string (lib)

See also: string.type


The string library contains functions intended for the manipulation of strings. This library is also the default event list for strings.


:byte( fromIndex   [toIndex] ) → number

Returns the numerical value of a given byte from the string.

print( ('abcdef'):byte(1) )

:chomp( stringToken ) → string, string

If found, returns the part of the string that came before the stringToken, returns the rest of the string as a second result.

print( ('abcdefghijklmnopqrs'):chomp('def') )
abc	ghijklmnopqrs

:copy( [fromIndex] [toIndex] ) → string

Returns a copy of the string, optionally a sub-string fromIndex to toIndex. If negative values are used for the indexes, the position is counted from the end of the string. Currently, :copy is not Unicode-aware.

print( ('abcdefghijklmnopqrs'):copy(3,-2) )

:characters( ƒ⇠char )

Iterates through all the character bytes of the string and calls ƒ on them. Currently, :characters is not Unicode-aware.

('abc'):characters{ c | print(c) }
a, b, c

:find( needlePattern   [fromIndex]   [plain] ) → number, number

Finds the first occurence of needlePattern and returns the position of its start and end (or nil if it's not found).

print( ('abc def'):find('%s') )
4, 4

:length( ) → number

Returns the length of the string (in byte characters, currently). Currently, :length is not Unicode-aware.

print( ('abc def'):length() )

:lower( ) → string

Returns a lower case version of the string. Currently, :lower is not Unicode-aware.

print( ('abc DEF'):lower() )
abc def

:match( pattern   [fromIndex] ) →

Returns the first matching substring as specified by the pattern.

print( ('I have 2 questions for you.'):match('%d+ %a+') )
2 questions

:parse( regex   ƒ⇠stringMatch,startPos,endPos )

Matches the string against the regular (POSIX) expression regex, and calls ƒ for every match.

('a very simple sipple is simxle string'):parse('s..[a-z]le' { s start end | print(s) })

:repeat( count   [seperator] )

Repeats the string count times and returns it.

print( ('Biggie Smalls'):repeat(3 ', ') )
Biggie Smalls, Biggie Smalls, Biggie Smalls

:replace( replaceAll   withString )

Replaces all occurrences of replaceAll with withString and returns the result. No Lua patterns or regular expressions are used.

  ('bananananana banana bananana'):replace('nana', 'NoNa')
baNoNaNoNana baNoNa baNoNana

:reverse( )

Reverses the string and returns it. Currently, :reverse is not Unicode-aware.

print( ('abcdefg'):reverse() )

:split( seperator )

Splits the string into an array, returning the array.

print( ('a,b,c,d'):split(',') )
(: 'a', 'b', 'c', 'd')

:substitute( patternString   replaceWith   [max] ) → string, replacementCount

Finds all occurrences matching the patternString and replaces them with replaceWith. patternString can be a Lua pattern.

print( ('hello world'):substitute('world', 'np-%1') )
hello np-world	1

:trim( ) → string

Returns a version of the string with all leading and trailing whitespace removed.

print( '-' << ('    np np np  '):trim() << '-' )
-np np np-

:upper( ) → string

Returns an upper case version of the string.

print( ('make me shout'):upper() )

Library Functions

char( asciiValue ) → string

Given an ASCII code, returns the appropriate character.

print( string.char(65) )