模組:String/doc
此頁面為 Module:String 的說明文件
 | 此模組文件被引用於約2,430,000個頁面。 為了避免造成大規模的影響，所有對此模組文件的編輯應先於沙盒或測試樣例上測試。 測試後無誤的版本可以一次性地加入此模組文件中，但是修改前請務必於討論頁發起討論。 模板引用數量會自動更新。 |
這個模組提供了基本的字串操作函數。
此處提供的大多數函數都可以使用命名參數、未命名參數或混合參數調用。 如果使用命名參數，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的一種正則表達式，更多資訊可以參考：
範例：
{{#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 "