string.byte
string.char
string.dump
string.find
string.format
string.gmatch
string.gsub
string.len
string.lower
string.match
string.rep
string.reverse
string.sub
string.upper
Patterns
string - string manipulation functions (standard library)
This library provides generic functions for string manipulation, such as finding and extracting substrings, and pattern matching. When indexing a string in Lua, the first character is at position 1 (not at 0, as in C). Indices are allowed to be negative and are interpreted as indexing backwards, from the end of the string. Thus, the last character is at position -1, and so on.
The string library provides all its functions inside the table
string
. It also sets a metatable for strings where the __index
field points to the string
table. Therefore, you can use the
string functions in object-oriented style. For instance,
string.byte(s, i)
can be written as s:byte(i)
.
string.byte
string.byte (s [, i [, j]])
Returns the internal numerical codes of the characters s[i]
,
s[i+1]
, ···, s[j]
. The default value
for i
is 1; the default value for j
is i
.
Note that numerical codes are not necessarily portable across platforms.
string.char
string.char (...)
Receives zero or more integers. Returns a string with length equal to the number of arguments, in which each character has the internal numerical code equal to its corresponding argument.
Note that numerical codes are not necessarily portable across platforms.
string.dump
string.dump (function)
Returns a string containing a binary representation of the given
function, so that a later loadstring
on this string returns a copy
of the function. function
must be a Lua function without upvalues.
string.find
string.find (s, pattern [, init [, plain]])
Looks for the first match of pattern
in the string s
. If it
finds a match, then find
returns the indices of s
where this
occurrence starts and ends; otherwise, it returns nil
. A third,
optional numerical argument init
specifies where to start the
search; its default value is 1 and may be negative. A value of
true
as a fourth, optional argument plain
turns off the pattern
matching facilities, so the function does a plain ``find substring''
operation, with no characters in pattern
being considered ``magic''.
Note that if plain
is given, then init
must be given as well.
If the pattern has captures, then in a successful match the captured values are also returned, after the two indices.
string.format
string.format (formatstring, ...)
Returns a formatted version of its variable number of arguments
following the description given in its first argument (which must be a
string). The format string follows the same rules as the printf
family of standard C functions. The only differences are that the
options/modifiers *
, l
, L
, n
, p
, and h
are not
supported and that there is an extra option, q
. The q
option
formats a string in a form suitable to be safely read back by the Lua
interpreter: the string is written between double quotes, and all
double quotes, newlines, embedded zeros, and backslashes in the string
are correctly escaped when written. For instance, the call
string.format('%q', 'a string with "quotes" and \n new line')
will produce the string:
"a string with \"quotes\" and \ new line"
The options c
, d
, E
, e
, f
, g
, G
, i
, o
,
u
, X
, and x
all expect a number as argument, whereas q
and
s
expect a string.
This function does not accept string values containing embedded zeros.
string.gmatch
string.gmatch (s, pattern)
Returns an iterator function that, each time it is called, returns the
next captures from pattern
over string s
.
If pattern
specifies no captures, then the whole match is produced
in each call.
As an example, the following loop
s = "hello world from Lua" for w in string.gmatch(s, "%a+") do print(w) end
will iterate over all the words from string s
, printing one per
line. The next example collects all pairs key=value
from the given
string into a table:
t = {} s = "from=world, to=Lua" for k, v in string.gmatch(s, "(%w+)=(%w+)") do t[k] = v end
string.gsub
string.gsub (s, pattern, repl [, n])
Returns a copy of s
in which all occurrences of the pattern
have
been replaced by a replacement string specified by repl
, which may
be a string, a table, or a function. gsub
also returns, as its
second value, the total number of substitutions made.
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).
The optional last parameter n
limits the maximum number of
substitutions to occur. For instance, when n
is 1 only the first
occurrence of pattern
is replaced.
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+5 = $return 4+5$", "%$(.-)%$", function (s) return loadstring(s)() end) --> x="4+5 = 9" local t = {name="lua", version="5.1"} x = string.gsub("$name%-$version.tar.gz", "%$(%w+)", t) --> x="lua-5.1.tar.gz"
string.len
string.len (s)
Receives a string and returns its length. The empty string ""
has
length 0. Embedded zeros are counted, so "a\000bc\000"
has length
5.
string.lower
string.lower (s)
Receives a string and returns a copy of this string with all uppercase letters changed to lowercase. All other characters are left unchanged. The definition of what an uppercase letter is depends on the current locale.
string.match
string.match (s, pattern [, init])
Looks for the first match of pattern
in the string s
.
If it finds one, then match
returns the captures from the pattern;
otherwise it returns nil
. If pattern
specifies no captures,
then the whole match is returned. A third, optional numerical
argument init
specifies where to start the search; its default
value is 1 and may be negative.
string.rep
string.rep (s, n)
Returns a string that is the concatenation of n
copies of
the string s
.
string.reverse
string.reverse (s)
Returns a string that is the string s
reversed.
string.sub
string.sub (s, i [, j])
Returns the substring of s
that starts at i
and continues until
j
; i
and j
may be negative. If j
is absent, then it is
assumed to be equal to -1 (which is the same as the string length).
In particular, the call string.sub(s,1,j)
returns a prefix of s
with length j
, and string.sub(s,-i)
returns a suffix of s
with length i
.
string.upper
string.upper (s)
Receives a string and returns a copy of this string with all lowercase letters changed to uppercase. All other characters are left unchanged. The definition of what a lowercase letter is depends on the current locale.
Patterns
Character Class
A character class is used to represent a set of characters. The following combinations are allowed in describing a character class:
x
^$()%.[]*+-?
)
represents the character x itself.
.
%a
%c
%d
%l
%p
%s
%u
%w
%x
%z
%x
%
' when used to represent itself in a pattern.
[set]
-
'. All classes
%
x described above may also be used as components in
set. All other characters in set represent
themselves. For example, [%w_]
(or [_%w]
) represents all
alphanumeric characters plus the underscore, [0-7]
represents the
octal digits, and [0-7%l%-]
represents the octal digits plus the
lowercase letters plus the '-
' character.
The interaction between ranges and classes is not defined. Therefore,
patterns like [%a-z]
or [a-%%]
have no meaning.
[^set]
For all classes represented by single letters (%a
, %c
, etc.),
the corresponding uppercase letter represents the complement of the
class. For instance, %S
represents all non-space characters.
The definitions of letter, space, and other character groups depend on
the current locale. In particular, the class [a-z]
may not be
equivalent to %l
.
A pattern item may be
*
', which matches 0 or more
repetitions of characters in the class. These repetition items will
always match the longest possible sequence;
+
', which matches 1 or more
repetitions of characters in the class. These repetition items will
always match the longest possible sequence;
-
', which also matches 0 or
more repetitions of characters in the class. Unlike '*
', these
repetition items will always match the shortest possible
sequence;
?
', which matches 0 or 1
occurrence of a character in the class;
%n
, for n between 1 and 9; such item matches a
substring equal to the n-th captured string (see below);
%bxy
, where x and y are two distinct
characters; such item matches strings that start with x, end
with y, and where the x and y are
balanced. This means that, if one reads the string from left
to right, counting +1 for an x and -1 for a
y, the ending y is the first y where the
count reaches 0. For instance, the item %b()
matches expressions
with balanced parentheses.
^
' at the beginning of a pattern anchors the match at the
beginning of the subject string.
$
' at the end of a pattern anchors the match at the end of the
subject string. At other positions,
^
' and '$
' have no special meaning and represent themselves.
A pattern may contain sub-patterns enclosed in parentheses; they
describe captures. When a match succeeds, the substrings of
the subject string that match captures are stored (captured)
for future use. Captures are numbered according to their left
parentheses. For instance, in the pattern "(a*(.)%w(%s*))"
, the
part of the string matching "a*(.)%w(%s*)"
is stored as the first
capture (and therefore has number 1); the character matching ``.
'' is
captured with number 2, and the part matching ``%s*
'' has number 3.
As a special case, the empty capture ()
captures the current string
position (a number). For instance, if we apply the pattern
"()aa()"
on the string "flaaap"
, there will be two captures: 3
and 5.
A pattern cannot contain embedded zeros. Use %z
instead.
This is Lua version 5.1.1.
Lua is developed at Lua.org, a laboratory of the Department of Computer Science of PUC-Rio (the Pontifical Catholic University of Rio de Janeiro in Brazil). For more information about the authors, see http://www.lua.org/authors.html .
Lua is licensed under the terms of the MIT license reproduced below. This means that Lua is free software and can be used for both academic and commercial purposes at absolutely no cost.
For details and rationale, see http://www.lua.org/license.html .
~~~~~
Copyright (C) 1994-2006 Lua.org, PUC-Rio.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the ``Software''), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED ``AS IS'', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
~~~~~