Quelltext der Seite Modul:String/doc

<noinclude><!--
-->{{#ifeq:{{SUBPAGENAME}}|doc||{{Documentation subpage}}}}<!--
--><languages/><!--
--></noinclude>{{#switch:<translate></translate>
| =
<includeonly>{{Languages|Module:String/doc}}</includeonly>
<!-- Add categories where indicated at the bottom of this page and interwikis at Wikidata -->
{{Shared Template Warning|Module:String}}
{{Module rating|release}}
{{Module rating|protected}}
<translate>
<!--T:1-->
This module is intended to provide access to basic string functions.
</translate>

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

<translate>
== Global options == <!--T:5-->
</translate>

; <code>ignore_errors</code>
: <translate><!--T:6--> 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><!--T:7--> If an error occurs, specifies the name of a category to include with the error message.</translate> <translate><!--T:8--> The default category is <tvar name=1>{{ll|Category:Errors reported by Module String}}</tvar>.</translate>
; <code>no_category</code>
: <translate><!--T:9--> 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>
<!--T:10-->
Unit tests for this module are available at <tvar name=1>[[Module:String/testcases]]</tvar>.
</translate>

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

<translate>
<!--T:11-->
This function returns the length of the target string.

<!--T:12-->
Usage:
</translate>

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

<translate>
<!--T:14-->
OR
</translate>

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

<translate>
<!--T:16-->
Parameters:
</translate>

; <code>s</code>
: <translate><!--T:17--> The string whose length to report</translate>

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

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

<translate>
<!--T:19-->
Usage:
</translate>

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

<translate>
<!--T:23-->
OR
</translate>

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

<translate>
<!--T:27-->
Parameters:
</translate>

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

<translate><!--T:31--> The first character of the string is assigned an index of 1.</translate>
<translate><!--T:32--> 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><!--T:33--> Hence, a value of -1 is the same as selecting the last character of the string.</translate>

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

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

<translate>
<!--T:35-->
This function returns a substring from the source string that matches a specified pattern.

<!--T:36-->
Usage:
</translate>

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

<translate>
<!--T:43-->
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><!--T:44--> source_string</translate>
|2=<translate><!--T:45--> pattern_string</translate>
|3=<translate><!--T:46--> start_index</translate>
|4=<translate><!--T:47--> match_number</translate>
|5=<translate><!--T:48--> plain_flag</translate>
|6=<translate><!--T:49--> nomatch_output</translate>
}}

<translate>
<!--T:50-->
Parameters:
</translate>

; <code>s</code>
: <translate><!--T:51--> The string to search</translate>
; <code>pattern</code>
: <translate><!--T:52--> The pattern or string to find within the string</translate>
; <code>start</code>
: <translate><!--T:53--> The index within the source string to start the search.</translate> <translate><!--T:54--> The first character of the string has index 1.</translate> <translate><!--T:55--> Defaults to 1.</translate>
; <code>match</code>
: <translate><!--T:56--> In some cases it may be possible to make multiple matches on a single string.</translate> <translate><!--T:57--> This specifies which match to return, where the first match is <tvar name=1><code>match = 1</code></tvar>.</translate> <translate><!--T:58--> If a negative number is specified then a match is returned counting from the last match.</translate> <translate><!--T:59--> Hence <tvar name=1><code>match = -1</code></tvar> is the same as requesting the last match.</translate> <translate><!--T:60--> Defaults to 1.</translate>
; <code>plain</code>
: <translate><!--T:61--> 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><!--T:62--> Defaults to <tvar name=1>{{phpi|false}}</tvar>.</translate>
; <code>nomatch</code>
: <translate><!--T:63--> If no match is found, output the "<tvar name=1>nomatch</tvar>" value rather than an error.</translate>

<translate><!--T:64--> 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><!--T:65--> An error is also generated if no match is found.</translate>
<translate><!--T:66--> 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>
<!--T:67-->
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><!--T:68--> Lua reference: Patterns</translate>] - <translate><!--T:69--> as of version 5.1</translate>
* {{ll|Extension:Scribunto/Lua reference manual#Patterns|2=<translate><!--T:70--> Scribunto patterns</translate>}}
* {{ll|Extension:Scribunto/Lua reference manual#Ustring patterns|2=<translate><!--T:71--> Scribunto Unicode string patterns</translate>}}

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

<translate>
<!--T:72-->
This function returns a single character from the target string at position pos.

<!--T:73-->
Usage:
</translate>

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

<translate>
<!--T:74-->
OR
</translate>

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

<translate>
<!--T:77-->
Parameters:
</translate>

; <code>target</code>
: <translate><!--T:78--> The string to search</translate>
; <code>pos</code>
: <translate><!--T:79--> The index for the character to return</translate>

<translate>
<!--T:80-->
The first character has an index value of 1.
</translate>

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

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

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

<translate>
<!--T:84-->
This function allows one to search for a target string or pattern within another string.

<!--T:85-->
Usage:
</translate>

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

<translate>
<!--T:90-->
OR
</translate>

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

<translate>
<!--T:95-->
Parameters:
</translate>

; <code>source</code>
: <translate><!--T:96--> The string to search</translate>
; <code>target</code>
: <translate><!--T:97--> The string or pattern to find within source</translate>
; <code>start</code>
: <translate><!--T:98--> The index within the source string to start the search, defaults to 1</translate>
; <code>plain</code>
: <translate><!--T:99--> 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><!--T:100--> 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><!--T:101--> Indices are 1-based.</translate>
<translate><!--T:102--> If "<tvar name=1>target</tvar>" is not found, then this function returns 0.</translate>
<translate><!--T:103--> If either "<tvar name=1>source</tvar>" or "<tvar name=2>target</tvar>" are missing / empty, this function also returns 0.</translate>

<translate>
<!--T:104-->
This function should be safe for UTF-8 strings.
</translate>

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

<translate>
<!--T:105-->
This function allows one to replace a target string or pattern within another string.

<!--T:106-->
Usage:
</translate>

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

<translate>
<!--T:112-->
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><!--T:113--> source_string</translate>
|2=<translate><!--T:114--> pattern_string</translate>
|3=<translate><!--T:115--> replace_string</translate>
|4=<translate><!--T:116--> replacement_count</translate>
|5=<translate><!--T:117--> plain_flag</translate>
}}

<translate>
<!--T:118-->
Parameters:
</translate>

; <code>source</code>
: <translate><!--T:119--> The string to search</translate>
; <code>pattern</code>
: <translate><!--T:120--> The string or pattern to find within source</translate>
; <code>replace</code>
: <translate><!--T:121--> The replacement text</translate>
; <code>count</code>
: <translate><!--T:122--> The number of occurrences to replace; defaults to all</translate>
; <code>plain</code>
: <translate><!--T:123--> 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>
<!--T:124-->
Repeats a string ''n'' times.

<!--T:125-->
Usage:
</translate>

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

<translate>
<!--T:128-->
Parameters:
</translate>

; <code>source</code>
: <translate><!--T:129--> The string to repeat</translate>
; <code>count</code>
: <translate><!--T:130--> The number of repetitions.</translate>

<translate>
<!--T:131-->
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||
<!-- Categories below this line; interwikis at Wikidata -->
[[Category:Modules]]
}}</includeonly><noinclude>
[[Category:Module documentation pages{{#translation:}}]]
</noinclude>
| #default=
  {{#invoke:Template translation|renderTranslatedTemplate|template=Module:String/doc|noshift=1|uselang={{int:lang}}}}
}}