Utils.string module

Extends Lua 5.2 string.

See also

• string

Usage

local string = require('__stdlib__/stdlib/utils/string')

Functions

String.trim(s)	Returns a copy of the string with any leading or trailing whitespace from the string removed.
String.starts_with(s, start)	Tests if a string starts with a given substring.
String.ends_with(s, ends)	Tests if a string ends with a given substring.
String.contains(s, contains)	Tests if a string contains a given substring.
String.is_empty(s)	Tests whether a string is empty.
String.is_alpha(s)	does s only contain alphabetic characters?
String.is_digit(s)	does s only contain digits?
String.is_alnum(s)	does s only contain alphanumeric characters?
String.is_space(s)	does s only contain spaces?
String.is_lower(s)	does s only contain lower case characters?
String.is_upper(s)	does s only contain upper case characters?
String.title(s)	iniital word letters uppercase (‘title case’).
String.shorten(s, w, tail)	Return a shortened version of a string.
String.join(s, seq)	concatenate the strings using this string as a delimiter.
String.ljust(s, w[, ch=' '])	left-justify s with width w.
String.rjust(s, w[, ch=' '])	right-justify s with width w.
String.center(s, w[, ch=' '])	center-justify s with width w.
String.split(s[, sep="."][, pattern=false][, func])	Splits a string into an array.
String.ordinal_suffix(n, prepend_number)	Return the ordinal suffix for a number.
String.exponent_number(str)	Convert a metric string prefix to a number value.

Functions

# String.trim(s)

Returns a copy of the string with any leading or trailing whitespace from the string removed.

Parameters:

• s : (string) the string to remove leading or trailing whitespace from

Returns:

• (string) a copy of the string without leading or trailing whitespace

# String.starts_with(s, start)

Tests if a string starts with a given substring.

Parameters:

• s : (string) the string to check for the start substring
• start : (string) the substring to test for

Returns:

• (boolean) true if the start substring was found in the string

# String.ends_with(s, ends)

Tests if a string ends with a given substring.

Parameters:

• s : (string) the string to check for the end substring
• ends : (string) the substring to test for

Returns:

• (boolean) true if the end substring was found in the string

# String.contains(s, contains)

Tests if a string contains a given substring.

Parameters:

• s : (string) the string to check for the substring
• contains : (string) the substring to test for

Returns:

• (boolean) true if the substring was found in the string

# String.is_empty(s)

Tests whether a string is empty.

Parameters:

• s : (string) the string to test

Returns:

• (boolean) true if the string is empty

# String.is_alpha(s)

does s only contain alphabetic characters?

Parameters:

• s : (string) a string

# String.is_digit(s)

does s only contain digits?

Parameters:

• s : (string) a string

# String.is_alnum(s)

does s only contain alphanumeric characters?

Parameters:

• s : (string) a string

# String.is_space(s)

does s only contain spaces?

Parameters:

• s : (string) a string

# String.is_lower(s)

does s only contain lower case characters?

Parameters:

• s : (string) a string

# String.is_upper(s)

does s only contain upper case characters?

Parameters:

• s : (string) a string

# String.title(s)

iniital word letters uppercase (‘title case’).

Here ‘words’ mean chunks of non-space characters.

Parameters:

• s : (string) the string

Returns:

• a string with each word’s first letter uppercase

# String.shorten(s, w, tail)

Return a shortened version of a string.

Fits string within w characters. Removed characters are marked with ellipsis.

Parameters:

• s : (string) the string
• w : (int) the maxinum size allowed
• tail : (bool) true if we want to show the end of the string (head otherwise)

Usage:

('1234567890'):shorten(8) == '12345...'

('1234567890'):shorten(8, true) == '...67890'

('1234567890'):shorten(20) == '1234567890'

# String.join(s, seq)

concatenate the strings using this string as a delimiter.

Parameters:

• s : (string) the string
• seq : a table of strings or numbers

Usage:

(' '):join {1,2,3} == '1 2 3'

# String.ljust(s, w[, ch=' '])

left-justify s with width w.

Parameters:

• s : (string) the string
• w : (int) width of justification
• ch : (string) padding character (default: ' ')

# String.rjust(s, w[, ch=' '])

right-justify s with width w.

Parameters:

• s : (string) the string
• w : (int) width of justification
• ch : (string) padding character (default: ' ')

# String.center(s, w[, ch=' '])

center-justify s with width w.

Parameters:

• s : (string) the string
• w : (int) width of justification
• ch : (string) padding character (default: ' ')

# String.split(s[, sep="."][, pattern=false][, func])

Splits a string into an array.

Note: Empty split substrings are not included in the resulting table.

For example, string.split("foo.bar...", ".", false) results in the table {"foo", "bar"}.

Parameters:

• s : (string) the string to split
• sep : (string) the separator to use. (default: ".")
• pattern : (boolean) whether to interpret the separator as a lua pattern or plaintext for the string split (default: false)
• func : (function) pass each split string through this function. (optional)

Returns:

• ({string,...}) an array of strings

# String.ordinal_suffix(n, prepend_number)

Return the ordinal suffix for a number.

Parameters:

• n : (number)
• prepend_number : (boolean) if the passed number should be pre-pended

Returns:

• (string) the ordinal suffix

# String.exponent_number(str)

Convert a metric string prefix to a number value.

Parameters:

• str : (string)

Returns:

• (float)