stdlib

• Index

Contents

• Core Functions
• Deprecated Functions
• Metamethods

Core Libraries

• std.debug
• std.io
• std.math
• std.package
• std.string
• std.table

Core Functions

• std

Module std.string

Additions to the core string module.

The module table returned by std.string also contains all of the entries from the core string table. An hygienic way to import this module, then, is simply to override the core string locally:

local string = require 'std.string'

Core Functions

caps (s)	Capitalise each word in a string.
chomp (s)	Remove any final newline from a string.
escape_pattern (s)	Escape a string to be used as a pattern.
escape_shell (s)	Escape a string to be used as a shell token.
finds (s, pattern[, init=1[, plain]])	Repeatedly string.find until target string is exhausted.
format (f[, ...])	Extend to work better with one argument.
ltrim (s[, r='%s+'])	Remove leading matter from a string.
numbertosi (n)	Write a number using SI suffixes.
ordinal_suffix (n)	Return the English suffix for an ordinal.
pad (s, w[, p=' '])	Justify a string.
pickle (x)	Convert a value to a string that loads as an equal value.
prettytostring (x[, indent='\t'[, spacing='']])	Pretty-print a table, or other object.
render (x, vfns[, roots])	Turn tables into strings with recursion detection.
rtrim (s[, r='%s+'])	Remove trailing matter from a string.
split (s[, sep='%s+'])	Split a string at a given separator.
tfind (s, pattern[, init=1[, plain]])	Do string.find, returning a table of captures.
trim (s[, r='%s+'])	Remove leading and trailing matter from a string.
wrap (s[, w=78[, ind=0[, ind1=ind]]])	Wrap a string into a paragraph.

Deprecated Functions

monkey_patch ([namespace=_G])

Overwrite core string functions and metamethods with std enhanced versions.

Metamethods

__concat (s, o)	String concatenation operation.
__index (s, i)	String subscript operation.

Core Functions

caps (s)

Capitalise each word in a string.

Parameters:

• s string any string

Returns:

string s with each word capitalized

Usage:

userfullname = caps(input_string)

chomp (s)

Remove any final newline from a string.

Parameters:

• s string any string

Returns:

string s with any single trailing newline removed

Usage:

line = chomp(line)

escape_pattern (s)

Escape a string to be used as a pattern.

Parameters:

• s string any string

Returns:

string s with active pattern characters escaped

Usage:

substr = match(inputstr, escape_pattern(literal))

escape_shell (s)

Escape a string to be used as a shell token. Quotes spaces, parentheses, brackets, quotes, apostrophes and whitespace.

Parameters:

• s string any string

Returns:

string s with active shell characters escaped

Usage:

os.execute('echo ' .. escape_shell(outputstr))

finds (s, pattern[, init=1[, plain]])

Repeatedly string.find until target string is exhausted.

Parameters:

• s string target string
• pattern string pattern to match in s
• init integer start position (default 1)
• plain boolean inhibit magic characters (optional)

Returns:

list of {from, to; capt={captures}}

See also:

std.string.tfind

Usage:

for t in std.elems(finds('the target string', '%S+')) do
   print(tostring(t.capt))
end

format (f[, ...])

Extend to work better with one argument. If only one argument is passed, no formatting is attempted.

Parameters:

• f string format string
• ... arguments to format (optional)

Returns:

formatted string

Usage:

print(format '100% stdlib!')

ltrim (s[, r='%s+'])

Remove leading matter from a string.

Parameters:

• s string any string
• r string leading pattern (default '%s+')

Returns:

string s with leading r stripped

Usage:

print('got: ' .. ltrim(userinput))

numbertosi (n)

Write a number using SI suffixes. The number is always written to 3 s.f.

Parameters:

• n number or string any numeric value

Returns:

string n simplifed using largest available SI suffix.

Usage:

print(numbertosi(bitspersecond) .. 'bps')

ordinal_suffix (n)

Return the English suffix for an ordinal.

Parameters:

• n int or string any integer value

Returns:

string English suffix for n

Usage:

local now = os.date '*t'
print('%d%s day of the week', now.day, ordinal_suffix(now.day))

pad (s, w[, p=' '])

Justify a string. When the string is longer than w, it is truncated(left or right according to the sign of w).

Parameters:

• s string a string to justify
• w integer

  width to justify to(-ve means right-justify; +ve means

  left-justify)
  

• p string string to pad with (default ' ')

Returns:

string s justified to w characters wide

Usage:

print(pad(trim(outputstr, 78)) .. '\n')

pickle (x)

Convert a value to a string that loads as an equal value. Strings, numbers, booleans, nil and tables of those, with keys in a stable order. Tables that contain themselves, functions, userdata and threads raise an error.

Parameters:

• x object to pickle

Returns:

string reversible string rendering of x

See also:

std.eval

Usage:

function slow_identity(x)
   return std.eval(pickle(x))
end

prettytostring (x[, indent='\t'[, spacing='']])

Pretty-print a table, or other object.

Parameters:

• x object to convert to string
• indent string indent between levels (default '\t')
• spacing string space before every line (default '')

Returns:

string pretty string rendering of x

Usage:

print(prettytostring(std, '   '))

render (x, vfns[, roots])

Turn tables into strings with recursion detection. With a table of rendering functions, this is the std.normalize string.render. The 41.2 form, with five callback functions in place of vfns, is deprecated.

Parameters:

• x object to convert to string
• vfns table

  table of virtual functions to control rendering,

  as for `std.normalize` `string.render`
  

• roots table used internally for cycle detection (optional)

Returns:

string representation of x

Usage:

function printarray(x)
   return render(x, arrayvfns)
end

rtrim (s[, r='%s+'])

Remove trailing matter from a string.

Parameters:

• s string any string
• r string trailing pattern (default '%s+')

Returns:

string s with trailing r stripped

Usage:

print('got: ' .. rtrim(userinput))

split (s[, sep='%s+'])

Split a string at a given separator. Separator is a Lua pattern, so you have to escape active characters, ^$()%.[]*+-? with a % prefix to match a literal character in s.

Parameters:

• s string to split
• sep string separator pattern (default '%s+')

Returns:

list of strings

Usage:

words = split 'a very short sentence'

tfind (s, pattern[, init=1[, plain]])

Do string.find, returning a table of captures.

Parameters:

• s string target string
• pattern string pattern to match in s
• init integer start position (default 1)
• plain boolean inhibit magic characters (optional)

Returns:

1. int start of match
2. int end of match
3. table list of captured strings

See also:

std.string.finds

Usage:

b, e, captures = tfind('the target string', '%s', 10)

trim (s[, r='%s+'])

Remove leading and trailing matter from a string.

Parameters:

• s string any string
• r string trailing pattern (default '%s+')

Returns:

string s with leading and trailing r stripped

Usage:

print('got: ' .. trim(userinput))

wrap (s[, w=78[, ind=0[, ind1=ind]]])

Wrap a string into a paragraph.

Parameters:

• s string a paragraph of text
• w integer width to wrap to (default 78)
• ind integer indent (default 0)
• ind1 integer indent of first line (default ind)

Returns:

string s wrapped to w columns

Usage:

print(wrap(copyright, 72, 4))

Deprecated Functions

monkey_patch ([namespace=_G])

Overwrite core string functions and metamethods with std enhanced versions.

Parameters:

• namespace table where to install global functions (default _G)

Returns:

table the module table

Usage:

require 'std.string'.monkey_patch()

Metamethods

__concat (s, o)

String concatenation operation.

Parameters:

• s string initial string
• o object to stringify and concatenate

Returns:

s .. tostring(o)

Usage:

local string = setmetatable('', require 'std.string')
concatenated = 'foo' .. {'bar'}

__index (s, i)

String subscript operation.

Parameters:

• s string string
• i int or string index or method name

Returns:

sub(s, i, i) if i is a number, otherwise

fall back to a `std.string` metamethod(if any).

Usage:

getmetatable('').__index = require 'std.string'.__index
third =('12345')[3]