=head1 NAME

string - string manipulation functions (standard library)

=head1 OVERVIEW

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
C<string>.  It also sets a metatable for strings where the C<__index>
field points to the C<string> table.  Therefore, you can use the
string functions in object-oriented style.  For instance,
L</string.byte>C<(s, i)> can be written as L<s:byte|/string.byte>C<(i)>.

=head1 REFERENCE

=head2 C<string.byte>

  string.byte (s [, i [, j]])

Returns the internal numerical codes of the characters C<s[i]>,
C<s[i+1]>, E<middot>E<middot>E<middot>, C<s[j]>.  The default value
for C<i> is 1; the default value for C<j> is C<i>.

Note that numerical codes are not necessarily portable across platforms.

=head2 C<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.

=head2 C<string.dump>

  string.dump (function)

Returns a string containing a binary representation of the given
function, so that a later C<loadstring> on this string returns a copy
of the function.  C<function> must be a Lua function without upvalues.

=head2 C<string.find>

  string.find (s, pattern [, init [, plain]])

Looks for the first match of C<pattern> in the string C<s>.  If it
finds a match, then C<find> returns the indices of C<s> where this
occurrence starts and ends; otherwise, it returns C<nil>.  A third,
optional numerical argument C<init> specifies where to start the
search; its default value is 1 and may be negative.  A value of
C<true> as a fourth, optional argument C<plain> turns off the pattern
matching facilities, so the function does a plain "find substring"
operation, with no characters in C<pattern> being considered "magic".
Note that if C<plain> is given, then C<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.

=head2 C<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 C<printf>
family of standard C functions.  The only differences are that the
options/modifiers C<*>, C<l>, C<L>, C<n>, C<p>, and C<h> are not
supported and that there is an extra option, C<q>.  The C<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<c>, C<d>, C<E>, C<e>, C<f>, C<g>, C<G>, C<i>, C<o>,
C<u>, C<X>, and C<x> all expect a number as argument, whereas C<q> and
C<s> expect a string.

This function does not accept string values containing embedded zeros.

=head2 C<string.gmatch>

  string.gmatch (s, pattern)

Returns an iterator function that, each time it is called, returns the
next captures from C<pattern> over string C<s>.

If C<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 C<s>, printing one per
line.  The next example collects all pairs C<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

=head2 C<string.gsub>

  string.gsub (s, pattern, repl [, n])

Returns a copy of C<s> in which all occurrences of the C<pattern> have
been replaced by a replacement string specified by C<repl>, which may
be a string, a table, or a function.  C<gsub> also returns, as its
second value, the total number of substitutions made.

If C<repl> is a string, then its value is used for replacement.  The
character C<%> works as an escape character: any sequence in C<repl>
of the form C<%>I<n>, with I<n> between 1 and 9, stands
for the value of the I<n>-th captured substring (see below).
The sequence C<%0> stands for the whole match.  The sequence C<%%>
stands for a single C<%>.

If C<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 C<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 C<false> or C<nil>, then there is no replacement
(that is, the original match is kept in the string).

The optional last parameter C<n> limits the maximum number of
substitutions to occur.  For instance, when C<n> is 1 only the first
occurrence of C<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"

=head2 C<string.len>

  string.len (s)

Receives a string and returns its length.  The empty string C<""> has
length 0.  Embedded zeros are counted, so C<"a\000bc\000"> has length
5.

=head2 C<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.

=head2 C<string.match>

  string.match (s, pattern [, init])

Looks for the first I<match> of C<pattern> in the string C<s>.
If it finds one, then C<match> returns the captures from the pattern;
otherwise it returns C<nil>.  If C<pattern> specifies no captures,
then the whole match is returned.  A third, optional numerical
argument C<init> specifies where to start the search; its default
value is 1 and may be negative.

=head2 C<string.rep>

  string.rep (s, n)

Returns a string that is the concatenation of C<n> copies of
the string C<s>.


=head2 C<string.reverse>

  string.reverse (s)

Returns a string that is the string C<s> reversed.

=head2 C<string.sub>

  string.sub (s, i [, j])

Returns the substring of C<s> that starts at C<i> and continues until
C<j>; C<i> and C<j> may be negative.  If C<j> is absent, then it is
assumed to be equal to -1 (which is the same as the string length).
In particular, the call C<string.sub(s,1,j)> returns a prefix of C<s>
with length C<j>, and C<string.sub(s,-i)> returns a suffix of C<s>
with length C<i>.


=head2 C<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.

=head2 C<Patterns>

=head3 C<Character Class>

A I<character class> is used to represent a set of characters.  The
following combinations are allowed in describing a character class:

=over 4

=item C<x>

(where I<x> is not one of the I<magic characters> C<^$()%.[]*+-?>)
represents the character I<x> itself.

=item C<.>

(a dot) represents all characters.

=item C<%a>

represents all letters.

=item C<%c>

represents all control characters.

=item C<%d>

represents all digits.

=item C<%l>

represents all lowercase letters.

=item C<%p>

represents all punctuation characters.

=item C<%s>

represents all space characters.

=item C<%u>

represents all uppercase letters.

=item C<%w>

represents all alphanumeric characters.

=item C<%x>

represents all hexadecimal digits.

=item C<%z>

represents the character with representation 0.

=item C<%x>

(where I<x> is any non-alphanumeric character) represents the
character I<x>.  This is the standard way to escape the magic
characters.  Any punctuation character (even the non magic) can be
preceded by a 'C<%>' when used to represent itself in a pattern.

=item C<[set]>

represents the class which is the union of all characters in
I<set>.  A range of characters may be specified by separating
the end characters of the range with a 'C<->'.  All classes
C<%>I<x> described above may also be used as components in
I<set>.  All other characters in I<set> represent
themselves.  For example, C<[%w_]> (or C<[_%w]>) represents all
alphanumeric characters plus the underscore, C<[0-7]> represents the
octal digits, and C<[0-7%l%-]> represents the octal digits plus the
lowercase letters plus the 'C<->' character.

The interaction between ranges and classes is not defined.  Therefore,
patterns like C<[%a-z]> or C<[a-%%]> have no meaning.

=item C<[^set]>

represents the complement of I<set>, where I<set> is
interpreted as above.

=back

For all classes represented by single letters (C<%a>, C<%c>, etc.),
the corresponding uppercase letter represents the complement of the
class.  For instance, C<%S> represents all non-space characters.

The definitions of letter, space, and other character groups depend on
the current locale.  In particular, the class C<[a-z]> may not be
equivalent to C<%l>.

=head3 Pattern Item:

A I<pattern item> may be

=over 4

=item

a single character class, which matches any single character in the
class;

=item

a single character class followed by 'C<*>', which matches 0 or more
repetitions of characters in the class.  These repetition items will
always match the longest possible sequence;

=item

a single character class followed by 'C<+>', which matches 1 or more
repetitions of characters in the class.  These repetition items will
always match the longest possible sequence;

=item

a single character class followed by 'C<->', which also matches 0 or
more repetitions of characters in the class.  Unlike 'C<*>', these
repetition items will always match the I<shortest> possible
sequence;

=item

a single character class followed by 'C<?>', which matches 0 or 1
occurrence of a character in the class;

=item

C<%I<n>>, for I<n> between 1 and 9; such item matches a
substring equal to the I<n>-th captured string (see below);

=item

C<%bI<xy>>, where I<x> and I<y> are two distinct
characters; such item matches strings that start with I<x>, end
with I<y>, and where the I<x> and I<y> are
I<balanced>.  This means that, if one reads the string from left
to right, counting I<+1> for an I<x> and I<-1> for a
I<y>, the ending I<y> is the first I<y> where the
count reaches 0.  For instance, the item C<%b()> matches expressions
with balanced parentheses.

=back

=head3 Pattern:

=over 4

=item

A I<pattern> is a sequence of pattern items.

=item

A 'C<^>' at the beginning of a pattern anchors the match at the
beginning of the subject string.

=item

A 'C<$>' at the end of a pattern anchors the match at the end of the
subject string.  At other positions,

=item

'C<^>' and 'C<$>' have no special meaning and represent themselves.

=back

=head3 Captures

A pattern may contain sub-patterns enclosed in parentheses; they
describe I<captures>.  When a match succeeds, the substrings of
the subject string that match captures are stored (I<captured>)
for future use.  Captures are numbered according to their left
parentheses.  For instance, in the pattern C<"(a*(.)%w(%s*))">, the
part of the string matching C<"a*(.)%w(%s*)"> is stored as the first
capture (and therefore has number 1); the character matching "C<.>" is
captured with number 2, and the part matching "C<%s*>" has number 3.

As a special case, the empty capture C<()> captures the current string
position (a number).  For instance, if we apply the pattern
C<"()aa()"> on the string C<"flaaap">, there will be two captures: 3
and 5.

A pattern cannot contain embedded zeros.  Use C<%z> instead.

=head1 VERSION

This is Lua version 5.1.1.

=head1 CREDITS

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 .

=head1 LICENSE

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.

~~~~~