Module:UtilsString

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	Result
1	isEmpty(nil)	true
2	isEmpty("")	true
3	isEmpty(" ")	false

notEmpty

notEmpty(str)

Returns

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

Examples

#	Input	Output	Result
4	notEmpty(" ")	true
5	notEmpty("")	false
6	notEmpty(nil)	false

isBlank

isBlank(str)

Returns

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

Examples

#	Input	Output	Result
7	isBlank(" ")	true
8	isBlank("\n\n\n")	true
9	isBlank(nil)	true
10	isBlank("foo")	false

nilIfEmpty

nilIfEmpty(str)

Returns

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

Examples

#	Input	Output	Status
11	nilIfEmpty("")	nil
12	nilIfEmpty(nil)	nil
13	nilIfEmpty(" ")	" "

startsWith

startsWith_startsWith

startsWith(str, pattern)

Returns

• true if str starts with pattern, else false.

Examples

#	Input	Output	Result
14	startsWith("Fooloo Limpah", "Foo")	true
15	startsWith("Fooloo Limpah", "foo")	false
16	startsWith("Fooloo Limpah", "")	true
17	startsWith("[[foo]]", "[[")	true

_startsWith(str)

Returns

• true if str starts with pattern, else false.

Examples

#	Input	Output	Result
18	_startsWith("Foo")("Fooloo Limpah")	true
19	_startsWith("foo")("Fooloo Limpah")	false
20	_startsWith("")("Fooloo Limpah")	true
21	_startsWith("[[")("[[foo]]")	true

startsWithRegex

startsWithRegex_startsWithRegex

startsWithRegex(str, pattern)

Returns

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

Examples

#	Input	Output	Result
22	startsWithRegex("foo", "[af]")	true
23	startsWithRegex("aoo", "[af]")	true
24	startsWithRegex("boo", "[af]")	false

_startsWithRegex(str)

Returns

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

Examples

#	Input	Output	Result
25	_startsWithRegex("[af]")("foo")	true
26	_startsWithRegex("[af]")("aoo")	true
27	_startsWithRegex("[af]")("boo")	false

endsWith

endsWith_endsWith

endsWith(str, pattern)

Returns

• true if str ends with pattern, else false.

Examples

#	Input	Output	Result
28	endsWith("Fooloo Limpah", "Limpah")	true
29	endsWith("Fooloo Limpah", "limpah")	false
30	endsWith("Fooloo Limpah", "")	true
31	endsWith("Wood (Character)", ")", true)	true

_endsWith(str)

Returns

• true if str ends with pattern, else false.

Examples

#	Input	Output	Result
32	_endsWith("Limpah")("Fooloo Limpah")	true
33	_endsWith("limpah")("Fooloo Limpah")	false
34	_endsWith("")("Fooloo Limpah")	true
35	_endsWith(")")("Wood (Character)")	true

endsWithRegex

endsWithRegex_endsWithRegex

endsWithRegex(str, pattern)

Returns

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

Examples

#	Input	Output	Result
36	endsWithRegex("Wood (Character)", "%([^)]*%)")	true
37	endsWithRegex("Wood", "%([^)]*%)")	false

_endsWithRegex(str)

Returns

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

Examples

#	Input	Output	Result
38	_endsWithRegex("%([^)]*%)")("Wood (Character)")	true
39	_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	Result
40	split(" foo, bar,baz ")	{" foo", "bar", "baz "}
41	split("foo bar baz", " ")	{"foo", "bar", "baz"}
Limited support for Unicode strings
42	split("アイウエオ", "")	{"ア", "イ", "ウ", "エ", "オ"}

_split(str)

A performant alternative to mw.text.split.

Parameters

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

• [plain]

• str

Returns

• A table of the split strings.

Examples

#	Input	Output	Result
43	_split(nil)(" foo, bar,baz ")	{" foo", "bar", "baz "}
44	_split(" ")("foo bar baz")	{"foo", "bar", "baz"}
Limited support for Unicode strings
45	_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
46	sub("Fooloo Limpah", 8)	"Limpah"
47	sub("Fooloo Limpah", 1, 6)	"Fooloo"
48	sub("Fooloo Limpah", 20)	""
49	sub("Fooloo Limpah", -20)	"Fooloo Limpah"
50	sub("Fooloo Limpah", 8, 20)	"Limpah"

_sub(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
51	_sub(8)("Fooloo Limpah")	"Limpah"
52	_sub(1, 6)("Fooloo Limpah")	"Fooloo"
53	_sub(20)("Fooloo Limpah")	""
54	_sub(-20)("Fooloo Limpah")	"Fooloo Limpah"
55	_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
56	trim(" foo")	"foo"
57	trim(":Category:Link", ":")	"Category:Link"

_trim(str)

A performant alternative to mw.text.trim.

Parameters

• [pattern]

• str

Returns

• The trimmed string.

Examples

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

interpolate

interpolate(formatStr, args)

Approximation of string interpolation

Parameters

• formatStr

• args

Returns

• The formatted string.

Examples

#	Input	Output	Status
60	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."

---

local p = {}
local h = {}

function p.isEmpty(str)
	return str == nil or str == ""
end

function p.notEmpty(str)
	return not p.isEmpty(str)
end

function p.isBlank(str)
	return str == nil or mw.text.trim(str) == ""
end

function p.nilIfEmpty(str)
	if str and str ~= "" then
		return str
	end
end

function p.startsWith(str, pattern)
	return h.startsWith(str, pattern, true)
end
function p.startsWithRegex(str, pattern)
	return h.startsWith(str, pattern, false)
end
function p._startsWith(pattern)
	return function(str)
		return h.startsWith(str, pattern, true)
	end
end
function p._startsWithRegex(pattern)
	return function(str)
		return h.startsWith(str, pattern, false)
	end
end
function h.startsWith(str, pattern, plain)
	return str:find(pattern, 1, plain) == 1
end

function p.endsWith(str, pattern)
	return h.endsWith(str, pattern, true)
end
function p.endsWithRegex(str, pattern)
	return h.endsWith(str, pattern, false)
end
function p._endsWith(pattern)
	return function(str)
		return h.endsWith(str, pattern, true)
	end
end
function p._endsWithRegex(pattern)
	return function(str)
		return h.endsWith(str, pattern, false)
	end
end
function h.endsWith(str, pattern, plain)
	local endIndex = 0
	repeat
		endIndex = select(2, str:find(pattern, endIndex + 1, plain))
	until endIndex == nil or endIndex == #str or endIndex == 0
	return endIndex ~= nil
end


function p._split(pattern, plain)
	return function(str)
		return p.split(str, pattern, plain)
	end
end
-- Original source: https://phabricator.wikimedia.org/diffusion/ELUA/browse/master/includes/engines/LuaCommon/lualib/mw.text.lua
function p.split(text, pattern, plain)
	local ret = {}
	-- Edge case: gsplit with pattern "" breaks Unicode characters which are composed of multiple bytes.
	-- Instead we simply iterate over the characters, which is effectively what splitting with "" does.
	-- If we had Lua 5.3 we could probably do something with the utf8 library.
	-- Instead we use a snippet from http://lua-users.org/wiki/LuaUnicode
	if pattern == "" then
		for m in string.gmatch(text, "([%z\1-\127\194-\244][\128-\191]*)") do
          ret[#ret+1] = m
        end
	else
		for m in h.gsplit( text, pattern, plain ) do
			ret[#ret+1] = m
		end
	end
	return ret
end
function h.gsplit(text, pattern, plain)
	if not pattern then pattern = '%s*,%s*' end
	local s, l = 1, text:len()
	return function ()
		if s then
			local e, n = text:find( pattern, s, plain )
			local ret
			if not e then
				ret = text:sub( s )
				s = nil
			elseif n < e then
				-- Empty separator!
				ret = text:sub( s, e )
				if e < l then
					s = e + 1
				else
					s = nil
				end
			else
				ret = e > s and text:sub( s, e - 1 ) or ''
				s = n + 1
			end
			return ret
		end
	end, nil, nil
end

function p.sub(str, s, e)
	return p._sub(s, e)(str)
end
function p._sub(s, e)
	return function(str)
		return string.sub(str, s, e)
	end
end


local char_to_hex = function(c)
  return string.format("%%%02X", string.byte(c))
end

-- Source: https://phabricator.wikimedia.org/diffusion/ELUA/browse/master/includes/engines/LuaCommon/lualib/mw.text.lua
function p.trim(s, charset)
	return p._trim(charset)(s)
end
function p._trim(charset)
	charset = charset or '\t\r\n\f '
	return function(s)
		s = s:gsub( '^[' .. charset .. ']*(.-)[' .. charset .. ']*$', '%1' )
		return s
	end
end

-- By http://lua-users.org/wiki/RiciLake
function p.interpolate(formatStr, tab)
  return (formatStr:gsub('($%b{})', function(w) return tab[w:sub(3, -2)] or w end))
end

p.Schemas = {
	split = {
		str = {
			type = "string",
			required = true,
		},
		pattern = {
			type = "string",
			default = mw.dumpObject("%s*,%s*"),
		},
		plain = {
			type = "boolean",
		},
	},
	sub = {
		str = {
			type = "string",
			required = true,
		},
		startIndex = {
			type = "number",
			required = true,
		},
		endIndex = {
			type = "number",
			default = "#str",
		},
	},
	trim = {
		pattern = {
			type = "string",
		},
		str = {
			type = "string",
			required = true,
		},
	},
	format = {
		formatStr = {
			type = "string",
			required = true,
		},
		["..."] = {
			type = "array",
			items = {
				type = "string",
			},
			required = true,
		},
	},
	interpolate = {
		formatStr = {
			type = "string",
			required = true,
		},
		args = {
			type = "map",
			required = true,
			keys = { type = "string" },
			values = { type = "string" },
		},
	},
}

p.Documentation = {
	isEmpty = {
		params = {"str"},
		returns = '<code>true</code> if and only if the value is <code>nil</code> or <code>""</code>',
		cases = {
			{
				args = {nil},
				expect = true,
			},
			{
				args = {""},
				expect = true,
			},
			{
				args = {" "},
				expect = false,
			},
		},
	},
	isBlank = {
		params = {"str"},
		returns = "<code>true</code> if and only if <code>str</code> is nil, blank, or whitespace.",
		cases = {
			{
				args = {"  "},
				expect = true,
			},
			{
				args = {"\n\n\n"},
				expect = true,
			},
			{
				args = {nil},
				expect = true,
			},
			{
				args = {"foo"},
				expect = false,
			},
		},
	},
	notEmpty = {
		params = {"str"},
		returns = "<code>true</code> if and only if <code>str</code> is neither nil nor an empty string.",
		cases = {
			{
				args = {" "},
				expect = true,
			},
			{
				args = {""},
				expect = false,
			},
			{
				args = {nil},
				expect = false,
			},
		}
	},
	nilIfEmpty = {
		params = {"str"},
		returns = "<code>nil</code> if value is nil or empty string, otherwise returns the given value.",
		cases = {
			outputOnly = true,
			{
				args = {""},
				expect = nil,	
			},
			{
				args = {nil},
				expect = nil,
			},
			{
				args = {" "},
				expect = " ",
			},
		},
	},
	startsWith = {
		params = {"str", "pattern"},
		_params = {{"pattern"}, {"str"}},
		returns = "<code>true</code> if <code>str</code> starts with <code>pattern</code>, else <code>false</code>.",
		cases = {
			{
				args = {"Fooloo Limpah", "Foo"},
				expect = true,
			},
			{
				args = {"Fooloo Limpah", "foo"},
				expect = false,
			},
			{
				args = {"Fooloo Limpah", ""},
				expect = true,
			},
			{
				args = {"[[foo]]", "[["},
				expect = true,
			},
		},
	},
	startsWithRegex = {
		params = {"str", "pattern"},
		_params = {{"pattern"}, {"str"}},
		returns = "<code>true</code> if <code>str</code> starts with regular expression <code>pattern</code>, else <code>false</code>.",
		cases = {
			{
				args = {"foo", "[af]"},
				expect = true,
			},
			{
				args = {"aoo", "[af]"},
				expect = true,
			},
			{
				args = {"boo", "[af]"},
				expect = false,
			},
		}
	},
	endsWith = {
		params = {"str", "pattern"},
		_params = {{"pattern"}, {"str"}},
		returns = "<code>true</code> if <code>str</code> ends with <code>pattern</code>, else <code>false</code>.",
		cases = {
			{
				args = {"Fooloo Limpah", "Limpah"},
				expect = true,
			},
			{
				args = {"Fooloo Limpah", "limpah"},
				expect = false,
			},
			{
				args = {"Fooloo Limpah", ""},
				expect = true,
			},
			{
				args = {"Wood (Character)", ")", true},
				expect = true,
			}
		},
	},
	endsWithRegex = {
		params = {"str", "pattern"},
		_params = {{"pattern"}, {"str"}},
		returns = "<code>true</code> if <code>str</code> ends with regular expression <code>pattern</code>, else <code>false</code>.",
		cases = {
			{
				args = {"Wood (Character)", "%([^)]*%)"},
				expect = true,
			},
			{
				args = {"Wood", "%([^)]*%)"},
				expect = false,
			},
		},
	},
	trim = {
		desc = "A [[gphelp:Extension:Scribunto#mw.text.trim is slow|performant alternative]] to {{Scribunto Manual|lib=mw.text.trim}}.",
		params = {"str", "pattern"},
		_params = {{"pattern"}, {"str"}},
		returns = "The trimmed string.",
		cases = {
			outputOnly = true,
			{
				args = {"  foo"},
				expect = "foo",
			},
			{
				args = {":Category:Link", ":"},
				expect = "Category:Link",
			},
		},
	},
	split = {
		desc = "A [[gphelp:Extension:Scribunto#mw.text.split is very slow|performant alternative]] to  {{Scribunto Manual|lib=mw.text.split}}.",
		params = {"str", "pattern", "plain"},
		_params = {{"pattern", "plain"}, {"str"}},
		returns = "A <code>table</code> of the split strings.",
		cases = {
			{
				args = {" foo,    bar,baz "},
				expect = {" foo", "bar", "baz "},
			},
			{
				args = {"foo bar baz", " "},
				expect = {"foo", "bar", "baz"},
			},
			{
				desc = "Limited support for Unicode strings",
				args = {"アイウエオ", ""},
				expect = {"ア","イ","ウ","エ","オ"},
			},
		},
	},
	sub = {
		desc = "Equivalent to <code>string.sub</code>.",
		params = {"str", "startIndex", "endIndex"},
		_params = {{"startIndex", "endIndex"}, {"str"}},
		returns = "Function returning a substring of <code>str</code> from <code>startIndex</code> to <code>endIndex</code> (inclusive).",
		cases = {
			outputOnly = true,
			{
				args = {"Fooloo Limpah", 8},
				expect = "Limpah",
			},
			{
				args = {"Fooloo Limpah", 1, 6},
				expect = "Fooloo",
			},
			{
				args = {"Fooloo Limpah", 20},
				expect = "",
			},
			{
				args = {"Fooloo Limpah", -20},
				expect = "Fooloo Limpah",
			},
			{
				args = {"Fooloo Limpah", 8, 20},
				expect = "Limpah", 
			},
		},
	},
	interpolate = {
		desc = "Approximation of [http://lua-users.org/wiki/StringInterpolation string interpolation]",
		params = {"formatStr", "args"},
		returns = "The formatted string.",
		cases = {
			outputOnly = true,
			{
				args = {"${wiki} is a ${franchise} encyclopedia that anyone can edit.", {
					wiki = "Zelda Wiki",
					franchise = "''Zelda''",
				}},
				expect = "Zelda Wiki is a ''Zelda'' encyclopedia that anyone can edit."
			}
		}
	},
}

return p