# string

This is an expansion to the existing Lua String library.

Expansion Library

This is an expansion to builtins provided by Lua itself, see more about them on the official Lua/LuaJIT wikis.

# Format

%c - convert a number to a single character (like string.char)
%d and %i - output as an integer number
%o - convert to octal
%u - convert to an unsigned number
%x - hex (lower-case)
%X - hex (upper-case)
%e - scientific notation, "e" in lower case:
%E - scientific notation, "E" in upper case:
%f - floating point, default to 6 decimal places:
%g - Signed value printed in %f or %e format, whichever is more compact for the given value. To make it compact, only the required number of decimal places (if any) are shown.
%G - Same as %g except that an upper-case E is used where appropriate.
%q - formats a string in such a way Lua can read it back in (eg. as Lua source).
%s - output a string (or something that can be converted to a string, such as a number).
%% - output a single % character

# Patterns

 . --- (a dot) represents all characters. 
%a --- all letters. 
%c --- all control characters. 
%d --- all digits. 
%l --- all lowercase letters. 
%p --- all punctuation characters. 
%s --- all space characters. 
%u --- all uppercase letters. 
%w --- all alphanumeric characters. 
%x --- all hexadecimal digits. 
%z --- the character with hex representation 0x00 (null). 
%% --- a single '%' character.
%1 --- captured pattern 1.
%2 --- captured pattern 2 (and so on).
%f[s]  transition from not in set 's' to in set 's'.
%b()   balanced nested pair ( ... ( ... ) ... ) 

# Sets

[abc] ---> matches a, b or c
[a-z] ---> matches lowercase letters (same as %l)
[^abc] ---> matches anything except a, b or c
[%a%d] ---> matches all letters and digits
[%a%d_] ---> matches all letters, digits and underscore
[%[%]] ---> matches square brackets (had to escape them with %)

# Repetition

+  ---> 1 or more repetitions (greedy)
*  ---> 0 or more repetitions (greedy)
-  ---> 0 or more repetitions (non greedy)
?  ---> 0 or 1 repetition only

# Anchor

^  ---> anchor to start of subject string (must be the very first character)
$  ---> anchor to end of subject string   (must be the very last character)

# Special

(...) ---> captures the contents inside the parenthesis
print (string.find ("You see dogs and dogs", "You see (.*) and %1")) --> 1 21 dogs

# Functions

# string.byte(s: string, n?: number = 1): number


string.byte(s: string, n?: number = 1): number

Returns the ASCII code for the nth character of the string s. The inverse operation is carried out by string.char.

# string.char(...: number): string


string.char(...: number): string

Receives 0 or more numbers and converts them to the corresponding characters. The inverse operation is carried out by string.byte.

# string.dump(f: function): string


string.dump(f: function): string

Converts a function f into binary representation, which can be subsequently processed by loadstring to retrieve the function.
The function must be a Lua function without upvalues.

# string.find(str: string, pattern: string, index?: number = 1, plain?: boolean = false): number?, number?, ...?: string


string.find(str: string, pattern: string, index?: number = 1, plain?: boolean = false): number?, number?, ...?: string

Find the first match of the regular expression "pattern" in "str", starting at position "index".
The starting position (index) is optional, and defaults to 1 (the start of the string).
If found, returns the start and end position, and any captures as additional results.
If "plain" is true, the search string is plain text, not a regular expression. (The "plain" argument is optional, and defaults to false).

# string.format(fstr: string, ...: any): string


string.format(fstr: string, ...: any): string

Formats the supplied values (v1, v2 etc.) using format string 'fstr', similar to the C function printf.
It is an error to supply too few variables for the format string.
The format string comprises literal text, and directives starting with %. Each directive controls the format of the next argument.
Directives can include flags, width and precision controls.
To literally incorporate % in the output you need to put %% in the format string.

# string.gmatch(str: string, pattern: string): function


string.gmatch(str: string, pattern: string): function

Returns an iterator function for returning the next capture from a pattern over a string.
If there is no capture, the whole match is produced.

# string.gsub(str: string, pattern: string, replacement: string | function | table, n?: number): string, number


string.gsub(str: string, pattern: string, replacement: string | function | table, n?: number): string, number

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 %.
Also, %0 in the replacement pattern refers to the entire matching string.
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.

# string.len(str: string): number


string.len(str: string): number

Returns the length of the string, including any imbedded zero (0x00) bytes.

# string.lower(str: string): string


string.lower(str: string): string

Returns the string converted to lower-case.

# string.match(str: string, pattern: string, index?: number): ...string


string.match(str: string, pattern: string, index?: number): ...string

Find the first match of the regular expression "pattern" in "str", starting at position "index".
The starting position (index) is optional, and defaults to 1 (the start of the string).
If found, returns any captures in the pattern. If no captures were specified the entire matching string is returned.

# string.rep(str: string, n: number): string


string.rep(str: string, n: number): string

Returns a string which is n copies of the source string concatenated together.

# string.reverse(str: string): string


string.reverse(str: string): string

Returns a string that is the string str reversed.

# string.sub(str: string, start: number, end?: number): string


string.sub(str: string, start: number, end?: number): string

Returns a substring of the string, starting at index 'start' and ending at index 'end'. Both may be negative to indicate counting from the right. The end point is optional and defaults to -1, which is the entire rest of the string.

# string.upper(str: string): string


string.upper(str: string): string

Returns the string converted to upper-case.