Library string
Lua's (not glua's) string library
Functions
| byte( string, startIndex, endIndex ) | Returns the byte(s) in the given string between the given start and optional end index (inclusive). |
| char( ... ) | Returns a string constructed from the given bytes. |
| explode( string, delimiter, withPattern ) | Splits the given string based on the given delimiter. |
| find( string, pattern, init, plainText ) | Searches the given string for the given pattern, optionally from the given starting index. |
| format( format, ... ) | Returns a string built from the given format with the given values substituted into it. |
| gmatch( string, pattern ) | Returns an iterator over all matches of the given pattern within the given string. |
| gsub( string, pattern, replacement, max ) | Substitutes all matches of the given pattern within the given string with the given replacement value, or calls a function for each match if the replacement is a function. |
| len( string ) | Returns the length of the given string, in bytes (equivalent to #string). |
| lower( string ) | Returns a copy of the given string with all ASCII letters lower-cased. |
| match( string, pattern, init ) | Matches the given string against the given pattern, optionally from the given starting index. |
| rep( string, repetitions, separator ) | Returns the given string repeated the given number of times, optionally separated by the given separator. |
| reverse( string ) | Returns a copy of the given string with all bytes in reverse order. |
| sub( string, startIndex, endIndex ) | Returns a substring of the given string between the given start and optional end index (inclusive). |
| upper( string ) | Returns a copy of the given string with all ASCII letters upper-cased. |
Functions
- string.byte( string, startIndex, endIndex )
-
Returns the byte(s) in the given string between the given start and optional end index (inclusive).
Environment:
SharedParameters:
-
(string) string: The string to get the bytes from. -
(number?) startIndex: The index within the string to get the first byte from (default = 1). -
(number?) endIndex: The index within the string to get the last byte from (default = startIndex).
Return value:
(number...)A variable number of bytes, depending on the size of the given index range. -
- string.char( ... )
-
Returns a string constructed from the given bytes.
Environment:
SharedParameters:
-
(string...) ...: The bytes to construct the string from.
-
- string.explode( string, delimiter, withPattern )
-
Splits the given string based on the given delimiter.
Environment:
SharedParameters:
-
(string) string: The string to split. -
(string) delimiter: The delimiter to split the string by. -
(boolean?) withPattern: Whether the delimiter should be interpreted as a Lua pattern or not (default = false).
Usage:
-- This will print "comma" as it's the second value when splitting by ",". print( string.explode( "some,comma,separated,values", "," )[ 2 ] )
Return value:
(tableAn array containing the segments of the string split by the given delimiter.) -
- string.find( string, pattern, init, plainText )
-
Searches the given string for the given pattern, optionally from the given starting index. See the Lua manual for details on the pattern syntax.
Environment:
SharedParameters:
-
(string) string: The string to search. -
(string) pattern: The pattern to search for. -
(number?) init: An optional start index within the given string to begin the pattern search from (default = 1). -
(boolean?) plainText: An optional flag indicating whether to search for an exact value (true), or a pattern (false) (default = false).
Return values:
-
(number | nil)The index within the string at which the given pattern was found, or nil if the pattern was not found. -
(number | nil)The index within the string at which the given pattern match ended, or nil if the pattern was not found. -
(string...)A variable number of matched values, determined by the capture groups within the pattern.
-
- string.format( format, ... )
-
Returns a string built from the given format with the given values substituted into it.
Environment:
SharedParameters:
-
(string) format: The format definition to use to construct the output string. -
...: Values to be substituted based on the given format definition.
-
- string.gmatch( string, pattern )
-
Returns an iterator over all matches of the given pattern within the given string. The number of values in the iteration depend on the number of capture groups. See the Lua manual for details on the pattern syntax.
Environment:
SharedParameters:
-
(string) string: The string to iterate over. -
(string) pattern: The pattern to search for in the given string.
Return value:
(function)An iterator function that can be used in a for-loop to iterate over every match. -
- string.gsub( string, pattern, replacement, max )
-
Substitutes all matches of the given pattern within the given string with the given replacement value, or calls a function for each match if the replacement is a function. See the Lua manual for details on the pattern syntax.
Environment:
SharedParameters:
-
(string) string: The string to replace values within. -
(string) pattern: The pattern to find and replace. -
(string | function | table) replacement: If a string, all matches will be replaced with this value. If a table, any matches that have a key in the given table will be replaced with the value under that key. If a function, will be called for each match, passing the capture groups from the pattern as var-args, with a non-nil return value used as the replacement (returning nil will leave the value as-is). -
(number?) max: An optional limit on the number of replacements to perform before stopping (default = unlimited).
Usage:
-- Replace all matches with a fixed string (this prints "word word", 2). print( string.gsub( "test value", "%w+", "word" ) ) -- Replace all matches based on a table of values (this prints "first second", 2). print( string.gsub( "test value", "%w+", { test = "first", value = "second" } ) ) -- Replace all matches by upper casing using a function (this prints "TEST VALUE", 2). print( string.gsub( "test value", "%w+", string.upper ) )Return values:
-
(string)A copy of the given string with all matches of the given pattern (up to the given maximum) replaced. -
(number)The number of substitutions that were made.
-
- string.len( string )
-
Returns the length of the given string, in bytes (equivalent to #string).
Environment:
SharedParameters:
-
(string) string: The string to get the length of.
Return value:
(number)The length of the given string in bytes. -
- string.lower( string )
-
Returns a copy of the given string with all ASCII letters lower-cased.
Environment:
SharedParameters:
-
(string) string: The string to get a lower-case copy of.
-
- string.match( string, pattern, init )
-
Matches the given string against the given pattern, optionally from the given starting index. See the Lua manual for details on the pattern syntax.
Environment:
SharedParameters:
-
(string) string: The string to match against. -
(string) pattern: The pattern to match. -
(number?) init: An optional start index within the given string to begin the pattern match from (default = 1).
Return value:
(string...)A variable number of matched values if the pattern was matched, determined by the capture groups within the pattern. Otherwise nil if there was no match. -
- string.rep( string, repetitions, separator )
-
Returns the given string repeated the given number of times, optionally separated by the given separator.
Environment:
SharedParameters:
-
(string) string: The string to repeat. -
(number) repetitions: The number of times to repeat the given string. -
(string?) separator: An optional separator to add between each repetition (default = "").
-
- string.reverse( string )
-
Returns a copy of the given string with all bytes in reverse order.
Environment:
SharedParameters:
-
(string) string: The string to get a reversed copy of.
-
- string.sub( string, startIndex, endIndex )
-
Returns a substring of the given string between the given start and optional end index (inclusive).
Environment:
SharedParameters:
-
(string) string: The string to extract a substring from. -
(number) startIndex: The start index of the substring (where 1 is the first byte). May be negative to start from the end of the string (e.g. -1 is the last byte). -
(number?) endIndex: The end index of the substring (default = #string).
-
- string.upper( string )
-
Returns a copy of the given string with all ASCII letters upper-cased.
Environment:
SharedParameters:
-
(string) string: The string to get a upper-case copy of.
-