Module:UtilsString/Documentation

This module provides utility functions for manipulating Lua strings in general. For string manipulation and formatting that is specific to wikitext, see Module:UtilsMarkup.

This module re-implements some of the functions in the mw.text library. Use these functions whenever possible — mw.text is an order of magnitude slower because it uses mw.ustring.

Like Module:UtilsTable, some functions have both procedural and functional variants.

This module exports the following functions.

isEmpty

isEmpty(str)

Returns

• true if and only if the value is nil or ""

Examples

Input	Output	Status
isEmpty(nil)	true
isEmpty("")	true
isEmpty(" ")	false

notEmpty

notEmpty(str)

Returns

• true if and only if str is neither nil nor an empty string.

Examples

Input	Output	Status
notEmpty(" ")	true
notEmpty("")	false
notEmpty(nil)	false

isBlank

isBlank(str)

Returns

• true if and only if str is nil, blank, or whitespace.

Examples

Input	Output	Status
isBlank(" ")	true
isBlank("\n\n\n")	true
isBlank(nil)	true
isBlank("foo")	false

nilIfEmpty

nilIfEmpty(str)

Returns

• nil if value is nil or empty string, otherwise returns the given value.

Examples

Input	Output	Status
nilIfEmpty("")	nil
nilIfEmpty(nil)	nil
nilIfEmpty(" ")	" "

startsWith

startsWith_startsWith

startsWith(str, pattern)

Returns

• true if str starts with pattern, else false.

Examples

Input	Output	Status
startsWith("Fooloo Limpah", "Foo")	true
startsWith("Fooloo Limpah", "foo")	false
startsWith("Fooloo Limpah", "")	true
startsWith("[[foo]]", "[[")	true

_startsWith(pattern)(str)

Returns

• true if str starts with pattern, else false.

Examples

Input	Output	Status
_startsWith("Foo")("Fooloo Limpah")	true
_startsWith("foo")("Fooloo Limpah")	false
_startsWith("")("Fooloo Limpah")	true
_startsWith("[[")("[[foo]]")	true

startsWithRegex

startsWithRegex_startsWithRegex

startsWithRegex(str, pattern)

Returns

• true if str starts with regular expression pattern, else false.

Examples

Input	Output	Status
startsWithRegex("foo", "[af]")	true
startsWithRegex("aoo", "[af]")	true
startsWithRegex("boo", "[af]")	false

_startsWithRegex(pattern)(str)

Returns

• true if str starts with regular expression pattern, else false.

Examples

Input	Output	Status
_startsWithRegex("[af]")("foo")	true
_startsWithRegex("[af]")("aoo")	true
_startsWithRegex("[af]")("boo")	false

endsWith

endsWith_endsWith

endsWith(str, pattern)

Returns

• true if str ends with pattern, else false.

Examples

Input	Output	Status
endsWith("Fooloo Limpah", "Limpah")	true
endsWith("Fooloo Limpah", "limpah")	false
endsWith("Fooloo Limpah", "")	true
endsWith("Wood (Character)", ")", true)	true

_endsWith(pattern)(str)

Returns

• true if str ends with pattern, else false.

Examples

Input	Output	Status
_endsWith("Limpah")("Fooloo Limpah")	true
_endsWith("limpah")("Fooloo Limpah")	false
_endsWith("")("Fooloo Limpah")	true
_endsWith(")")("Wood (Character)")	true

endsWithRegex

endsWithRegex_endsWithRegex

endsWithRegex(str, pattern)

Returns

• true if str ends with regular expression pattern, else false.

Examples

Input	Output	Status
endsWithRegex("Wood (Character)", "%([^)]*%)")	true
endsWithRegex("Wood", "%([^)]*%)")	false

_endsWithRegex(pattern)(str)

Returns

• true if str ends with regular expression pattern, else false.

Examples

Input	Output	Status
_endsWithRegex("%([^)]*%)")("Wood (Character)")	true
_endsWithRegex("%([^)]*%)")("Wood")	false

split

split_split

split(str, [pattern], [plain])

A performant alternative to mw.text.split.

Parameters

• str

• [pattern="%s*,%s*"]

• [plain]

Returns

• A table of the split strings.

Examples

Input	Output	Status
split(" foo, bar,baz ")	{" foo", "bar", "baz "}
split("foo bar baz", " ")	{"foo", "bar", "baz"}
Limited support for Unicode strings
split("アイウエオ", "")	{"ア", "イ", "ウ", "エ", "オ"}

_split([pattern], [plain])(str)

A performant alternative to mw.text.split.

Parameters

• [pattern="%s*,%s*"]

• [plain]

• str

Returns

• A table of the split strings.

Examples

Input	Output	Status
_split(nil)(" foo, bar,baz ")	{" foo", "bar", "baz "}
_split(" ")("foo bar baz")	{"foo", "bar", "baz"}
Limited support for Unicode strings
_split("")("アイウエオ")	{"ア", "イ", "ウ", "エ", "オ"}

sub

sub_sub

sub(str, startIndex, [endIndex])

Equivalent to string.sub.

Parameters

• str

• startIndex

• [endIndex=#str]

Returns

• Function returning a substring of str from startIndex to endIndex (inclusive).

Examples

Input	Output	Status
sub("Fooloo Limpah", 8)	"Limpah"
sub("Fooloo Limpah", 1, 6)	"Fooloo"
sub("Fooloo Limpah", 20)	""
sub("Fooloo Limpah", -20)	"Fooloo Limpah"
sub("Fooloo Limpah", 8, 20)	"Limpah"

_sub(startIndex, [endIndex])(str)

Equivalent to string.sub.

Parameters

• startIndex

• [endIndex=#str]

• str

Returns

• Function returning a substring of str from startIndex to endIndex (inclusive).

Examples

Input	Output	Status
_sub(8)("Fooloo Limpah")	"Limpah"
_sub(1, 6)("Fooloo Limpah")	"Fooloo"
_sub(20)("Fooloo Limpah")	""
_sub(-20)("Fooloo Limpah")	"Fooloo Limpah"
_sub(8, 20)("Fooloo Limpah")	"Limpah"

trim

trim_trim

trim(str, [pattern])

A performant alternative to mw.text.trim.

Parameters

• str

• [pattern]

Returns

• The trimmed string.

Examples

Input	Output	Status
trim(" foo")	"foo"
trim(":Category:Link", ":")	"Category:Link"

_trim([pattern])(str)

A performant alternative to mw.text.trim.

Parameters

• [pattern]

• str

Returns

• The trimmed string.

Examples

Input	Output	Status
_trim(nil)(" foo")	"foo"
_trim(":")(":Category:Link")	"Category:Link"

interpolate

interpolate(formatStr, args)

Approximation of string interpolation

Parameters

• formatStr

• args

Returns

• The formatted string.

Examples

Input	Output	Status
interpolate( "${wiki} is a ${franchise} encyclopedia that anyone can edit.", { wiki = "Zelda Wiki", franchise = "''Zelda''", } )	"Zelda Wiki is a ''Zelda'' encyclopedia that anyone can edit."