Manual:String Functions

String Functions

string.byte, utf8.byte

string.byte(string [, i [, j]]) or utf8.byte(string [, i [, j]])

mystring:byte([, 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.byte() works with English text only, use utf8.byte() for the international version.

See also: string.char, utf8.char

Example

<syntaxhighlight lang="lua"> -- the following call will return the ASCII values of "A", "B" and "C" a, b, c = string.byte("ABC", 1, 3) echo(a .. " - " .. b .. " - " .. c) -- shows "65 - 66 - 67"

-- same for the international version but with the Unicode values a, b, c = utf8.byte("дом", 1, 3) echo(a .. " - " .. b .. " - " .. c) -- shows "1076 - 1086 - 1084" </lua>

string.char, utf8.char

string.char(···) or utf8.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.char() works with English text only, use utf8.char() for the international version.

See also: string.byte, utf8.byte

Example

<syntaxhighlight lang="lua"> -- the following call will return the string "ABC" corresponding to the ASCII values 65, 66, 67 mystring = string.char(65, 66, 67)

-- same for the infernational version which will return text "дом" for the Unicode values 1076, 1086, 1084 mystring = utf8.char(1076,1086,1084) print(mystring) </lua>

string.cut

string.cut(string, maxLen)

Cuts string to the specified maximum length.

Returns the modified string.

Parameters

• string:

The text you wish to cut. Passed as a string.

• maxLen:

The maximum length you wish the string to be. Passed as an integer number.

Example

<syntaxhighlight lang="lua"> --The following call will return 'abc' and store it in myString mystring = string.cut("abcde", 3) --You can easily pad string to certain length. Example below will print 'abcde ' e.g. pad/cut string to 10 characters. local s = "abcde" s = string.cut(s .. " ", 10) -- append 10 spaces echo("'" .. s .. "'") </lua>

string.dump

string.dump()

Converts a function into a binary string. You can use the loadstring() function later to get the function back.

string.dump() works with both English and non-English text fine.

Example

<syntaxhighlight lang="lua"> string = string.dump(echo("this is a string")) --The following should then echo "this is a string" loadstring(string)() </lua>

string.enclose

string.enclose(String)

Wraps a string with [[ ]]

Returns the altered string.

Parameters

• String:

The string to enclose. Passed as a string.

Example

<syntaxhighlight lang="lua"> --This will echo 'Oh noes!' to the main window echo("'" .. string.enclose("Oh noes!") .. "'") </lua>

string.ends

string.ends(String, Suffix)

Test if string is ending with specified suffix.

Returns true or false.

See also: string.starts

Parameters

• String:

The string to test. Passed as a string.

• Suffix:

The suffix to test for. Passed as a string.

Example

<syntaxhighlight lang="lua"> --This will test if the incoming line ends with "in bed" and if not will add it to the end. if not string.ends(line, "in bed") then

 echo("in bed\n")

end </lua>

string.find, utf8.find

string.find() or utf8.find

Need description

string.find() works with English text only, use utf8.find() for the international version.

Example

Need example

string.findPattern

string.findPattern(text, pattern)

Return first matching substring or nil.

Parameters

• text:

The text you are searching the pattern for.

• pattern:

The pattern you are trying to find in the text.

Example

Following example will print: "I did find: Troll" string. <syntaxhighlight lang="lua"> local match = string.findPattern("Troll is here!", "Troll") if match then

  echo("I did find: " .. match)

end </lua>

This example will find substring regardless of case.

<lua>local match = string.findPattern("Troll is here!", string.genNocasePattern("troll")) if match then

   echo("I did find: " .. match)

end </lua>

• Return value:

nil or first matching substring

See also: string.genNocasePattern()

string.format

string.format()

Need description here.

string.format() works with both English and non-English text fine.

Example

Need example

string.genNocasePattern

string.genNocasePattern(s)

Generate case insensitive search pattern from string.

Parameters

• s:

Example

Following example will generate and print "123[aA][bB][cC]" string.

<lua>echo(string.genNocasePattern("123abc"))</lua>

• Return value:

case insensitive pattern string

string.gfind

string.gfind()

Need description here.

Example

Need example

string.gmatch, utf8.gmatch

string.gmatch() or utf8.gmatch

Need description here.

string.gmatch() works with English text only, use utf8.gmatch() for the international version.

Example

Need example

string.gsub, utf8.gsub

string.gsub() or utf8.gsub

Need description here.

string.gsub() works with English text only, use utf8.gsub() for the international version.

Example

Need example

string.len, utf8.len

string.len(string) or utf8.len(string)

mystring:len()

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.len() works with English text only, use utf8.len() for the international version.

Parameters

• string:

The string (text) you want to find the length of.

Example

<syntaxhighlight lang="lua"> -- prints 5 for the 5 letters in our word print(string.len("hello"))

-- international version print(utf8.len("слово")) </lua>

string.lower, utf8.lower

string.lower(string) or utf8.lower(string)

mystring:lower()

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.lower() works with English text only, use utf8.lower() for the international version.

See also: string.upper, utf8.upper

Example

<syntaxhighlight lang="lua"> -- prints an all-lowercase version print(string.lower("No way! This is AWESOME!"))

-- international version print(utf8.lower("Класс! Ето ОТЛИЧНО!")) </lua>

string.match, utf8.match

string.match() or utf8.match()

Need description here.

string.match() works with English text only, use utf8.match() for the international version.

Example

Need example

string.rep

string.rep(String, n)

mystring:rep(n)

Returns a string that is the concatenation of n copies of the string String.

string.rep() works with both English and non-English text fine.

Example

Need example

string.reverse, utf8.reverse

string.reverse(string), utf8.reverse(string)

mystring:reverse()

Returns a string that is the string string reversed.

string.reverse() works with English text only, use utf8.reverse() for the international version.

Parameters

• string:

The string to reverse. Passed as a string.

Example

<syntaxhighlight lang="lua"> mystring = "Hello from Lua" echo(mystring:reverse()) -- displays 'auL morf olleH'

-- international version. mystring = "Привет от Луа!" echo(utf8.reverse(mystring)) -- displays '!ауЛ то тевирП', which probably looks the same to you </lua>

string.split

string.split(string, delimiter)

myString:split(delimiter)

Splits a string into a table by the given delimiter. Can be called against a string (or variable holding a string) using the second form above.

Returns a table containing the split sections of the string.

Parameters

• string:

The string to split. Parameter is not needed if using second form of the syntax above. Passed as a string.

• delimiter:

The delimiter to use when splitting the string. Passed as a string, and allows for Lua pattern types. Use % to escape here (and %% to escape a stand-alone %).

Example

<syntaxhighlight lang="lua"> -- This will split the string by ", " delimiter and print the resulting table to the main window. names = "Alice, Bob, Peter" name_table = string.split(names, ", ") display(name_table)

--The alternate method names = "Alice, Bob, Peter" name_table = names:split(", ") display(name_table) </lua>

Either method above will print out:

table {

1: 'Alice'

2: 'Bob'

3: 'Peter'

}

string.starts

string.starts(string, prefix)

Test if string is starting with specified prefix.

Returns true or false

See also: string.ends

Parameters

• string:

The string to test. Passed as a string.

• prefix:

The prefix to test for. Passed as a string.

Example

<syntaxhighlight lang="lua"> --The following will see if the line begins with "You" and if so will print a statement at the end of the line if string.starts(line, "You") then

 echo("====oh you====\n")

end </lua>

string.sub, utf8.sub

string.sub() or utf8.sub()

Need description here.

string.sub() works with English text only, use utf8.sub() for the international version.

Example

Need example

string.title

string.title(string)

string:title()

Capitalizes the first character in a string.

Returns the altered string.

Parameters

• string:

The string to modify. Not needed if you use the second form of the syntax above.

Example

<syntaxhighlight lang="lua"> --Variable testname is now Anna. testname = string.title("anna") --Example will set test to "Bob". test = "bob" test = test:title() </lua>

string.trim

string.trim(string)

Trims string, removing all 'extra' white space at the beginning and end of the text.

Returns the altered string.

Parameters

• string:

The string to trim. Passed as a string.

Example

<syntaxhighlight lang="lua"> --This will print 'Troll is here!', without the extra spaces. local str = string.trim(" Troll is here! ") echo("'" .. str .. "'") </lua>

string.upper, utf8.upper

string.upper(string) or utf8.upper(string)

mystring:upper()

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.

string.upper() works with English text only, use utf8.upper() for the international version.

See also: string.lower, utf8.lower

Parameters

• string:

The string you want to change to uppercase

Example

<syntaxhighlight lang="lua"> -- displays 'RUN BOB RUN' print(string.upper("run bob run"))

-- displays 'ДАВАЙ ДАВАЙ!' print(utf8.upper("давай давай!")) </lua>

utf8.charpos

utf8.charpos(string[[, charpos], offset])

Converts UTF-8 position to byte offset, returns the character position and code point. If only offset is given, returns byte offset of this UTF-8 char index. If charpos and offset is given, a new charpos will be calculated by adding/subtracting UTF-8 char offset to current charpos. In all cases, it return a new char position, and code point (a number) at this position.

Parameters

• string:

The input string to work on.

• charpos:

(optional) character position to work on.

• offset:

(optional) offset (as a number) to work on.

utf8.escape

utf8.escape(string)

Escape a string to UTF-8 format string. It support several escape formats:

%ddd - which ddd is a decimal number at any length:

      change Unicode code point to UTF-8 format.

%{ddd} - same as %nnn but has bracket around. %uddd - same as %ddd, u stands Unicode %u{ddd} - same as %{ddd} %xhhh - hexadigit version of %ddd %x{hhh} same as %xhhh. %? - '?' stands for any other character: escape this character.

Parameters

• string:

The string you want to escape

Example

<syntaxhighlight lang="lua"> local u = utf8.escape print(u"%123%u123%{123}%u{123}%xABC%x{ABC}") print(u"%%123%?%d%%u") </lua>

utf8.fold

utf8.fold(string)

Returns the lowercase version of the string for use in case-insensitive comparisons. If string is a number, it's treated as a code point and the converted code point is returned (as a number).

Parameters

• string:

The string to lowercase.

Example

<syntaxhighlight lang="lua"> print(utf8.fold("ПРИВЕТ")) -- 'привет' print(utf8.fold("Привет")) -- 'привет' </lua>

utf8.insert

utf8.insert(string[, idx], substring)

Inserts the substring into the given string. If idx is given, inserts substring before the character at this index, otherwise the substring will append onto the end of string. idx can be negative.

Parameters

• string:

The input string to work on.

• idx:

(optional) character position to insert the string at.

• substring:

text to insert into the substring.

Example

<syntaxhighlight lang="lua"> -- inserts letter я before the 2nd letter and prints 'мясо' print(utf8.insert("мсо", 2, "я")) </lua>

utf8.ncasecmp

utf8.ncasecmp(a, b)

Compares a and b without case. Return -1 means a < b, 0 means a == b and 1 means a > b.

Parameters

• a:

String to compare.

• b:

String to compare against.

utf8.next

utf8.next(string[, charpos[, offset]])

Iterates though the UTF-8 string.

Parameters

• string:

The input string to work on.

• charpos:

(optional) character position to work on.

• offset:

(optional) offset (as a number) to work on.

Example

<syntaxhighlight lang="lua"> -- prints location and code point of every letter for pos, code in utf8.next, "тут есть текст" do

  print(pos, code)

end </lua>

utf8.remove

utf8.remove(string[, start[, stop]])

Removed characters from the given string. Deletes characters from the given start to the end of the string. If stop is given, deletes characters from start to stop (including start and stop). start and stop can be negative.

Parameters

• string:

The input string to work on.

• start:

position to start deleting characters from.

• stop:

(optional) posititon to stop deleting characters at.

Example

<syntaxhighlight lang="lua"> -- delete everything from the 3rd character including the character itself print(utf8.remove("мясо", 3)) -- 'мя'

-- delete the last character, use negative to count backwards print(utf8.remove("мясо", -1)) -- 'мяс'

-- delete everything from the 2nd to the 4th character print(utf8.remove("вкусное", 2,4)) -- 'вное' </lua>

utf8.title

utf8.title(string)

Returns the uppercase version of the string for use in case-insensitive comparisons. If string is a number, it's treated as a code point and the converted code point is returned (as a number).

Parameters

• string:

The string to uppercase.

Example

<syntaxhighlight lang="lua"> print(utf8.title("привет")) -- 'ПРИВЕТ' print(utf8.title("Привет")) -- 'ПРИВЕТ' </lua>

utf8.width

utf8.width(string[, ambi_is_double[, default_width]])

Calculate the widths of the given string. If the string is a code point, return the width of this code point.

Parameters

• string:

The input string to work on.

• ambi_is_double:

(optional) if provided, the ambiguous width character's width is 2, otherwise it's 1.

• default_width:

(optional) if provided, this will be the width of unprintable character, used display a non-character mark for these characters.

utf8.widthindex

utf8.widthindex(string, location[, ambi_is_double[, default_width]])

Returns the character index at the location in the given string as well as the offset and the width. This is a reverse operation of utf8.width().

Parameters

• string:

The input string to work on.

• location:

location to get the width of.

• ambi_is_double:

(optional) if provided, the ambiguous width character's width is 2, otherwise it's 1.

• default_width:

(optional) if provided, this will be the width of unprintable character, used display a non-character mark for these characters.