util.string.gsub

Syntax

local result, count = util.string.gsub(
    input,
    pattern,
    replacement,
    max_replacements = nil
)

Parameters

Type	Name	Description
`string`	input	String to convert
`string`	pattern	Lua pattern to find
`string`, `table` or `function`	replacement	Replacement string, table, or function
`int`	max_replacements	Maximum number of replacements to make

Returns

Type	Name	Description
`string`	result	Altered string with replacements
`int`	count	Number of substitutions that occurred

Examples

Simple text replacement

local result, count = util.string.gsub("hello world", "world", "Lua")

core.engine.print("info", result) -- 'hello Lua'
core.engine.print("info", count) -- 1

Replace all occurrences

local result = util.string.gsub("aaa", "a", "b")

core.engine.print("info", result) -- 'bbb'

Limit the number of replacements

local result, count = util.string.gsub("aaa", "a", "b", 2)

core.engine.print("info", result) -- 'bba'
core.engine.print("info", count) -- 2

Replace using a pattern

local result = util.string.gsub("hello world", "%a+", "word")

core.engine.print("info", result) -- 'word word'

Remove all spaces from a string

local result = util.string.gsub("h e l l o", " ", "")

core.engine.print("info", result) -- 'hello'

Replace all digits with a placeholder

local result = util.string.gsub("call 555-1234", "%d", "X")

core.engine.print("info", result) -- 'call XXX-XXXX'

Capture and reuse groups in replacement

local result = util.string.gsub("hello world", "(%a+)", "<%1>")

core.engine.print("info", result) -- '<hello> <world>'

Swap two words using captures

local result = util.string.gsub("first second", "(%a+) (%a+)", "%2 %1")

core.engine.print("info", result) -- 'second first'

Use a function to transform matches

local result = util.string.gsub("I have 2 apples and 3 oranges", "%d+", function(n)
    return tonumber(n)*2
end)

core.engine.print("info", result) -- 'I have 4 apples and 6 oranges'

Use a table to map replacements

local replacements = {
    hello = "goodbye",
    world = "moon"
}
local result = util.string.gsub("hello world", "%a+", replacements)

core.engine.print("info", result) -- 'goodbye moon'

Capitalize the first letter of each word

local result = util.string.gsub("hello world from lua", "%a+", function(word)
    return util.string.upper(util.string.sub(word, 1, 1))..util.string.sub(word, 2)
end)

core.engine.print("info", result) -- 'Hello World From Lua'

Strip HTML tags from a string

local html = "<p>Hello <b>world</b></p>"
local result = util.string.gsub(html, "<[^>]+>", "")

core.engine.print("info", result) -- 'Hello world'

Escape special characters

local result = util.string.gsub("cost: $5.00", "%$", "USD ")

core.engine.print("info", result) -- 'cost: USD 5.00'

Convert snake_case to camelCase

local result = util.string.gsub("my_variable_name", "_(%a)", function(letter)
    return util.string.upper(letter)
end)

core.engine.print("info", result) -- 'myVariableName'

Return original string when pattern is not found

local result, count = util.string.gsub("hello", "xyz", "abc")

core.engine.print("info", result) -- 'hello'
core.engine.print("info", count) -- 0

Syntax

Parameters

Returns

Examples

On this page