string.gsub
Lua function

string.gsub

Summary

Substitute strings inside another string

Prototype

s = string.gsub (str, pattern, replacement, n)


Description

Returns a copy of str with matches to 'pattern' replaced by 'replacement', for a maximum of n times.
As a second result it returns the number of matches made.

'replacement' can be a string in which case it simply replaces the matching pattern. However %1 through to %9 in the replacement pattern can refer to captured strings in the source pattern. %% becomes %.

If 'replacement' is a function it is called for each match with the matching string as an argument. It should return a string which is the string to replace it with. If it returns nil the original string is retained.

If 'replacement' is a table then the matching string is looked up in the table for each match, and if found, the replacement is substituted.

See string.find for an explanation of regular expressions.


string.gsub ("nick eats fish", "fish", "chips") --> nick eats chips

-- example of using a function as the replacement

replacements = { 
   ["nice"] = "windy",
   ["walk"] = "stroll",
   }
   
s = "a nice long walk"

result = string.gsub (s, "%a+", 
  function (str)
  return replacements [str]
  end
  )

print (result) --> a windy long stroll

-- An alternative way of doing a table replacement using the above table:

result = string.gsub (s, "%a+", replacements)

print (result) --> a windy long stroll

-- You can call inbuilt functions too:

s = "a nice long walk"

result = string.gsub (s, "%f[%a]%a%a", string.upper)

print (result) --> a NIce LOng WAlk


See Also ...

Topics

DOC_lua_base Lua base functions
DOC_lua_bc Lua bc (big number) functions
DOC_lua_bit Lua bit manipulation functions
DOC_lua_coroutines Lua coroutine functions
DOC_lua_debug Lua debug functions
DOC_lua_io Lua io functions
DOC_lua_math Lua math functions
DOC_lua_os Lua os functions
DOC_lua_package Lua package functions
DOC_lua_rex Lua PCRE regular expression functions
DOC_lua Lua script extensions
DOC_lua_string Lua string functions
DOC_lua_tables Lua table functions
DOC_lua_utils Lua utilities
DOC_regexp Regular Expressions
DOC_scripting Scripting

Lua functions

LUA_string.byte string.byte (Converts a character into its ASCII (decimal) equivalent)
LUA_string.char string.char (Converts ASCII codes into their equivalent characters)
LUA_string.dump string.dump (Converts a function into binary)
LUA_string.find string.find (Searches a string for a pattern)
LUA_string.format string.format (Formats a string)
LUA_string.gfind string.gfind (Iterate over a string (obsolete in Lua 5.1))
LUA_string.gmatch string.gmatch (Iterate over a string)
LUA_string.len string.len (Return the length of a string)
LUA_string.lower string.lower (Converts a string to lower-case)
LUA_string.match string.match (Searches a string for a pattern)
LUA_string.rep string.rep (Returns repeated copies of a string)
LUA_string.reverse string.reverse (Reverses the order of characters in a string)
LUA_string.sub string.sub (Returns a substring of a string)
LUA_string.upper string.upper (Converts a string to upper-case)

(Help topic: lua=string.gsub)

DOC_contents Documentation contents page