Global Lua Modules/String

String
Information
Type	Invocable Lua module
Release status	Stable
Test suite status	Passed
Description	Provides access to basic string functions.
Author(s)	Dessamator
Using code by	Wikipedia
Other attribution	Anomie (Wikipedia)
Updated	July 11, 2020
Code	Module:String

String provides access to basic string functions. This module allows simple text manipulation and is dozens of times more efficient that its parser function counterparts. MediaWiki's native string functions have a upper limit defined by wgPFStringLengthLimit as 1000 characters - this module lacks any such limit.

The default category name for errors is "Errors reported by Module String". However, this can be overriden if your wiki configures Module:String/category to return a different category name. On this wiki, the category is configured to Scribunto's general error category, and this configuration corresponds to "Pages with script errors" on wikis written in your user language.

The majority of template functions provided can be invoked with named parameters, unnamed parameters, or a mixture.

If named parameters are used, Mediawiki will automatically remove leading or trailing whitespace from the parameter - see str._getParameters.

Template options:

• ignore_errors: If set to true or 1, any error condition will result in an empty string being returned rather than an error message.
• error_category: If an error occurs, overrides the name of a category to include with the error message.
• no_category: If set to true or 1, no category will be added if an error is generated.

Installation

Lua installation
Module:	Create Module:String on your wiki with the following code:
Template:	Create Template:String on your wiki with the following code:
Template usage:	The template can be used with the following syntax:

Documentation

Package items

str.len(frame) (function)

Computes the length of the target string.

Parameters:

• frame Invocation frame object. (table)
  • frame.args Invocation/template arguments. (table)
    • frame.args.s Target Unicode string. (string; optional)

Returns: Length of Unicode string. (number)

Usage:

• {{string|len|<target string>}}
• {{string|len|s = <target string>}}

str.sub(frame) (function)

Extracts a substring of the target string at specified indices. Indexing is 1-based for the target string to extract from. If either i or j is a negative value, it is interpreted the same as selecting a character by counting from the end of the string. Hence, a value of -1 is the same as selecting the last character of the string.

If the requested indices are out of range for the given string, an error is reported.

Parameters:

• frame Invocation frame object. (table)
  • frame.args Invocation/template arguments. (table)
    • frame.args.s The string to return a subset of. (string)
    • frame.args.i The fist index of the substring to return; default: 1. (string)
    • frame.args.j: The last index of the string to return; default: #s. (string)

Errors:

• 'string subset index out of range' (string; line 99)
• 'string subset indices out of order' (string; line 102)

Returns: Substring from i/1 to j/#s.

Usage:

• {{string|sub|<target string>|<start index>|<end index>}}
• {{string|sub|s = <target string>|i = <start index>|j = <end index>}}

str.sublength(frame) (function)

Implements {{str sub old}}. This function is kept in order to maintain these older templates. Indexing is 0-based for the substring start position.

Parameters:

• frame Invocation frame object. (table)
  • frame.args Invocation/template arguments. (table)
    • frame.args.s Source string to search. (string)
    • frame.args.i Index to begin output substring at. Default: 0. (string)
    • frame.args.len Length of output substring. (string)

Returns: Substring starting with i/0 of length len. (string)

Warning: This function is deprecated in favor of str.sub.

str.match(frame) (function)

Extracts a substring matching a pattern from the source string. If match or start are out of range for the string being queried, then this function generates an error.

An error is also generated if no match is found. If one adds the parameter ignore_errors=true, then the error will be suppressed and an empty string will be returned on any failure.

Parameters:

• frame Invocation frame object. (table)
  • frame.args Invocation/template arguments. (table)
    • frame.args.s Target string to search. (string)
    • frame.args.pattern The pattern or string to find within the string. (string)
    • frame.args.start The index within the source string to start the search. The first character of the string has index 1. Default: 1. (string)
    • frame.args.match In some cases it may be possible to make multiple matches on a single string. This specifies which match to return, where the first match is match = 1. If a negative number is specified then a match is returned counting from the last match. Hence match = -1 is the same as requesting the last match. Default: 1. (string)
    • frame.args.plain A flag indicating that the pattern should be understood as a literal. Default: false. (string)
    • frame.args.nomatch If no match is found, output the "nomatch" value rather than an error. (string)

Errors:

• 'target string is empty' (string; line 192)
• 'pattern string is empty' (string; line 195)
• 'requested start is out of range' (string; line 198)
• 'match index is out of range' (string; line 201)
• 'match not found' (string; line 241)

Returns: Substring of the source string matching a pattern or string literal. (string)

Usage:

• {{string|match|<source string>|<pattern string>|<start index>|<match number>|<plain flag>|<nomatch output>}}
• {{string|match|s = <source string>|pattern = <pattern string>|start = <start index>|match = <match number>|plain = <plain flag>|nomatch = <nomatch output>}}

See also:

• Native patterns
• Unicode patterns

str.pos(frame) (function)

Returns a single character from the target string. Indexing is 1-based for the target string position.

If one requests a negative value, this function will select a character by counting backwards from the end of the string. In other words, pos = -1 is the same as asking for the last character.

A requested value of zero, or a value greater than the length of the string returns an error.

Parameters:

• frame Invocation frame object. (table)
  • frame.args Invocation/template arguments. (table)
    • frame.args.target The string to search. (string)
    • frame.args.pos The index for the character to return. Can be negative for reverse indexing. (string)

Error: 'string index out of range' (string; line 274)

Returns: Single character at position pos. (string)

Usage:

• {{string|pos|<target string>|<index value>}}
• {{string|pos|target = <target string>|pos = <index value>}}

str.find(frame) (function)

Searches for a target string/pattern in a string. This function should be safe for UTF-8 strings.

Parameters:

• frame Invocation frame object. (table)
  • frame.args Invocation/template arguments. (table)
    • frame.args.source The string to search. (string)
    • frame.args.target The string or pattern to find within the source string. (string)
    • frame.args.start The index within the source string to start the search. Default: 1. (string)
    • frame.args.plain Boolean flag indicating that target should be understood as a literal and not as a Lua style regular expression. Default: true. (string)

Returns: First index >= start/1 that target is found within source. Indexing is 1-based. If target is not found, then this function returns 0. If either "source" or "target" are missing / empty, this function also returns 0.

Usage:

• {{string|find|<source string>|<target string>|<start index>|<plain flag>}}
• {{string|find|source = <source string>|target = <target string>|start = <start index>|plain = <plain flag>}}

str.str_find(frame) (function)

Duplicates the behavior of {{str find}} including its quirks. This is provided in order to support older templates.

Parameters:

• frame Invocation frame object. (table)
  • frame.args Invocation/template arguments. (table)
    • frame.args.source Source string to find a match in. (string)
    • frame.args.target Search string within source. (string)

Returns: The first index in source that is a match to target. Indexing is 1-based, and the function returns -1 if the target string is not present in source.

Note: If the "target" string is empty / missing, this function returns a value of '1', which is generally unexpected behavior, and must be accounted for separatetly.

Warning: This function is deprecated in favour of str.find.

str.prefix(frame) (function)

Determines the presence of a prefix in a string.

Parameters:

• frame Invocation frame object. (table)
  • frame.args Invocation/template arguments. (table)
    • frame.args.source Source string to test. (string)
    • frame.args.prefix Suffix to test for. (string)

Returns: Boolean flag indicating prefix presence. (string)

Usage:

• {{string|prefix|<source string>|<prefix string>}}
• {{string|prefix|source = <source string>|prefix = <prefix string>}}

str.suffix(frame) (function)

Determines the presence of a suffix in a string.

Parameters:

• frame Invocation frame object. (table)
  • frame.args Invocation/template arguments. (table)
    • frame.args.source Source string to test. (string)
    • frame.args.suffix Suffix to test for. (string)

Returns: Boolean flag indicating suffix presence. (string)

Usage:

• {{string|suffix|<source string>|<suffix string>}}
• {{string|suffix|source = <source string>|suffix = <suffix string>}}

str.count(frame) (function)

Counts the number of occurrences of one string in another.

Parameters:

• frame Invocation frame object. (table)
  • frame.args Invocation/template arguments. (table)
    • frame.args.source Source string to count occurences in. (string)
    • frame.args.pattern Lua pattern or string to match against. (string)
    • frame.args.plain Boolean flag indicating that pattern should be understood as a literal and not as a Lua style regular expression. Default: 'true'. (string; optional)

Returns: Number of occurences in target string. (number)

Usage:

• {{string|count|<source string>|<pattern string>|<plain flag>}}
• {{string|count|source = <source string>|pattern = <pattern string>|plain = <plain flag>}}

str.replace(frame) (function)

Replaces a target string or pattern within another string.

Parameters:

• frame Invocation frame object. (table)
  • frame.args Invocation/template arguments. (table)
    • frame.args.source The string to search. (string)
    • frame.args.pattern The string or pattern to find within the source. (string)
    • frame.args.replace The replacement text (string)
    • frame.args.count The number of occurences to replace. Defaults to all occurences. (string)
    • frame.args.plain Boolean flag indicating that pattern should be understood as a literal and not as a Lua style regular expression. Default: 'true'. (string)

Usage:

• {{string|replace|<source string>|<pattern string>|<replace string>|<replacement count>|<plain flag>}}
• {{string|replace|source = <source_string>|pattern = <pattern string>|replace = <replace string>|count = <replacement count>|plain = <plain flag>}}

str.rep(frame) (function)

Repeats a string ${\textstyle \{n \in \N \}}$ times. A simple template pipe for the string.rep Lua function.

Parameters:

• frame Invocation frame object. (table)
  • frame.args Invocation/template arguments. (table)
    • frame.args.source Source string to repeat. (string)
    • frame.args.count Integer for number of output repetitions. (string)

Error: 'function rep expects a number as second parameter, received $count' (string; line 513)

Returns: String with repeated copies of source. (string)

Usage:

• {{string|rep|<hello>|<3>}}
• {{string|rep|source = <hello>|count = <3>}}

str.lc(frame) (function)

Convert string to lowercase Unicode character sequence.

Parameters:

• frame Invocation frame object. (table)
  • frame.args Invocation/template arguments. (table)
    • frame.args.source Source string to change case. (string)

Returns: Lowercase UTF-8 string.

Usage:

• {{string|lc|<INPUT STRING>}}
• {{string|lc|source = <INPUT STRING>}}

str.uc(frame) (function)

Convert string to uppercase Unicode character sequence.

Parameters:

• frame Invocation frame object. (table)
  • frame.args Invocation/template arguments. (table)
    • frame.args.str String of indeterminate case. (string)

Returns: Uppercase UTF-8 string.

Usage:

• {{string|uc|<input string>}}
• {{string|uc|source = <input string>}}

str.lcfirst(frame) (function)

Convert string prefix to lowercase Unicode character.

Parameters:

• frame Invocation frame object. (table)
  • frame.args Invocation/template arguments. (table)
    • frame.args.source String of indeterminate case. (string)

Returns: UTF-8 string with lowercase prefix letter.

Usage:

• {{string|lcfirst|<Input string>}}
• {{string|lcfirst|source = <Input string>}}

str.ucfirst(frame) (function)

Convert string prefix to uppercase Unicode character.

Parameters:

• frame Invocation frame object. (table)
  • frame.args Invocation/template arguments. (table)
    • frame.args.source Source string to change case. (string)

Returns: UTF-8 string with uppercase prefix letter.

Usage:

• {{string|ucfirst|<iNPUT STRING>}}
• {{string|ucfirst|source = <iNPUT STRING>}}

str.padleft(frame) (function)

Pads beginning of a string with a character or whitespace.

Parameters:

• frame Invocation frame object. (table)
  • frame.args Invocation/template arguments. (table)
    • frame.args.str Source string to pad. (string)
    • frame.args.len Length of output string. (string)
    • frame.args.char Start padding character. Default: ' '. (string; optional)

Returns: String padded to the left. (string)

Usage:

• {{string|padleft|<source string>|<expected length>|<pad character>}}
• {{string|padleft|source = <source string>|len = <expected length>|char = <pad character>}}

str.padright(frame) (function)

Pads end of a string with a character or whitespace.

Parameters:

• frame Invocation frame object. (table)
  • frame.args Invocation/template arguments. (table)
    • frame.args.source Source string to pad. (string)
    • frame.args.len Length of output string. (string)
    • frame.args.char End padding character. Default: ' '. (string; optional)

Returns: String padded to the right. (string)

Usage:

• {{string|padright|<source string>|<expected length>|<pad character>}}
• {{string|padright|source = <source string>|len = <expected length>|char = <pad character>}}

str.explode(frame) (function)

Return delimited string piece, like PHP's explode(). Indexing is 0-based to match the behavior of {{#explode}} parser function.

Parameters:

• frame Invocation frame object. (table)
  • frame.args Invocation/template arguments. (table)
    • frame.args.source Delimited string to split. (string)
    • frame.args.dlm Symbol or character to split with. (string)
    • frame.args.pos Initial piece position. Default: 0. (string; optional)
    • frame.args.lim Maximum number of pieces to append. Default: 1. (string; optional)

Returns: Percent-encoded string. (string)

Usage:

• {{string|explode|<source string>|<delimiter>|<position 0-index>|<piece limit>}}
• {{string|explode|source = <source string>|dlm = <delimiter>|pos = <position 0-index>|lim = <piece limit>}}

str.urlencode(frame) (function)

Percent-encoding for strings.

Parameters:

• frame Invocation frame object. (table)
  • frame.args Invocation/template arguments. (table)
    • frame.args.source Source string to encode. (string)
    • frame.args.code Encoding type (QUERY, PATH, WIKI). (string)

Returns: Percent-encoded string. (string)

Usage:

• {{string|urlencode|<unencoded string>}}
• {{string|urlencode|source = <unencoded string>|code = <encoding type>}}

str.urldecode(frame) (function)

URL decoding for strings.

Parameters:

• frame Invocation frame object. (table)
  • frame.args Invocation/template arguments. (table)
    • frame.args.source Source string to decode. (string)
    • frame.args.code Encoding type (QUERY, PATH, WIKI). (string)

Returns: Percent-decoded string. (string)

Usage:

• {{string|urldecode|<percent-encoded string>}}
• {{string|urldecode|source = <percent-encoded string>|code = <encoding type>}}

str.htmlencode(frame) (function)

Replaces characters in a string with HTML entities.

Parameters:

• frame Invocation frame object. (table)
  • frame.args Invocation/template arguments. (table)
    • frame.args.s Source string to encode. (string)
    • frame.args.charset A string as appropriate to go inside brackets in a Ustring pattern. (string)

Returns: HTML-encoded string. (string)

Usage:

• {{string|htmlencode|<unencoded string>}}
• {{string|htmlencode|s = <unencoded string>|code = <encoding type>}}

str.htmldecode(frame) (function)

Replaces HTML entities in the string with the corresponding characters.

Parameters:

• frame Invocation frame object. (table)
  • frame.args Invocation/template arguments. (table)
    • frame.args.s Source string to decode. (string)
    • frame.args.decodeNamedEntities If decodeNamedEntities is omitted or false, the only named entities recognized are '<', '>', '&', and '"'. Otherwise, the list of HTML5 named entities to recognize is loaded from PHP's get_html_translation_table function. (string)

Returns: Decoded string. (string)

Usage:

• {{string|htmldecode|<encoded string>}}
• {{string|htmldecode|s = <encoded string>|decodeNamedEntities = <something>}}

Helper functions

str._getParameters(frame_args, arg_list) (function)

Populates an argument list with both named/unnamed parameters. This is relevant because named parameters are not identical to unnamed parameters due to string trimming, and when dealing with strings we sometimes want to either preserve or remove that whitespace depending on the application.

Parameters:

• frame_args Table of sequential and named arguments. (table)
• arg_list Array of parameter names. (table)

Returns: Map of named arguments corresponding to arg_list. (table)

str._error(exception, frame) (function)

Helper function to handle error messages.

Parameters:

• exception Error string to display to user. (string)
• frame Current frame object (from string template or module). (table)

Returns: Optional error message, with or without categorisation. (string)

str._getBoolean(str) (function)

Helper function to interpret boolean strings.

Parameter: str Boolean-like wikitext string. (string)

Returns: Boolean value corresponding to str. (boolean)

str._escapePattern(pattern_str) (function)

Helper function that escapes all pattern characters. This allows patterns to be treated as plain text.

Parameter: pattern_str Lua pattern string with special characters. (string)

Returns: Escaped Lua pattern string for literal string matches. (string)

str.main() (function)

Wrapper function for string template.

Usage: {{string|function|<...>}}

See also

• Wikipedia documentation
• Test suite for module