模組:String/doc

這個模塊提供了基本的字符串操作函數。

此處提供的大多數函數都可以使用命名參數、未命名參數或混合參數調用。 如果使用命名參數，Mediawiki將自動從參數中刪除任何前導或尾隨空格。取決於預期用途，保留或刪除此類空白各有優劣的。

全局參數

ignore_errors

如果設置為「true」或「1」，則任何錯誤條件都將導致返回空字符串而不是錯誤消息。

error_category

如果發生錯誤，則指定要包含在錯誤消息中的分類的名稱。默認分類為Category:字符串模塊報告的錯誤（19）。

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的一種正則表達式，更多信息可以參考：

• Scribunto patterns
• Scribunto Unicode string patterns

示例：

• {{#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 "