Export translations

Group:

Language:

Format

Export for off-line translation

Export in native format

Export in CSV format

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

{{Magic words|general=1}}
{{Module rating|release}}
{{Module rating|protected}}
<div lang="en" dir="ltr" class="mw-content-ltr">
This module is intended to provide access to basic string functions.
</div>

<span lang="en" dir="ltr" class="mw-content-ltr">Most of the functions provided here can be invoked with named parameters, unnamed parameters, or a mixture.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">If named parameters are used, MediaWiki will automatically remove any leading or trailing whitespace from the parameter.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Depending on the intended use, it may be advantageous to either preserve or remove such whitespace.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
== Global options ==
</div>

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

<div lang="en" dir="ltr" class="mw-content-ltr">
Unit tests for this module are available at [[Module:String/testcases]].
</div>

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

<div lang="en" dir="ltr" class="mw-content-ltr">
This function returns the length of the target string.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Usage:
</div>

: {{tmpl|0=<code><nowiki>{{#invoke:</nowiki>String{{!}}len{{!}}''$1''<nowiki>}}</nowiki></code>
|1=<span lang="en" dir="ltr" class="mw-content-ltr">target_string</span>
}}

: {{tmpl|0=<code><nowiki>{{#invoke:</nowiki>String{{!}}len{{!}}s= ''$1'' <nowiki>}}</nowiki></code>
|1=<span lang="en" dir="ltr" class="mw-content-ltr">target_string</span>
}}

<div lang="en" dir="ltr" class="mw-content-ltr">
Parameters:
</div>

; <code>s</code>
: <span lang="en" dir="ltr" class="mw-content-ltr">The string whose length to report</span>

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

: <span lang="en" dir="ltr" class="mw-content-ltr">This function returns a substring of the target string at specified indices.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
Usage:
</div>

: {{tmpl|0=<code><nowiki>{{#invoke:</nowiki>String{{!}}sub{{!}}''$1''{{!}}''$2''{{!}}''$3''<nowiki>}}</nowiki></code>
|1=<span lang="en" dir="ltr" class="mw-content-ltr">target_string</span>
|2=<span lang="en" dir="ltr" class="mw-content-ltr">start_index</span>
|3=<span lang="en" dir="ltr" class="mw-content-ltr">end_index</span>
}}

: {{tmpl|0=<code><nowiki>{{#invoke:</nowiki>String{{!}}sub<wbr/>{{!}}s= ''$1'' {{!}}i= ''$2'' {{!}}j= ''$3'' <nowiki>}}</nowiki></code>
|1=<span lang="en" dir="ltr" class="mw-content-ltr">target_string</span>
|2=<span lang="en" dir="ltr" class="mw-content-ltr">start_index</span>
|3=<span lang="en" dir="ltr" class="mw-content-ltr">end_index</span>
}}

<div lang="en" dir="ltr" class="mw-content-ltr">
Parameters:
</div>

; <code>s</code>
: <span lang="en" dir="ltr" class="mw-content-ltr">The string to return a subset of</span>
; <code>i</code>
: <span lang="en" dir="ltr" class="mw-content-ltr">The first index of the substring to return, defaults to 1.</span>
; <code>j</code>
: <span lang="en" dir="ltr" class="mw-content-ltr">The last index of the string to return, defaults to the last character.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">The first character of the string is assigned an index of 1.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">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.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Hence, a value of -1 is the same as selecting the last character of the string.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
If the requested indices are out of range for the given string, an error is reported.
</div>

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

<div lang="en" dir="ltr" class="mw-content-ltr">
This function returns a substring from the source string that matches a specified pattern.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Usage:
</div>

: {{tmpl|0=<code><nowiki>{{#invoke:</nowiki>String{{!}}match{{!}}''$1''{{!}}''$2''{{!}}''$3''{{!}}''$4''{{!}}''$5''{{!}}''$6''<nowiki>}}</nowiki></code>
|1=<span lang="en" dir="ltr" class="mw-content-ltr">source_string</span>
|2=<span lang="en" dir="ltr" class="mw-content-ltr">pattern_string</span>
|3=<span lang="en" dir="ltr" class="mw-content-ltr">start_index</span>
|4=<span lang="en" dir="ltr" class="mw-content-ltr">match_number</span>
|5=<span lang="en" dir="ltr" class="mw-content-ltr">plain_flag</span>
|6=<span lang="en" dir="ltr" class="mw-content-ltr">nomatch_output</span>
}}

: {{tmpl|0=<code><nowiki>{{#invoke:</nowiki>String{{!}}match{{!}}s= ''$1'' {{!}}pattern= ''$2'' {{!}}start= ''$3'' {{!}}match= ''$4'' {{!}}plain= ''$5'' {{!}}nomatch= ''$6'' <nowiki>}}</nowiki></code>
|1=<span lang="en" dir="ltr" class="mw-content-ltr">source_string</span>
|2=<span lang="en" dir="ltr" class="mw-content-ltr">pattern_string</span>
|3=<span lang="en" dir="ltr" class="mw-content-ltr">start_index</span>
|4=<span lang="en" dir="ltr" class="mw-content-ltr">match_number</span>
|5=<span lang="en" dir="ltr" class="mw-content-ltr">plain_flag</span>
|6=<span lang="en" dir="ltr" class="mw-content-ltr">nomatch_output</span>
}}

<div lang="en" dir="ltr" class="mw-content-ltr">
Parameters:
</div>

; <code>s</code>
: <span lang="en" dir="ltr" class="mw-content-ltr">The string to search</span>
; <code>pattern</code>
: <span lang="en" dir="ltr" class="mw-content-ltr">The pattern or string to find within the string</span>
; <code>start</code>
: <span lang="en" dir="ltr" class="mw-content-ltr">The index within the source string to start the search.</span> <span lang="en" dir="ltr" class="mw-content-ltr">The first character of the string has index 1.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Defaults to 1.</span>
; <code>match</code>
: <span lang="en" dir="ltr" class="mw-content-ltr">In some cases it may be possible to make multiple matches on a single string.</span> <span lang="en" dir="ltr" class="mw-content-ltr">This specifies which match to return, where the first match is <code>match = 1</code>.</span> <span lang="en" dir="ltr" class="mw-content-ltr">If a negative number is specified then a match is returned counting from the last match.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Hence <code>match = -1</code> is the same as requesting the last match.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Defaults to 1.</span>
; <code>plain</code>
: <span lang="en" dir="ltr" class="mw-content-ltr">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]].</span> <span lang="en" dir="ltr" class="mw-content-ltr">Defaults to {{phpi|false}}.</span>
; <code>nomatch</code>
: <span lang="en" dir="ltr" class="mw-content-ltr">If no match is found, output the "nomatch" value rather than an error.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">If the <code>match</code> or <code>start</code> are out of range for the string being queried, then this function generates an error.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">An error is also generated if no match is found.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">If one adds the parameter <code>ignore_errors=true</code>, then the error will be suppressed and an empty string will be returned on any failure.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
For information on constructing [[w:Lua (programming language)|Lua]] patterns, a form of [[w:Regular expression|regular expression]], see:
</div>

* [https://www.lua.org/manual/5.1/manual.html#5.4.1 <span lang="en" dir="ltr" class="mw-content-ltr">Lua reference: Patterns</span>] - <span lang="en" dir="ltr" class="mw-content-ltr">as of version 5.1</span>
* {{ll|Extension:Scribunto/Lua reference manual#Patterns|2=<span lang="en" dir="ltr" class="mw-content-ltr">Scribunto patterns</span>}}
* {{ll|Extension:Scribunto/Lua reference manual#Ustring patterns|2=<span lang="en" dir="ltr" class="mw-content-ltr">Scribunto Unicode string patterns</span>}}

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

<div lang="en" dir="ltr" class="mw-content-ltr">
This function returns a single character from the target string at position pos.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Usage:
</div>

: {{tmpl|0=<code><nowiki>{{#invoke:</nowiki>String{{!}}pos{{!}}''$1''{{!}}''$2''<nowiki>}}</nowiki></code>
|1=<span lang="en" dir="ltr" class="mw-content-ltr">target_string</span>
|2=<span lang="en" dir="ltr" class="mw-content-ltr">index_value</span>
}}

: {{tmpl|0=<code><nowiki>{{#invoke:</nowiki>String{{!}}pos{{!}}target= ''$1'' {{!}}pos= ''$2'' <nowiki>}}</nowiki></code>
|1=<span lang="en" dir="ltr" class="mw-content-ltr">target_string</span>
|2=<span lang="en" dir="ltr" class="mw-content-ltr">index_value</span>
}}

<div lang="en" dir="ltr" class="mw-content-ltr">
Parameters:
</div>

; <code>target</code>
: <span lang="en" dir="ltr" class="mw-content-ltr">The string to search</span>
; <code>pos</code>
: <span lang="en" dir="ltr" class="mw-content-ltr">The index for the character to return</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
The first character has an index value of 1.
</div>

<span lang="en" dir="ltr" class="mw-content-ltr">If one requests a negative value, this function will select a character by counting backwards from the end of the string.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">In other words <code>pos = -1</code> is the same as asking for the last character.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
A requested value of zero, or a value greater than the length of the string returns an error.
</div>

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

<div lang="en" dir="ltr" class="mw-content-ltr">
This function allows one to search for a target string or pattern within another string.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Usage:
</div>

: {{tmpl|0=<code><nowiki>{{#invoke:</nowiki>String{{!}}find{{!}}''$1''{{!}}''$2''{{!}}''$3''{{!}}''$4''<nowiki>}}</nowiki></code>
|1=<span lang="en" dir="ltr" class="mw-content-ltr">source_str</span>
|2=<span lang="en" dir="ltr" class="mw-content-ltr">target_string</span>
|3=<span lang="en" dir="ltr" class="mw-content-ltr">start_index</span>
|4=<span lang="en" dir="ltr" class="mw-content-ltr">plain_flag</span>
}}

: {{tmpl|0=<code><nowiki>{{#invoke:</nowiki>String{{!}}find{{!}}source= ''$1'' {{!}}target= ''$2'' {{!}}start= ''$3'' {{!}}plain= ''$4'' <nowiki>}}</nowiki></code>
|1=<span lang="en" dir="ltr" class="mw-content-ltr">source_str</span>
|2=<span lang="en" dir="ltr" class="mw-content-ltr">target_str</span>
|3=<span lang="en" dir="ltr" class="mw-content-ltr">start_index</span>
|4=<span lang="en" dir="ltr" class="mw-content-ltr">plain_flag</span>
}}

<div lang="en" dir="ltr" class="mw-content-ltr">
Parameters:
</div>

; <code>source</code>
: <span lang="en" dir="ltr" class="mw-content-ltr">The string to search</span>
; <code>target</code>
: <span lang="en" dir="ltr" class="mw-content-ltr">The string or pattern to find within source</span>
; <code>start</code>
: <span lang="en" dir="ltr" class="mw-content-ltr">The index within the source string to start the search, defaults to 1</span>
; <code>plain</code>
: <span lang="en" dir="ltr" class="mw-content-ltr">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 {{phpi|true}}</span>

<span lang="en" dir="ltr" class="mw-content-ltr">This function returns the first index >= "start" where "target" can be found within "source".</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Indices are 1-based.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">If "target" is not found, then this function returns 0.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">If either "source" or "target" are missing / empty, this function also returns 0.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
This function should be safe for UTF-8 strings.
</div>

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

<div lang="en" dir="ltr" class="mw-content-ltr">
This function allows one to replace a target string or pattern within another string.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Usage:
</div>

: {{tmpl|0=<code><nowiki>{{#invoke:</nowiki>String{{!}}replace{{!}}''$1''{{!}}''$2''{{!}}''$3''{{!}}''$4''{{!}}''$5''<nowiki>}}</nowiki></code>
|1=<span lang="en" dir="ltr" class="mw-content-ltr">source_str</span>
|2=<span lang="en" dir="ltr" class="mw-content-ltr">pattern_string</span>
|3=<span lang="en" dir="ltr" class="mw-content-ltr">replace_string</span>
|4=<span lang="en" dir="ltr" class="mw-content-ltr">replacement_count</span>
|5=<span lang="en" dir="ltr" class="mw-content-ltr">plain_flag</span>
}}

: {{tmpl|0=<code><nowiki>{{#invoke:</nowiki>String{{!}}replace{{!}}source= ''$1'' {{!}}pattern= ''$2'' {{!}}replace= ''$3'' {{!}}count= ''$4'' {{!}}plain= ''$5'' <nowiki>}}</nowiki></code>
|1=<span lang="en" dir="ltr" class="mw-content-ltr">source_string</span>
|2=<span lang="en" dir="ltr" class="mw-content-ltr">pattern_string</span>
|3=<span lang="en" dir="ltr" class="mw-content-ltr">replace_string</span>
|4=<span lang="en" dir="ltr" class="mw-content-ltr">replacement_count</span>
|5=<span lang="en" dir="ltr" class="mw-content-ltr">plain_flag</span>
}}

<div lang="en" dir="ltr" class="mw-content-ltr">
Parameters:
</div>

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

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

<div lang="en" dir="ltr" class="mw-content-ltr">
Repeats a string ''n'' times.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Usage:
</div>

: {{tmpl|0=<code><nowiki>{{#invoke:</nowiki>String{{!}}rep{{!}}''$1''{{!}}''$2''<nowiki>}}</nowiki></code>
|1=<span lang="en" dir="ltr" class="mw-content-ltr">source</span>
|2=<span lang="en" dir="ltr" class="mw-content-ltr">count</span>
}}

<div lang="en" dir="ltr" class="mw-content-ltr">
Parameters:
</div>

; <code>source</code>
: <span lang="en" dir="ltr" class="mw-content-ltr">The string to repeat</span>
; <code>count</code>
: <span lang="en" dir="ltr" class="mw-content-ltr">The number of repetitions.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
Example {{tmpl|0=<code><nowiki>{{#invoke:</nowiki>String{{!}}rep{{!}}$1{{!}}3<nowiki>}}</nowiki></code>|hello}} gives {{tmpl|0={{#invoke:String|rep|$1|3}}|hello}}
</div>
<includeonly>{{Sandbox other||

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