查看“Module:String/doc”的源代码

这个模块提供了基本的[[:Category:字符串算法|字符串操作]]函数。

此处提供的大多数函数都可以使用命名参数、未命名参数或混合参数调用。 如果使用命名参数，Mediawiki将自动从参数中删除任何前导或尾随空格。取决于预期用途，保留或删除此类空白各有优劣的。

== 全局参数 ==
; <code>ignore_errors</code>
: 如果设置为“true”或“1”，则任何错误条件都将导致返回空字符串而不是错误消息。
; <code>error_category</code>
: 如果发生错误，则指定要包含在错误消息中的分类的名称。默认分类为{{clc|字符串模块报告的错误}}。
; <code>no_category</code>
: 如果设置为“true”或 1，则在生成错误时不会添加任何类别。
此模块的单元测试可在[[Module:String/testcases]]进行。

== len ==

此函数返回目标字符串的长度。

用法：

: <code><nowiki>{{#invoke:</nowiki>String|len|''target_string''}}</code>

或

: <code><nowiki>{{#invoke:</nowiki>String|len|s= ''target_string'' }}</code>

参数：

; s
: 目标字符串

示例：

* <code><nowiki>{{#invoke:String|len| abcdefghi }}</nowiki></code> → {{#invoke:String|len| abcdefghi }}
* <code><nowiki>{{#invoke:String|len|s= abcdefghi }}</nowiki></code> → {{#invoke:String|len|s= abcdefghi }}

== sub ==

: 此函数返回指定索引处目标字符串的子字符串。

用法：

: <code><nowiki>{{#invoke:</nowiki>String|sub|''target_string''|''start_index''|''end_index''}}</code>

或

: <code><nowiki>{{#invoke:</nowiki>String|sub|s= ''target_string'' |i= ''start_index'' |j= ''end_index'' }}</code>

参数：

; s
: 返回此字符串的子集
; i
: 要返回的子字符串的第一个索引，默认为1。
; j
: 要返回的字符串的最后一个索引，默认为最后一个字符。

字符串的第一个字符的索引为1。如果i或j是负值，则将其解析为通过从字符串末尾计数来选择字符。因此，值-1与选择字符串的最后一个字符相同。

如果请求的索引超出给定字符串的范围，则会报告错误。

示例：

* <code><nowiki>"{{#invoke:String|sub| abcdefghi }}"</nowiki></code> → "{{#invoke:String|sub| abcdefghi }}"
* <code><nowiki>"{{#invoke:String|sub|s= abcdefghi }}"</nowiki></code> → "{{#invoke:String|sub|s= abcdefghi }}"
* <code><nowiki>"{{#invoke:String|sub| abcdefghi | 3 }}"</nowiki></code> → "{{#invoke:String|sub| abcdefghi | 3 }}"
* <code><nowiki>"{{#invoke:String|sub|s= abcdefghi |i= 3 }}"</nowiki></code> → "{{#invoke:String|sub|s= abcdefghi |i= 3 }}"
* <code><nowiki>"{{#invoke:String|sub| abcdefghi | 3 | 4 }}"</nowiki></code> → "{{#invoke:String|sub| abcdefghi | 3 | 4 }}"
* <code><nowiki>"{{#invoke:String|sub|s= abcdefghi |i= 3 |j= 4 }}"</nowiki></code> → "{{#invoke:String|sub|s= abcdefghi |i= 3 |j= 4 }}"

== sublength ==

此函数实现了{{tl|Str sub old}}的功能，保留仅为维持旧的模板。

用法：

: <code><nowiki>{{#invoke:</nowiki>String|sublength|s= -{}-''目标字符串'' |i= ''开始索引'' |len= ''长度'' }}</code>

参数：

; s
: 字符串
; i
: 返回的子串的开始索引。第一个个字符的索引为0。
; len
: 返回的字符串的长度，默认为最后一个字符。

示例：

* <code><nowiki>{{#invoke:String|sublength|s= abcdefghi }}</nowiki></code> → {{#invoke:String|sublength|s= abcdefghi }}
* <code><nowiki>{{#invoke:String|sublength|s= abcdefghi |i= 3 }}</nowiki></code> → {{#invoke:String|sublength|s= abcdefghi |i= 3 }}
* <code><nowiki>{{#invoke:String|sublength|s= abcdefghi |i= 3 |len= 4 }}</nowiki></code> → {{#invoke:String|sublength|s= abcdefghi |i= 3 |len= 4 }}

== match ==

此函数从源字符串返回一个匹配指定模式的子字符串。

用法：

: <code><nowiki>{{#invoke:</nowiki>String-{}-|match|''源字符串''|''模式字符串''|''开始索引''|''匹配数量''|''纯标记''|''无匹配输出''}}</code>

或者

: <code><nowiki>{{#invoke:</nowiki>String|-{}-match|s= ''源字符串'' |pattern= ''模式字符串'' |start= ''开始索引''|match= ''匹配数量''|plain= ''纯标记'' |nomatch= ''无匹配输出'' }}</code>

参数：

; s
: 在这个字符串内搜索
; pattern
: 需要在字符串内搜索的模式或者字符串
; start
: 源字符串内的索引，从此索引开始搜索。字符串的第一个字符的索引为1。默认为1。
; match
: 在一些情况下，可能需要在单个字符串中进行多次匹配。此参数指定了返回哪一个匹配，其中第一个匹配就是match=1。如果指定了负数，那么返回的匹配从最后一个匹配开始数的。因此match=-1表达返回最后一个匹配。默认为1。
; plain
: pattern是否应该理解为纯字符串，而非正则表达式。默认为false。
; nomatch
: 如果没有找到匹配，返回nomatch的值，而不是一个错误。

如果match_number或start_index超出了查询的字符串的范围，此函数会产生错误。如果没有找到匹配，也会产生错误。

如果添加了参数ignore_errors=true，那么错误会被禁止，失败时返回的是一个空字符串。

匹配是Lua的一种正则表达式，更多信息可以参考：

* [[mw:Special:MyLanguage/Extension:Scribunto/Lua_reference_manual#Patterns|Scribunto patterns]]
* [[mw:Special:MyLanguage/Extension:Scribunto/Lua_reference_manual#Ustring_patterns|Scribunto Unicode string patterns]]

示例：
* <code><nowiki>{{#invoke:String|match| abc123def456 |%d+}}</nowiki></code> → {{#invoke:String|match| abc123def456 |%d+}}
* <code><nowiki>{{#invoke:String|match|s= abc123def456 |pattern= %d+ }}</nowiki></code> → {{#invoke:String|match|s= abc123def456 |pattern= %d+ }}
* <code><nowiki>{{#invoke:String|match| abc123def456 |%d+|6}}</nowiki></code> → {{#invoke:String|match| abc123def456 |%d+|6}}
* <code><nowiki>{{#invoke:String|match|s= abc123def456 |pattern= %d+ |start= 6 }}</nowiki></code> → {{#invoke:String|match|s= abc123def456 |pattern= %d+ |start= 6 }}
* <code><nowiki>{{#invoke:String|match|s= abc123def456 |pattern= %d+ |start= 6 |match= 2 }}</nowiki></code> → {{#invoke:String|match|s= abc123def456 |pattern= %d+ |start= 6 |match= 2 }}
* <code><nowiki>{{#invoke:String|match|s= abc123%d+ |pattern= %d+ }}</nowiki></code> → {{#invoke:String|match|s= abc123%d+ |pattern= %d+ }}
* <code><nowiki>{{#invoke:String|match|s= abc123%d+ |pattern= %d+ |plain= true }}</nowiki></code> → {{#invoke:String|match|s= abc123%d+ |pattern= %d+ |plain= true }}
* <code><nowiki>{{#invoke:String|match|s= abc |pattern= %d }}</nowiki></code> → {{#invoke:String|match|s= abc |pattern= %d |no_category=true}}
* <code><nowiki>{{#invoke:String|match|s= abc |pattern= %d |nomatch= No numeric characters in string }}</nowiki></code> → {{#invoke:String|match|s= abc |pattern= %d |nomatch= No numeric characters in string }}
* <code><nowiki>{{#invoke:String|match|s= abc |pattern= %d |ignore_errors= true }}</nowiki></code> → {{#invoke:String|match|s= abc |pattern= %d |ignore_errors= true }}
* <code><nowiki>{{#invoke:String|match|s= 0012001200 |pattern= 0*(%d*) }}</nowiki></code> → {{#invoke:String|match|s= 0012001200 |pattern= 0*(%d*) }}

== pos ==

返回在目标字符串中的位置pos处的单个字符。

用法：

: <code><nowiki>{{#invoke:</nowiki>String|pos|-{}-''目标字符串''|''索引值''}}</code>

或

: <code><nowiki>{{#invoke:</nowiki>String|pos|-{}-target= ''目标字符串'' |pos= ''索引值'' }}</code>

参数：

; 目标
: 在此字符串内搜索
; pos
: 需要返回的字符所在的索引。

第一个字符的索引值为1。

如果为负值，则此函数会从字符串的最后面开始倒数。也就是说，pos=-1相当于返回最后一个字符。

如果此值为0，或者超出了字符串的长度，则会返回错误。

示例：

* <code><nowiki>{{#invoke:String|pos| abcdefghi | 4 }}</nowiki></code> → {{#invoke:String|pos| abcdefghi | 4 }}
* <code><nowiki>{{#invoke:String|pos|target= abcdefghi |pos= 4 }}</nowiki></code> → {{#invoke:String|pos|target= abcdefghi |pos= 4 }}

== str_find ==

此函数与{{tl|str_find}}的行为重复，包含了其所有的技巧，仅为支持存在的模板，但是对于新的代码和模板''不推荐''使用。新的代码建议直接使用find函数。

返回源字符串中匹配目的的第一个索引。索引是从1开始数的，如果源字符串中找不到目标字符串，则返回-1。

注意：如果目标字符串是空白或者缺失，则函数返回值为1，这可能不是预期的行为，必须要单独考虑。

用法：

: <code><nowiki>{{#invoke:</nowiki>String|str_find|-{}-''源字符串''|''目标字符串''}}</code>

或

: <code><nowiki>{{#invoke:</nowiki>String|str_find|source= ''源字符串'' |target= ''目标字符串'' }}</code>

参数：

; source
: 在此字符串内搜索
; target
: 在源内搜索的字符串

示例：
* <code><nowiki>{{#invoke:String|str_find| abc123def }}</nowiki></code> → {{#invoke:String|str_find| abc123def }}
* <code><nowiki>{{#invoke:String|str_find|source= abc123def }}</nowiki></code> → {{#invoke:String|str_find|source= abc123def }}
* <code><nowiki>{{#invoke:String|str_find| abc123def |123}}</nowiki></code> → {{#invoke:String|str_find| abc123def |123}}
* <code><nowiki>{{#invoke:String|str_find|source= abc123def |target= 123 }}</nowiki></code> → {{#invoke:String|str_find|source= abc123def |target= 123 }}
* <code><nowiki>{{#invoke:String|str_find| abc123def |not}}</nowiki></code> → {{#invoke:String|str_find| abc123def |not}}

== find ==

此函数在一个字符串内搜索另一个字符串。

用法：

: <code><nowiki>{{#invoke:</nowiki>String|find-{}-|''源字符串''|''目标字符串''|''开始索引''|''纯标记''}}</code>

或

: <code><nowiki>{{#invoke:</nowiki>String|find|-{}-source= ''源字符串'' |target= ''目标字符串'' |start= ''开始索引'' |plain= ''纯标记'' }}</code>

参数：

; source
: 在此字符串内搜索
; target
: 在源字符串内搜索的字符串
; start
: 在源字符串的此位置索引版主开始搜索。默认为1
; plain
: 布尔值标记，表示目的应该被理解为纯文本，而不是[[mw:Special:MyLanguage/Extension:Scribunto/Lua reference manual#Ustring patterns|Scribunto ustring模式]]，默认为true

此函数返回了在索引&gt;"start"，其中"source"中可以持续到"target"。索引是从1开始数的。如果没有找到目标字符串，函数返回0。如果索引或者目的缺失或者是空的，此函数也会返回0。

此函数应该可以安全地操作UTF-8字符串。

示例：
* <code><nowiki>{{#invoke:String|find|abc123def|12}}</nowiki></code> → {{#invoke:String|find|abc123def|12}}
* <code><nowiki>{{#invoke:String|find|source=abc123def|target=12}}</nowiki></code> → {{#invoke:String|find|source=abc123def|target=12}}
* <code><nowiki>{{#invoke:String|find|source=abc123def|target=pqr}}</nowiki></code> → {{#invoke:String|find|source=abc123def|target=pqr}}
* <code><nowiki>{{#invoke:String|find| abc123def |123}}</nowiki></code> → {{#invoke:String|find| abc123def |123}}
* <code><nowiki>{{#invoke:String|find|source= abc123def |target= 123 }}</nowiki></code> → {{#invoke:String|find|source= abc123def |target= 123 }}
* <code><nowiki>{{#invoke:String|find|source=abc123def|target=%d |start=3 |plain=false }}</nowiki></code> → {{#invoke:String|find|source=abc123def|target=%d |start=3 |plain=false }}

与未命名的参数使用时，两端的空格会被保留且被计入：
* <code><nowiki>{{#invoke:String|find|  abc123def |c|false}}</nowiki></code> → {{#invoke:String|find|  abc123def |c|false}}
* <code><nowiki>{{#invoke:String|find|source=  abc123def |target=c|plain=false}}</nowiki></code> → {{#invoke:String|find|source=  abc123def |target=c|plain=false}}
* <code><nowiki>{{#invoke:string|find|abc 123 def|%s|plain=false}}</nowiki></code> → {{#invoke:string|find|abc 123 def|%s|plain=false}}

检测字符串是否存在：
* <code>{{pf|ifexpr|<nowiki>{{#invoke:string|find|haystack|needle}}</nowiki>|Found needle|Didn't find needle}}</code> → {{#ifexpr:{{#invoke:string|find|haystack|needle}}|Found needle|Didn't find needle}}

{{anchor|replace}}
== replace（gsub） ==

此函数在一个字符串内替换到目的字符串或者模式。此函数是通过调用<code>mw.ustring.gsub</code>实现的。

用法：

: <code><nowiki>{{#invoke:</nowiki>String|replace|''源字符串''|''模式字符串''|''替换字符串''|''替换次数''|''纯标记''}}</code>

或

: <code><nowiki>{{#invoke:</nowiki>String|replace|source= ''源字符串'' |pattern= ''模式字符串'' |replace= ''替换字符串'' |count= ''替换次数'' |plain= ''纯标记'' }}</code>

参数：

; source
: 在此字符串内搜索
; pattern
: 在源内查找此字符串或者模式
; replace
: 使用此字符串替换
; count
: 需要替换的次数，默认为all
; plain
: 布尔值标记，表示目的应该被理解为纯文本，而不是[[mw:Special:MyLanguage/Extension:Scribunto/Lua reference manual#Ustring patterns|Scribunto ustring模式]]，默认为true

示例：

* <code><nowiki>"{{#invoke:String|replace| abc123def456 |123|XYZ}}"</nowiki></code> → "{{#invoke:String|replace| abc123def456 |123|XYZ}}"
* <code><nowiki>"{{#invoke:String|replace|source= abc123def456 |pattern= 123 |replace= XYZ }}"</nowiki></code> → "{{#invoke:String|replace|source= abc123def456 |pattern= 123 |replace= XYZ }}"
* <code><nowiki>"{{#invoke:String|replace| abc123def456 |%d+|XYZ|1|false}}"</nowiki></code> → "{{#invoke:String|replace| abc123def456 |%d+|XYZ|1|false}}"
* <code><nowiki>"{{#invoke:String|replace|source= abc123def456 |pattern= %d+ |replace= XYZ |count=1 |plain= false }}"</nowiki></code> → "{{#invoke:String|replace|source= abc123def456 |pattern= %d+ |replace= XYZ |count=1 |plain= false }}"
* <code><nowiki>"{{#invoke:String|replace|source= abc123def456 |pattern= %d+ |replace= XYZ |plain= false }}"</nowiki></code> → "{{#invoke:String|replace|source= abc123def456 |pattern= %d+ |replace= XYZ |plain= false }}"
* <code><nowiki>{{#invoke:String|replace|source= 0012001200 |pattern= ^0* |plain= false }}</nowiki></code> → {{#invoke:String|replace|source= 0012001200 |pattern= ^0* |plain= false }}

== rep ==

将一个字符串重复''n''次，其本质为<code>string.rep</code>。

用法：

: <code><nowiki>{{#invoke:</nowiki>String|rep|''源''|''次数''}}</code>

参数：

; 源
: 需要重复的字符串
; 次数
: 重复的次数

示例：

* <code><nowiki>"{{#invoke:String|rep|hello|3}}"</nowiki></code> → "{{#invoke:String|rep|hello|3}}"
* <code><nowiki>"{{#invoke:String|rep| hello | 3 }}"</nowiki></code> → "{{#invoke:String|rep| hello | 3 }}"
<!--

以下函数暂时还不存在，故移除有关的文档：
== escapePattern ==

在[[:mw:Special:MyLanguage/LUAREF#Patterns|模式]]中，将''类字符'''替换为''字面字符''。例如，在模式中，字符<code>.</code>会捕获任何字符，escapePattern会将其转换为<code>%.</code>，这样就捕获了字面字符“.”。

用法：
* <code><nowiki>{{#invoke:String|escapePattern|</nowiki>''模式字符串''<nowiki>}}</nowiki></code>

参数：

; 模式字符串
: 需要转义的模式字符串

示例：

* <code><nowiki>"{{#invoke:String|escapePattern|A.D.}}"</nowiki></code> → "{{#invoke:String|escapePattern|A.D.}}"
* <code><nowiki>"{{#invoke:String|escapePattern|10%}}"</nowiki></code> → "{{#invoke:String|escapePattern|10%}}"

== count == 
返回指定的模式的次数。返回不会将匹配交连。

用法：
: <code><nowiki>{{#invoke:</nowiki>String|count|''源字符串''|''匹配字符串''|''纯标记''}}</code>

或

: <code><nowiki>{{#invoke:</nowiki>String|count|source= ''源字符串'' |pattern= ''匹配字符串''|plain= ''纯标记'' }}</code>
参数：
; source_string
: 在此字符串内数出现次数
; pattern
: 在源内需要数的字符串或者模式
; plain
: 布尔值标记，表示目的应该被理解为纯文本，而不是[[mw:Special:MyLanguage/Extension:Scribunto/Lua reference manual#Ustring patterns|Scribunto ustring模式]]，默认为true

示例：
* 数“a”：<code><nowiki>"{{#invoke:String|count|aabbcc|a}}"</nowiki></code> → "{{#invoke:String|count|aabbcc|a}}"
* 数“aba”出现的次数：<code><nowiki>"{{#invoke:String|count|ababababab|aba}}"</nowiki></code> → "{{#invoke:String|count|ababababab|aba}}"
* 数a或c出现的次数：<code><nowiki>"{{#invoke:String|count|aabbcc|[ac]|plain=false}}"</nowiki></code> → "{{#invoke:String|count|aabbcc|[ac]|plain=false}}"
* 数非a出现的次数：<code><nowiki>"{{#invoke:String|count|aaabaaac|[^a]|plain=false}}"</nowiki></code> → "{{#invoke:String|count|aaabaaac|[^a]|plain=false}}"
* 数开头的a出现的次数：<code><nowiki>"{{#invoke:String|count|aaabaaac|^a|plain=false}}"</nowiki></code> → "{{#invoke:String|count|aaabaaac|^a|plain=false}}"

== join ==
将传入的所有字符串连成一个字符串，第一个字符串表示分隔符

用法：
: <code><nowiki>{{#invoke:</nowiki>String|join|''分隔符''|''字符串1''|''字符串2''|...}}</code>
参数：
; 分隔符
: 被连接在一起的各个字符串之间的字符串
: 注意对此参数，开头和结尾的空格不会被移除。
; 字符串1/字符串2/...
: 需要连接进来的字符串
示例：
* <code><nowiki>"{{#invoke:String|join|x|foo|bar|baz}}"</nowiki></code> → "{{#invoke:String|join|x|foo|bar|baz}}"
* <code><nowiki>"{{#invoke:String|join||a|b|c|d|e|f|g}}"</nowiki></code> → "{{#invoke:String|join||a|b|c|d|e|f|g}}"
* <code><nowiki>"{{#invoke:String|join|,|a|b|c|d|e|f|g}}"</nowiki></code> → "{{#invoke:String|join|,|a|b|c|d|e|f|g}}"
* <code><nowiki>"{{#invoke:String|join|, |a|b|c|d|e|f|g}}"</nowiki></code> → "{{#invoke:String|join|, |a|b|c|d|e|f|g}}"
* <code><nowiki>"{{#invoke:String|join| &ndash; |a|b|c|d|e|f|g}}"</nowiki></code> → "{{#invoke:String|join| &ndash; |a|b|c|d|e|f|g}}"
前面的这个例子使用了html实体&amp;ndash;，但是unicode字符也是有用的。

== endswith ==
{{for|startswith函数|Module:String2#startswith}}
用法：
: <code><nowiki>{{#invoke:</nowiki>String|endswith|''源字符串''|''搜索字符串''}}</code>

或

: <code><nowiki>{{#invoke:</nowiki>String|endswith|source= ''源字符串'' |pattern= ''搜索字符串''}}</code>
如果源字符串是以指定的搜索字符串结尾的，返回yes。使用命名参数会移除掉空格。''搜索字符串''不是个Lua模式，而是按照字面解释的。

* <code><nowiki>"{{#invoke:String|endswith|xxxyyy|y}}"</nowiki></code> → "{{#invoke:String|endswith|xxxyyy|y}}"
* <code><nowiki>"{{#invoke:String|endswith|xxxyyy|z}}"</nowiki></code> → "{{#invoke:String|endswith|xxxyyy|z}}"
-->
<includeonly>
<!-- 本行下加入模板的分類，跨維基連結加入Wikidata（參見[[Wikipedia:维基数据]]） -->
[[Category:Lua元模块}]]
[[Category:添加追踪分类的模块]]</includeonly>