模組:String/doc
![本頁使用了標題或全文手工轉換](http://upload.wikimedia.org/wikipedia/commons/thumb/c/cd/Zh_conversion_icon_m.svg/35px-Zh_conversion_icon_m.svg.png)
此頁面為 Module:String 的說明文件
![]() | 此模組文件被引用於約2,410,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 "
|