Module:String/doc

This module provides byte-oriented string helpers for templates. Its implementation uses Lua's string library: lengths and positions count bytes, so these operations can split multibyte characters. Use mw.ustring in Lua when Unicode character positions are required.

Functions

Invoke with {{#invoke:String|function|arguments}}. The following names describe the deployed implementation.

Function	Parameters	Behavior
len	s	Number of bytes.
sub	s, i, j	Substring with one-based inclusive positions; defaults: i=1, j=-1. Negative positions count from the end. Invalid ranges produce an error.
sublength	named s, i, len	Legacy substring with a zero-based offset i (default 0) and optional length.
pos	target, pos	Byte at a one-based position. Negative positions count from the end; zero or out-of-range positions produce an error.
find	source, target, start, plain	First match position, or 0 if absent. Defaults: start=1, literal search plain=true.
str_find	source, target	Legacy literal search: -1 if absent, 1 for an empty target. Prefer find for new uses.
match	s, pattern, start, match, plain, nomatch	Selected match (default 1), starting at byte 1. Uses Lua patterns by default; plain=true requests literal matching. nomatch supplies a fallback.
replace	source, pattern, replace, count, plain	Replacement, literal by default. count limits replacements; plain=false enables Lua patterns.
rep	positional text, repetition count	Repeats text.
escapePattern	pattern_string	Escapes Lua pattern metacharacters.
count	source, pattern, plain	Counts matches; literal matching by default.
endswith	source, pattern	Returns yes if the source has that literal suffix, otherwise empty text.
join	positional separator, followed by strings	Joins nonempty arguments with the separator.

Most helpers accept named parameters or positional parameters in the order shown. sublength uses the named fields shown; rep and join use positional arguments. Named arguments handled by the module's parameter helper are trimmed; positional arguments retain whitespace.

Examples

Invocation	Result
{{#invoke:String|len|abc}}	3
{{#invoke:String|sub|abcdef|2|4}}	bcd
{{#invoke:String|find|abcabc|bc}}	2
{{#invoke:String|replace|source=a.b|pattern=.|replace=-}}	a-b
{{#invoke:String|join| / |one||two}}	one / two

Patterns and errors

Lua patterns are not regular expressions; see the Lua string-library reference. Literal replacement escapes pattern and replacement metacharacters. When pattern mode is enabled, Lua pattern and replacement rules apply.

Functions that report errors through the module's error helper display an error and can add an error category. ignore_errors=true or 1 suppresses that output, no_category=true or 1 suppresses the category, and error_category changes its name. These options do not catch every possible Lua runtime error. Functions whose names begin with an underscore are implementation helpers.