NinjaLikesCheez: 1 revision imported: Module:String

2025-08-27T14:27:48Z

1 revision imported: Module:String

← Older revision	Revision as of 14:27, 27 August 2025
(No difference)

mediawikiwiki>Waddie96: {{Magic words|general=1}}

2025-08-20T08:06:54Z

New page

<noinclude>{{#ifeq:{{SUBPAGENAME}}|doc||{{Documentation subpage}}}}<languages/></noinclude>{{#switch:<translate></translate>
| =
<includeonly>{{Languages|Module:String/doc}}</includeonly>

{{Magic words|general=1}}
{{Shared Template Warning|Module:String}}
{{Module rating|release}}
{{Module rating|protected}}
<translate>

This module is intended to provide access to basic string functions.
</translate>

<translate> Most of the functions provided here can be invoked with named parameters, unnamed parameters, or a mixture.</translate>
<translate> If named parameters are used, MediaWiki will automatically remove any leading or trailing whitespace from the parameter.</translate>
<translate> Depending on the intended use, it may be advantageous to either preserve or remove such whitespace.</translate>

<translate>
== Global options == 
</translate>

; <code>ignore_errors</code>
: <translate> If set to <tvar name=1>{{phpi|true}}</tvar> or <tvar name=2>1</tvar>, any error condition will result in an empty string being returned rather than an error message.</translate>
; <code>error_category</code>
: <translate> If an error occurs, specifies the name of a category to include with the error message.</translate> <translate> The default category is <tvar name=1>{{ll|Category:Errors reported by Module String}}</tvar>.</translate>
; <code>no_category</code>
: <translate> If set to <tvar name=1>{{phpi|true}}</tvar> or <tvar name=2>1</tvar>, no category will be added if an error is generated.</translate>

<translate>

Unit tests for this module are available at <tvar name=1>[[Module:String/testcases]]</tvar>.
</translate>

== <code>len</code> ==

<translate>

This function returns the length of the target string.


Usage:
</translate>

: {{tmpl|0=<code><nowiki>{{#invoke:</nowiki>String{{!}}len{{!}}''$1''<nowiki>}}</nowiki></code>
|1=<translate> target_string</translate>
}}

<translate>

or
</translate>

: {{tmpl|0=<code><nowiki>{{#invoke:</nowiki>String{{!}}len{{!}}s= ''$1'' <nowiki>}}</nowiki></code>
|1=<translate> target_string</translate>
}}

<translate>

Parameters:
</translate>

; <code>s</code>
: <translate> The string whose length to report</translate>

== <code>sub</code> ==

: <translate> This function returns a substring of the target string at specified indices.</translate>

<translate>

Usage:
</translate>

: {{tmpl|0=<code><nowiki>{{#invoke:</nowiki>String{{!}}sub{{!}}''$1''{{!}}''$2''{{!}}''$3''<nowiki>}}</nowiki></code>
|1=<translate> target_string</translate>
|2=<translate> start_index</translate>
|3=<translate> end_index</translate>
}}

<translate>

OR
</translate>

: {{tmpl|0=<code><nowiki>{{#invoke:</nowiki>String{{!}}sub<wbr/>{{!}}s= ''$1'' {{!}}i= ''$2'' {{!}}j= ''$3'' <nowiki>}}</nowiki></code>
|1=<translate> target_string</translate>
|2=<translate> start_index</translate>
|3=<translate> end_index</translate>
}}

<translate>

Parameters:
</translate>

; <code>s</code>
: <translate> The string to return a subset of</translate>
; <code>i</code>
: <translate> The first index of the substring to return, defaults to 1.</translate>
; <code>j</code>
: <translate> The last index of the string to return, defaults to the last character.</translate>

<translate> The first character of the string is assigned an index of 1.</translate>
<translate> If either <tvar name=1>i</tvar> or <tvar name=2>j</tvar> is a negative value, it is interpreted the same as selecting a character by counting from the end of the string.</translate>
<translate> Hence, a value of -1 is the same as selecting the last character of the string.</translate>

<translate>

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

== <code>match</code> ==

<translate>

This function returns a substring from the source string that matches a specified pattern.


Usage:
</translate>

: {{tmpl|0=<code><nowiki>{{#invoke:</nowiki>String{{!}}match{{!}}''$1''{{!}}''$2''{{!}}''$3''{{!}}''$4''{{!}}''$5''{{!}}''$6''<nowiki>}}</nowiki></code>
|1=<translate> source_string</translate>
|2=<translate> pattern_string</translate>
|3=<translate> start_index</translate>
|4=<translate> match_number</translate>
|5=<translate> plain_flag</translate>
|6=<translate> nomatch_output</translate>
}}

<translate>

OR
</translate>

: {{tmpl|0=<code><nowiki>{{#invoke:</nowiki>String{{!}}match{{!}}s= ''$1'' {{!}}pattern= ''$2'' {{!}}start= ''$3'' {{!}}match= ''$4'' {{!}}plain= ''$5'' {{!}}nomatch= ''$6'' <nowiki>}}</nowiki></code>
|1=<translate> source_string</translate>
|2=<translate> pattern_string</translate>
|3=<translate> start_index</translate>
|4=<translate> match_number</translate>
|5=<translate> plain_flag</translate>
|6=<translate> nomatch_output</translate>
}}

<translate>

Parameters:
</translate>

; <code>s</code>
: <translate> The string to search</translate>
; <code>pattern</code>
: <translate> The pattern or string to find within the string</translate>
; <code>start</code>
: <translate> The index within the source string to start the search.</translate> <translate> The first character of the string has index 1.</translate> <translate> Defaults to 1.</translate>
; <code>match</code>
: <translate> In some cases it may be possible to make multiple matches on a single string.</translate> <translate> This specifies which match to return, where the first match is <tvar name=1><code>match = 1</code></tvar>.</translate> <translate> If a negative number is specified then a match is returned counting from the last match.</translate> <translate> Hence <tvar name=1><code>match = -1</code></tvar> is the same as requesting the last match.</translate> <translate> Defaults to 1.</translate>
; <code>plain</code>
: <translate> Boolean flag indicating that pattern should be understood as plain text and not as a [[w:Lua (programming language)|Lua]]-style [[w:Regular expression|regular expression]].</translate> <translate> Defaults to <tvar name=1>{{phpi|false}}</tvar>.</translate>
; <code>nomatch</code>
: <translate> If no match is found, output the "<tvar name=1>nomatch</tvar>" value rather than an error.</translate>

<translate> If the <tvar name=1><code>match</code></tvar> or <tvar name=2><code>start</code></tvar> are out of range for the string being queried, then this function generates an error.</translate>
<translate> An error is also generated if no match is found.</translate>
<translate> If one adds the parameter <tvar name=1><code>ignore_errors=true</code></tvar>, then the error will be suppressed and an empty string will be returned on any failure.</translate>

<translate>

For information on constructing [[w:Lua (programming language)|Lua]] patterns, a form of [[w:Regular expression|regular expression]], see:
</translate>

* [https://www.lua.org/manual/5.1/manual.html#5.4.1 <translate> Lua reference: Patterns</translate>] - <translate> as of version 5.1</translate>
* {{ll|Extension:Scribunto/Lua reference manual#Patterns|2=<translate> Scribunto patterns</translate>}}
* {{ll|Extension:Scribunto/Lua reference manual#Ustring patterns|2=<translate> Scribunto Unicode string patterns</translate>}}

== <code>pos</code> ==

<translate>

This function returns a single character from the target string at position pos.


Usage:
</translate>

: {{tmpl|0=<code><nowiki>{{#invoke:</nowiki>String{{!}}pos{{!}}''$1''{{!}}''$2''<nowiki>}}</nowiki></code>
|1=<translate> target_string</translate>
|2=<translate> index_value</translate>
}}

<translate>

OR
</translate>

: {{tmpl|0=<code><nowiki>{{#invoke:</nowiki>String{{!}}pos{{!}}target= ''$1'' {{!}}pos= ''$2'' <nowiki>}}</nowiki></code>
|1=<translate> target_string</translate>
|2=<translate> index_value</translate>
}}

<translate>

Parameters:
</translate>

; <code>target</code>
: <translate> The string to search</translate>
; <code>pos</code>
: <translate> The index for the character to return</translate>

<translate>

The first character has an index value of 1.
</translate>

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

<translate>

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

== <code>find</code> ==

<translate>

This function allows one to search for a target string or pattern within another string.


Usage:
</translate>

: {{tmpl|0=<code><nowiki>{{#invoke:</nowiki>String{{!}}find{{!}}''$1''{{!}}''$2''{{!}}''$3''{{!}}''$4''<nowiki>}}</nowiki></code>
|1=<translate> source_str</translate>
|2=<translate> target_string</translate>
|3=<translate> start_index</translate>
|4=<translate> plain_flag</translate>
}}

<translate>

OR
</translate>

: {{tmpl|0=<code><nowiki>{{#invoke:</nowiki>String{{!}}find{{!}}source= ''$1'' {{!}}target= ''$2'' {{!}}start= ''$3'' {{!}}plain= ''$4'' <nowiki>}}</nowiki></code>
|1=<translate> source_str</translate>
|2=<translate> target_str</translate>
|3=<translate> start_index</translate>
|4=<translate> plain_flag</translate>
}}

<translate>

Parameters:
</translate>

; <code>source</code>
: <translate> The string to search</translate>
; <code>target</code>
: <translate> The string or pattern to find within source</translate>
; <code>start</code>
: <translate> The index within the source string to start the search, defaults to 1</translate>
; <code>plain</code>
: <translate> Boolean flag indicating that target should be understood as plain text and not as a [[w:Lua (programming language)|Lua]]-style [[w:Regular expression|regular expression]], defaults to <tvar name=1>{{phpi|true}}</tvar></translate>

<translate> This function returns the first index >= "<tvar name=1>start</tvar>" where "<tvar name=2>target</tvar>" can be found within "<tvar name=3>source</tvar>".</translate>
<translate> Indices are 1-based.</translate>
<translate> If "<tvar name=1>target</tvar>" is not found, then this function returns 0.</translate>
<translate> If either "<tvar name=1>source</tvar>" or "<tvar name=2>target</tvar>" are missing / empty, this function also returns 0.</translate>

<translate>

This function should be safe for UTF-8 strings.
</translate>

== <code>replace</code> ==

<translate>

This function allows one to replace a target string or pattern within another string.


Usage:
</translate>

: {{tmpl|0=<code><nowiki>{{#invoke:</nowiki>String{{!}}replace{{!}}''$1''{{!}}''$2''{{!}}''$3''{{!}}''$4''{{!}}''$5''<nowiki>}}</nowiki></code>
|1=<translate> source_str</translate>
|2=<translate> pattern_string</translate>
|3=<translate> replace_string</translate>
|4=<translate> replacement_count</translate>
|5=<translate> plain_flag</translate>
}}

<translate>

OR
</translate>

: {{tmpl|0=<code><nowiki>{{#invoke:</nowiki>String{{!}}replace{{!}}source= ''$1'' {{!}}pattern= ''$2'' {{!}}replace= ''$3'' {{!}}count= ''$4'' {{!}}plain= ''$5'' <nowiki>}}</nowiki></code>
|1=<translate> source_string</translate>
|2=<translate> pattern_string</translate>
|3=<translate> replace_string</translate>
|4=<translate> replacement_count</translate>
|5=<translate> plain_flag</translate>
}}

<translate>

Parameters:
</translate>

; <code>source</code>
: <translate> The string to search</translate>
; <code>pattern</code>
: <translate> The string or pattern to find within source</translate>
; <code>replace</code>
: <translate> The replacement text</translate>
; <code>count</code>
: <translate> The number of occurrences to replace; defaults to all</translate>
; <code>plain</code>
: <translate> Boolean flag indicating that pattern should be understood as plain text and not as a [[<tvar name=1>Special:MyLanguage/Extension:Scribunto/Lua reference manual#Ustring patterns</tvar>|Scribunto ustring pattern]] (a unicode-friendly [[w:Lua (programming language)|Lua]]-style [[w:Regular expression|regular expression]]); defaults to <tvar name=2>{{phpi|true}}</tvar></translate>

== <code>rep</code> ==

<translate>

Repeats a string ''n'' times.


Usage:
</translate>

: {{tmpl|0=<code><nowiki>{{#invoke:</nowiki>String{{!}}rep{{!}}''$1''{{!}}''$2''<nowiki>}}</nowiki></code>
|1=<translate> source</translate>
|2=<translate> count</translate>
}}

<translate>

Parameters:
</translate>

; <code>source</code>
: <translate> The string to repeat</translate>
; <code>count</code>
: <translate> The number of repetitions.</translate>

<translate>

Example {{<tvar name=1>tmpl|0=<code><nowiki>{{#invoke:</nowiki>String{{!}}rep{{!}}$1{{!}}3<nowiki>}}</nowiki></code></tvar>|hello}} gives {{<tvar name=2>tmpl|0={{#invoke:String|rep|$1|3}}</tvar>|hello}}
</translate>
<includeonly>{{Sandbox other||

[[Category:Modules]]
}}</includeonly><noinclude>
[[Category:Module documentation pages{{#translation:}}]]
</noinclude>
| #default=
{{#invoke:Template translation|renderTranslatedTemplate|template=Module:String/doc|noshift=1|uselang={{int:lang}}}}
}}

Module:String/doc - Revision history

NinjaLikesCheez: 1 revision imported: Module:String

mediawikiwiki>Waddie96: {{Magic words|general=1}}