AddOn Studio Wiki

WoW Lua

string.gsub(s, pattern, replace [, n])
gsub(s, pattern, replace [, n])
strreplace(s, pattern, replace [, n])

This is a very powerful function and can be used in multiple ways. Used simply it can replace all instances of the pattern provided with the replacement. A pair of values is returned, the modified string and the number of substitutions made. The optional fourth argument n can be used to limit the number of substitutions made:

> = string.gsub("Hello banana", "banana", "Lua user")
Hello Lua user  1
> = string.gsub("banana", "a", "A", 2)  -- limit substitutions made to 2
bAnAna  2

If a capture is used this can be referenced in the replacement string using the notation %capture_index, e.g.,

> = string.gsub("banana", "(an)", "%1-")    -- capture any occurances of "an" and replace
ban-an-a        2
> = string.gsub("banana", "a(n)", "a(%1)")  -- brackets around n's which follow a's
ba(n)a(n)a      2
> = string.gsub("banana", "(a)(n)", "%2%1") -- reverse any "an"s
bnanaa  2

If the replacement is a function, not a string, the arguments passed to the function are any captures that are made. If the function returns a string, the value returned is substituted back into the string. Just like string.find() we can use regular expressions to search in strings. Patterns are covered in the Patterns Tutorial on, and the pattern matching HOWTO.

> = string.gsub("Hello Lua user", "(%w+)", print)  -- print any words found
> = string.gsub("Hello Lua user", "(%w+)", function(w) return string.len(w) end) -- replace with lengths
5 3 4   3
> = string.gsub("banana", "(a)", string.upper)     -- make all "a"s found uppercase
bAnAnA  3
> = string.gsub("banana", "(a)(n)", function(a,b) return b..a end) -- reverse any "an"s
bnanaa  2