模块:String/doc

本页使用了标题或全文手工转换，现处于中国大陆简体模式
求闻百科，共笔求闻

这个模块提供了基本的字符串操作函数。

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

全局参数

ignore_errors
如果设置为“true”或“1”，则任何错误条件都将导致返回空字符串而不是错误消息。
error_category
如果发生错误，则指定要包含在错误消息中的分类的名称。默认分类为Category:字符串模块报告的错误（228）。
no_category
如果设置为“true”或 1，则在生成错误时不会添加任何类别。

此模块的单元测试可在Module:String/testcases进行。

len

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

用法：

{{#invoke:String|len|target_string}}

或

{{#invoke:String|len|s= target_string }}

参数：

s
目标字符串

示例：

  • {{#invoke:String|len| abcdefghi }} → 11
  • {{#invoke:String|len|s= abcdefghi }} → 9

sub

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

用法：

{{#invoke:String|sub|target_string|start_index|end_index}}

或

{{#invoke:String|sub|s= target_string |i= start_index |j= end_index }}

参数：

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

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

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

示例：

  • "{{#invoke:String|sub| abcdefghi }}" → " abcdefghi "
  • "{{#invoke:String|sub|s= abcdefghi }}" → "abcdefghi"
  • "{{#invoke:String|sub| abcdefghi | 3 }}" → "bcdefghi "
  • "{{#invoke:String|sub|s= abcdefghi |i= 3 }}" → "cdefghi"
  • "{{#invoke:String|sub| abcdefghi | 3 | 4 }}" → "bc"
  • "{{#invoke:String|sub|s= abcdefghi |i= 3 |j= 4 }}" → "cd"

sublength

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

用法：

{{#invoke:String|sublength|s= 目标字符串 |i= 开始索引 |len= 长度 }}

参数：

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

示例：

  • {{#invoke:String|sublength|s= abcdefghi }} → abcdefghi
  • {{#invoke:String|sublength|s= abcdefghi |i= 3 }} → defghi
  • {{#invoke:String|sublength|s= abcdefghi |i= 3 |len= 4 }} → defg

match

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

用法：

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

或者

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

参数：

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

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

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

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

示例：

  • {{#invoke:String|match| abc123def456 |%d+}} → 123
  • {{#invoke:String|match|s= abc123def456 |pattern= %d+ }} → 123
  • {{#invoke:String|match| abc123def456 |%d+|6}} → 23
  • {{#invoke:String|match|s= abc123def456 |pattern= %d+ |start= 6 }} → 3
  • {{#invoke:String|match|s= abc123def456 |pattern= %d+ |start= 6 |match= 2 }} → 456
  • {{#invoke:String|match|s= abc123%d+ |pattern= %d+ }} → 123
  • {{#invoke:String|match|s= abc123%d+ |pattern= %d+ |plain= true }} → %d+
  • {{#invoke:String|match|s= abc |pattern= %d }} → 字符串模块出错：找不到匹配
  • {{#invoke:String|match|s= abc |pattern= %d |nomatch= No numeric characters in string }} → No numeric characters in string
  • {{#invoke:String|match|s= abc |pattern= %d |ignore_errors= true }} →
  • {{#invoke:String|match|s= 0012001200 |pattern= 0*(%d*) }} → 12001200

pos

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

用法：

{{#invoke:String|pos|目标字符串|索引值}}

或

{{#invoke:String|pos|target= 目标字符串 |pos= 索引值 }}

参数：

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

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

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

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

示例：

  • {{#invoke:String|pos| abcdefghi | 4 }} → c
  • {{#invoke:String|pos|target= abcdefghi |pos= 4 }} → d

str_find

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

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

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

用法：

{{#invoke:String|str_find|源字符串|目标字符串}}

或

{{#invoke:String|str_find|source= 源字符串 |target= 目标字符串 }}

参数：

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

示例：

  • {{#invoke:String|str_find| abc123def }} → 1
  • {{#invoke:String|str_find|source= abc123def }} → 1
  • {{#invoke:String|str_find| abc123def |123}} → 5
  • {{#invoke:String|str_find|source= abc123def |target= 123 }} → 4
  • {{#invoke:String|str_find| abc123def |not}} → -1

find

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

用法：

{{#invoke:String|find|源字符串|目标字符串|开始索引|纯标记}}

或

{{#invoke:String|find|source= 源字符串 |target= 目标字符串 |start= 开始索引 |plain= 纯标记 }}

参数：

source
在此字符串内搜索
target
在源字符串内搜索的字符串
start
在源字符串的此位置索引版主开始搜索。默认为1
plain
布尔值标记，表示目的应该被理解为纯文本，而不是Scribunto ustring模式，默认为true

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

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

示例：

  • {{#invoke:String|find|abc123def|12}} → 4
  • {{#invoke:String|find|source=abc123def|target=12}} → 4
  • {{#invoke:String|find|source=abc123def|target=pqr}} → 0
  • {{#invoke:String|find| abc123def |123}} → 5
  • {{#invoke:String|find|source= abc123def |target= 123 }} → 4
  • {{#invoke:String|find|source=abc123def|target=%d |start=3 |plain=false }} → 4

与未命名的参数使用时，两端的空格会被保留且被计入：

  • {{#invoke:String|find| abc123def |c|false}} → 5
  • {{#invoke:String|find|source= abc123def |target=c|plain=false}} → 3
  • {{#invoke:string|find|abc 123 def|%s|plain=false}} → 4

检测字符串是否存在：

  • {{#ifexpr:{{#invoke:string|find|haystack|needle}}|Found needle|Didn't find needle}} → Didn't find needle

replace（gsub）

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

用法：

{{#invoke:String|replace|源字符串|模式字符串|替换字符串|替换次数|纯标记}}

或

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

参数：

source
在此字符串内搜索
pattern
在源内查找此字符串或者模式
replace
使用此字符串替换
count
需要替换的次数，默认为all
plain
布尔值标记，表示目的应该被理解为纯文本，而不是Scribunto ustring模式，默认为true

示例：

  • "{{#invoke:String|replace| abc123def456 |123|XYZ}}" → " abcXYZdef456 "
  • "{{#invoke:String|replace|source= abc123def456 |pattern= 123 |replace= XYZ }}" → "abcXYZdef456"
  • "{{#invoke:String|replace| abc123def456 |%d+|XYZ|1|false}}" → " abcXYZdef456 "
  • "{{#invoke:String|replace|source= abc123def456 |pattern= %d+ |replace= XYZ |count=1 |plain= false }}" → "abcXYZdef456"
  • "{{#invoke:String|replace|source= abc123def456 |pattern= %d+ |replace= XYZ |plain= false }}" → "abcXYZdefXYZ"
  • {{#invoke:String|replace|source= 0012001200 |pattern= ^0* |plain= false }} → 12001200

rep

将一个字符串重复n次，其本质为string.rep。

用法：

{{#invoke:String|rep|源|次数}}

参数：

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

示例：

  • "{{#invoke:String|rep|hello|3}}" → "hellohellohello"
  • "{{#invoke:String|rep| hello | 3 }}" → " hello hello hello "

escapePattern

在模式中，将类字符'替换为字面字符。例如，在模式中，字符.会捕获任何字符，escapePattern会将其转换为%.，这样就捕获了字面字符“.”。

用法：

  • {{#invoke:String|escapePattern|模式字符串}}

参数：

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

示例：

  • "{{#invoke:String|escapePattern|A.D.}}" → "脚本错误：函数“escapePattern”不存在。"
  • "{{#invoke:String|escapePattern|10%}}" → "脚本错误：函数“escapePattern”不存在。"

count

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

用法：

{{#invoke:String|count|源字符串|匹配字符串|纯标记}}

或

{{#invoke:String|count|source= 源字符串 |pattern= 匹配字符串|plain= 纯标记 }}

参数：

source_string
在此字符串内数出现次数
pattern
在源内需要数的字符串或者模式
plain
布尔值标记，表示目的应该被理解为纯文本，而不是Scribunto ustring模式，默认为true

示例：

  • 数“a”："{{#invoke:String|count|aabbcc|a}}" → "脚本错误：函数“count”不存在。"
  • 数“aba”出现的次数："{{#invoke:String|count|ababababab|aba}}" → "脚本错误：函数“count”不存在。"
  • 数a或c出现的次数："{{#invoke:String|count|aabbcc|[ac]|plain=false}}" → "脚本错误：函数“count”不存在。"
  • 数非a出现的次数："{{#invoke:String|count|aaabaaac|[^a]|plain=false}}" → "脚本错误：函数“count”不存在。"
  • 数开头的a出现的次数："{{#invoke:String|count|aaabaaac|^a|plain=false}}" → "脚本错误：函数“count”不存在。"

join

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

用法：

{{#invoke:String|join|分隔符|字符串1|字符串2|...}}

参数：

分隔符
被连接在一起的各个字符串之间的字符串
注意对此参数，开头和结尾的空格不会被移除。
字符串1/字符串2/...
需要连接进来的字符串

示例：

  • "{{#invoke:String|join|x|foo|bar|baz}}" → "fooxbarxbaz"
  • "{{#invoke:String|join||a|b|c|d|e|f|g}}" → "abcdefg"
  • "{{#invoke:String|join|,|a|b|c|d|e|f|g}}" → "a,b,c,d,e,f,g"
  • "{{#invoke:String|join|, |a|b|c|d|e|f|g}}" → "a, b, c, d, e, f, g"
  • "{{#invoke:String|join| – |a|b|c|d|e|f|g}}" → "a – b – c – d – e – f – g"

前面的这个例子使用了html实体–，但是unicode字符也是有用的。

endswith

  关于startswith函数，请见“Module:String2 § startswith”。

用法：

{{#invoke:String|endswith|源字符串|搜索字符串}}

或

{{#invoke:String|endswith|source= 源字符串 |pattern= 搜索字符串}}

如果源字符串是以指定的搜索字符串结尾的，返回yes。使用命名参数会移除掉空格。搜索字符串不是个Lua模式，而是按照字面解释的。

  • "{{#invoke:String|endswith|xxxyyy|y}}" → "脚本错误：函数“endswith”不存在。"
  • "{{#invoke:String|endswith|xxxyyy|z}}" → "脚本错误：函数“endswith”不存在。"
字符串处理模板
切短
根据数量处理
模板链接：{{str mid}} 按位置及长度选取子串。
模板链接：{{trunc}} 切短到规定的字数。
模板链接：{{str left}} 切短或重复填充到规定的字数。
模板链接：{{str crop}} 从末尾切短特定数量的字符。
模板链接：{{chop head and tail}} To crop a specified number of characters off the beginning and end.
模板链接：{{str right}} 返回从左向右移除若干个字符后的字符串
模板链接：{{str rightc}} 返回从后向前指定数量的字符串，如果字符串为空则返回一个参数
模板链接：{{str rightmost}} To trim down to the last specified number of characters.
模板链接：{{str sub old}} To trim down to a specified number, starting at a given number from the left.
模板链接：{{str sub new}} Select a substr based on starting and ending index.
模板链接：{{str index}} 返回字符串的第×个字符
根据条件处理
模板链接：{{trim}} 移除首尾空格。
模板链接：{{str letter/trim}} To trim down to the beginning letters.
模板链接：{{str number/trim}} To trim down to the beginning numbers.
模板链接：{{trim brackets}} To trim any leading or trailing square brackets.
模板链接：{{trim quotes}} To trim leading or trailing matches quotes.
模板链接：{{String split}} 从长字符串中抽取短字符串。
模板链接：{{first word}} 切短至首个空格前。
模板链接：{{remove first word}} 移除首个空格前的内容。
模板链接：{{last word}} 切短至最后一个空格前。
模板链接：{{remove last word}} 移除最后一个空格前的内容。
专用于Wiki语法
模板链接：{{除链}} 去除Wiki链接的括号（Wiki代码）。
模板链接：{{remove file prefix}} 从文件名中去除“File:”（或“Image:”）。
模板链接：{{PAGENAMEBASE}} 去除字符串末尾的括号文本（消歧义）。
模板链接：{{title disambig text}} 返回字符串末尾的括号文本（消歧义）。
模板链接：{{WikiProjectbasename}} Removes "WikiProject" from a pagename.
模板链接：{{remove unranked}} Removes the string "unranked_" from the left of a string (taxonomy).
模板链接：{{ship prefix}} Returns the length of a ship's name prefix, if listed (ship names).
模板链接：{{title year}} Returns the 4-digit year from a pagename, if any.
插入、替换、长度
模板链接：{{strloc insert}} Inserts a string at character location strloc, or appends if strloc<=0.
模板链接：{{loop}} 特定次数重复字符串。
模板链接：{{replace}} 在字符串中查找并全部替换某字符串后返回。
模板链接：{{str rep}} 在字符串中查找并替换首次出现的某字符串后返回。
模板链接：{{digits}} 移除字符串中不是数字（0～9）的字符。
模板链接：{{str len}} 返回字符串长度。
模板链接：{{str ≥ len}} 检查一个字符串和某一给定长度相比是“更长或等长”还是“更短”。
模板链接：{{str ≤ len}} 检查一个字符串和某一给定长度相比是“更短或等长”还是“更长”。
模板链接：{{str ≠ len}} 检查一个字符串和某一给定长度相比是“不等长”还是“等长”。
模板链接：{{str ≤ ≥ len}} 检查一个字符串和某一给定长度相比是“更短”、“等长”还是“更长”。
分析、技术
模板链接：{{str endswith}} 检查是否以给定的字符串结尾。
模板链接：{{str find}}
模板链接：{{strfind short}}		在一个字符串中搜寻并返回特定字符串的位置。
模板链接：{{str find0}} Zero-based substring search.
模板链接：{{str sub find}} 从指定的偏移量开始搜索一个子字符串。
模板链接：{{str letter}} 返回一个字符串开头的所有字符。
模板链接：{{str number}} 返回一个字符串开头的所有数字。
模板链接：{{str gtr str}} 判断两个字符串是否相等，然后根据返回相应的值。
模板链接：{{ASCII code}} 返回单个字符的ASCII码值
模板链接：{{a or an}} Takes a noun and produces the appropriate indefinite article, based on whether the first letter is a vowel.
   
Module:String
...Magic words About {{padleft:|}}.
...ParserFunctions About {{#titleparts:|}}, {{#expr:|}}, {{#ifeq:|}}, etc.


取自“https://www.qiuwenbaike.cn/index.php?title=Module:String/doc&oldid=5851478”