String.gsub: Difference between revisions

From GiderosMobile
No edit summary
No edit summary
 
(12 intermediate revisions by 2 users not shown)
Line 1: Line 1:
__NOTOC__
__NOTOC__
'''Available since:''' Gideros 2011.6<br/>
'''Available since:''' Gideros 2011.6<br/>
'''Class:''' [[string]]<br/>
=== Description ===
=== Description ===
<translate>Returns a copy of s in which all (or the first n, if given) occurrences of the pattern have been replaced by a replacement string specified by repl, which can be a string, a table, or a function. gsub also returns, as its second value, the total number of matches that occurred.  
Returns a copy of s in which all (or the first n, if given) occurrences of the pattern have been replaced by a replacement string specified by repl, which can be a string, a table, or a function. gsub also returns, as its second value, the total number of matches that occurred.
<syntaxhighlight lang="lua">
(string) = string.gsub(s,pat,repl,n)
</syntaxhighlight>


* If repl is a string, then its value is used for replacement. The character % works as an escape character: any sequence in repl of the form %n, with n between 1 and 9, stands for the value of the n-th captured substring (see below). The sequence %0 stands for the whole match. The sequence %% stands for a single %.
* If repl is a table, then the table is queried for every match, using the first capture as the key; if the pattern specifies no captures, then the whole match is used as the key.
* If repl is a function, then this function is called every time a match occurs, with all captured substrings passed as arguments, in order; if the pattern specifies no captures, then the whole match is passed as a sole argument.
* If the value returned by the table query or by the function call is a string or a number, then it is used as the replacement string; otherwise, if it is false or nil, then there is no replacement (that is, the original match is kept in the string).


If repl is a string, then its value is used for replacement. The character % works as an escape character: any sequence in repl of the form %n, with n between 1 and 9, stands for the value of the n-th captured substring (see below). The sequence %0 stands for the whole match. The sequence %% stands for a single %.
=== Parameters ===
'''s''': (string) string where to make replacements<br/>
'''pat''': (string) pattern what to replace<br/>
'''repl''': (varies) to what to replace<br/>
'''n''': (number) number of replacements '''optional'''<br/>


=== Return values ===
'''Returns''' (string) modified string with replacements<br/>


If repl is a table, then the table is queried for every match, using the first capture as the key; if the pattern specifies no captures, then the whole match is used as the key.
=== Examples ===
'''Simple examples:'''
<syntaxhighlight lang="lua">
local mystring = "hello, world!"
local newstring = string.gsub(mystring, "world", "mundo")
local newstring2 = mystring:gsub("world", "mundo") -- this is the same as above but shorter!
</syntaxhighlight>


<syntaxhighlight lang="lua">
local s = "Hello WORLD, hello world!"


If repl is a function, then this function is called every time a match occurs, with all captured substrings passed as arguments, in order; if the pattern specifies no captures, then the whole match is passed as a sole argument.
-- Replace "hello" or "HELLO" (any case) with "hi"
local result = string.gsub(s, "[Hh][Ee][Ll][Ll][Oo]", "hi")


print(result)  -- hi WORLD, hi world!
</syntaxhighlight>


If the value returned by the table query or by the function call is a string or a number, then it is used as the replacement string; otherwise, if it is false or nil, then there is no replacement (that is, the original match is kept in the string).  
'''Advanced examples:'''
<syntaxhighlight lang="lua">
x = string.gsub("hello world", "(%w+)", "%1 %1") -- x="hello hello world world"
x = string.gsub("hello world", "%w+", "%0 %0", 1) -- x="hello hello world"
x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1") -- x="world hello Lua from"
x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv) -- x="home = /home/roberto, user = roberto"
x = string.gsub("4%2B5 = $return 4%2B5$", "%$(.-)%$", function (s) return loadstring(s)() end) -- x="4%2B5 = 9"
local t = {name="lua", version="5.1"}''
x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t) -- x="lua-5.1.tar.gz"
</syntaxhighlight>


 
{{String}}
Here are some examples:
 
[[x = string.gsub("hello world", "(%w+)", "%1 %1") --> x="hello hello world world"]]
   
[[x = string.gsub("hello world", "%w+", "%0 %0", 1) --> x="hello hello world"]]
   
[[x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1") --> x="world hello Lua from"]]
   
[[x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv)]]
[[--> x="home = /home/roberto, user = roberto"]]
   
[[x = string.gsub("4%2B5 = $return 4%2B5$", "%$(.-)%$", function (s) return loadstring(s)() end) --> x="4%2B5 = 9"]]
<br/>
[[local t = {name="lua", version="5.1"}]]
[[x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t) --> x="lua-5.1.tar.gz"]]</translate>
<source lang="lua">
(string) = string.gsub(s,pat,repl,n)
</source>
=== Parameters ===
'''s''': (string) <translate>string where to make replacements</translate> <br/>
'''pat''': (string) <translate>pattern what to replace</translate> <br/>
'''repl''': (varies) <translate>to what to replace</translate> <br/>
'''n''': (number) <translate>number of replacements</translate> '''optional'''<br/>
=== Return values ===
'''Returns''' (string) <translate>modified string with replacements</translate><br/>

Latest revision as of 20:56, 30 August 2026

Available since: Gideros 2011.6
Class: string

Description

Returns a copy of s in which all (or the first n, if given) occurrences of the pattern have been replaced by a replacement string specified by repl, which can be a string, a table, or a function. gsub also returns, as its second value, the total number of matches that occurred.

(string) = string.gsub(s,pat,repl,n)
  • If repl is a string, then its value is used for replacement. The character % works as an escape character: any sequence in repl of the form %n, with n between 1 and 9, stands for the value of the n-th captured substring (see below). The sequence %0 stands for the whole match. The sequence %% stands for a single %.
  • If repl is a table, then the table is queried for every match, using the first capture as the key; if the pattern specifies no captures, then the whole match is used as the key.
  • If repl is a function, then this function is called every time a match occurs, with all captured substrings passed as arguments, in order; if the pattern specifies no captures, then the whole match is passed as a sole argument.
  • If the value returned by the table query or by the function call is a string or a number, then it is used as the replacement string; otherwise, if it is false or nil, then there is no replacement (that is, the original match is kept in the string).

Parameters

s: (string) string where to make replacements
pat: (string) pattern what to replace
repl: (varies) to what to replace
n: (number) number of replacements optional

Return values

Returns (string) modified string with replacements

Examples

Simple examples:

local mystring = "hello, world!"
local newstring = string.gsub(mystring, "world", "mundo")
local newstring2 = mystring:gsub("world", "mundo") -- this is the same as above but shorter!
local s = "Hello WORLD, hello world!"

-- Replace "hello" or "HELLO" (any case) with "hi"
local result = string.gsub(s, "[Hh][Ee][Ll][Ll][Oo]", "hi")

print(result)  -- hi WORLD, hi world!

Advanced examples:

x = string.gsub("hello world", "(%w+)", "%1 %1") -- x="hello hello world world"
x = string.gsub("hello world", "%w+", "%0 %0", 1) -- x="hello hello world"
x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1") -- x="world hello Lua from"
x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv) -- x="home = /home/roberto, user = roberto"
x = string.gsub("4%2B5 = $return 4%2B5$", "%$(.-)%$", function (s) return loadstring(s)() end) -- x="4%2B5 = 9"
local t = {name="lua", version="5.1"}''
x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t) -- x="lua-5.1.tar.gz"