DivošiRunner: Fill documented site and template gaps; repair verified links and flag uncertain file rights

2026-10-05T15:12:03Z

Fill documented site and template gaps; repair verified links and flag uncertain file rights

New page

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

== Functions ==
Invoke with <code><nowiki>{{#invoke:String|function|arguments}}</nowiki></code>. The following names describe the deployed implementation.

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

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

== Examples ==
{| class="wikitable"
! Invocation !! Result
|-
| <code><nowiki>{{#invoke:String|len|abc}}</nowiki></code> || {{#invoke:String|len|abc}}
|-
| <code><nowiki>{{#invoke:String|sub|abcdef|2|4}}</nowiki></code> || {{#invoke:String|sub|abcdef|2|4}}
|-
| <code><nowiki>{{#invoke:String|find|abcabc|bc}}</nowiki></code> || {{#invoke:String|find|abcabc|bc}}
|-
| <code><nowiki>{{#invoke:String|replace|source=a.b|pattern=.|replace=-}}</nowiki></code> || {{#invoke:String|replace|source=a.b|pattern=.|replace=-}}
|-
| <code><nowiki>{{#invoke:String|join| / |one||two}}</nowiki></code> || {{#invoke:String|join| / |one||two}}
|}

== Patterns and errors ==
Lua patterns are not regular expressions; see [https://www.lua.org/manual/5.1/manual.html#5.4.1 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. <code>ignore_errors=true</code> or <code>1</code> suppresses that output, <code>no_category=true</code> or <code>1</code> suppresses the category, and <code>error_category</code> changes its name. These options do not catch every possible Lua runtime error. Functions whose names begin with an underscore are implementation helpers.
[[Category:Template documentation]]

Module:String/doc - Revision history

DivošiRunner: Fill documented site and template gaps; repair verified links and flag uncertain file rights