モジュール:String/docのソースを表示

{{Documentation subpage}}
{{使用箇所の多いテンプレート|172,000以上}}
{{Module rating|p}}
文字列を扱ういくつかの関数を提供するモジュールです。[[UTF-8]]でエンコードされた文字列を取り扱えます。

このモジュールのユニットテストについては[[モジュール:String/testcases]]をご参照ください。

== 共通引数 ==
{| class="wikitable"
|+ 引数の一覧
! 引数 !! 内容 !! 既定値 !! 説明
|-
! ignore_errors
| エラー無視 || ''なし'' ||
; false, no, 0, ''空文字'' : エラーがあるときはそのままエラーを返す
; true、1など上記以外の文字列 : エラーがあってもエラーを返さず空文字を返す
|-
! error_category
| エラーカテゴリ || [[:Category:モジュールStringのエラー]] || エラーがあるときの[[:Category:追跡カテゴリ]]名を指定する
|-
! no_category
| カテゴリ付与 || ''なし'' ||
; false, no, 0, ''空文字'' : エラーがあるときにエラーカテゴリを付与する
; true、1など上記以外の文字列 : エラーがあってもエラーカテゴリを付与しない
|}

== 使い方 ==
=== len ===
文字列の長さを返します。
<syntaxhighlight lang="moin">
{{#invoke:String|len|文字列}}
</syntaxhighlight>
もしくは
<syntaxhighlight lang="moin">
{{#invoke:String|len|s=文字列}}
</syntaxhighlight>
{| class="wikitable"
|+ 引数の一覧
! 引数 !! 内容 !! 既定値 !! 説明
|-
! 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 ===
文字列から指定された部分の文字列を抜き出して返します。
<syntaxhighlight lang="moin">
{{#invoke:String|sub|文字列|開始位置|終了位置}}
</syntaxhighlight>
もしくは
<syntaxhighlight lang="moin">
{{#invoke:String|sub|s=文字列|i=開始位置|j=終了位置}}
</syntaxhighlight>
{| class="wikitable"
|+ 引数の一覧
! 引数 !! 内容 !! 既定値 !! 説明
|-
! s
| 文字列 || ''なし'' || 元の文字列
|-
! i
| 開始位置 || 1 || 抜き出す初めの文字の位置
|-
! j
| 終了位置 || -1 || 抜き出す最後の文字の位置
|}
開始位置・終了位置には負の数を指定することも可能です。その場合、文字列の後ろから数えます。例えば、「-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}}を実装しており、Str subのような古いテンプレートを維持するために残されています。文字列から指定された部分の文字列を抜き出して返します。

<syntaxhighlight lang="moin">
{{#invoke:String|sublength|s=文字列|i=開始位置|len=長さ}}
</syntaxhighlight>
{| class="wikitable"
|+ 引数の一覧
! 引数 !! 内容 !! 既定値 !! 説明
|-
! s
| 文字列 || ''なし'' || 元の文字列
|-
! i
| 開始位置 || 1 || 抜き出す初めの文字の位置。1文字目は"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 ===
パターンに一致する文字列を返します。
<syntaxhighlight lang="moin">
{{#invoke:String|match|文字列|パターン|検索開始位置|一致番号|プレーンフラグ|エラー出力}}
</syntaxhighlight>
もしくは
<syntaxhighlight lang="moin">
{{#invoke:String|match
|s=文字列
|pattern=パターン
|start=検索開始位置
|match=一致番号
|plain=プレーンフラグ
|nomatch=エラー出力
}}
</syntaxhighlight>
{| class="wikitable"
|+ 引数の一覧
! 引数 !! 内容 !! 既定値 !! 説明
|-
! s
| 文字列 || ''なし'' || 検索対象の文字列
|-
! pattern
| パターン || ''なし'' || 検索する文字列パターン
|-
! start
| 検索開始位置 || 1 || 検索を開始する文字の位置
|-
! match
| 一致番号 || 1 || 検索開始位置から何番目の一致箇所を返すか
|-
! plain
| プレーンフラグ || false ||
; false, no, 0, ''空文字'' : パターンを[[mw:Extension:Scribunto/Lua_reference_manual#Patterns|Luaパターン]]として解釈する
; true、1など上記以外の文字列 : パターンをプレーンテキストとして解釈する
|-
! nomatch
| エラー出力 || ''なし'' || 何もマッチしなかったときに返す文字列<br />何も指定しないとエラーを返す（既定）
|}
検索開始位置・一致番号には負の数を指定することも可能です。その場合、後ろから数えます。

パターンにキャプチャがある場合はそのキャプチャを返します。

matchかstart引数が範囲外の場合、エラーを返します。パターンが見つからなかった場合はnomatchを指定していなければエラーを返します。また、ignore_errors=trueを指定した場合、いずれのエラーも返さず、代わりに空の文字列を返します。

Luaパターンの詳細は[[mw:Extension:Scribunto/Lua_reference_manual#Patterns|Scribunto patterns]]と[[mw: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=1 }}
*<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 }}

=== pos ===
文字列の中から指定された位置にある文字を返します。
<syntaxhighlight lang="moin">
{{#invoke:String|pos|文字列|位置}}
</syntaxhighlight>
もしくは
<syntaxhighlight lang="moin">
{{#invoke:String|pos|target=文字列|pos=位置}}
</syntaxhighlight>
{| class="wikitable"
|+ 引数の一覧
! 引数 !! 内容 !! 既定値 !! 説明
|-
! target
| 文字列 || ''なし'' || 検索対象の文字列
|-
! pos
| 位置 || ''なし'' || 返す文字の位置
|}
位置には負の数を指定することも可能です。その場合、文字列の後ろから数えます。例えば、「-1」は文字列の最後の文字です。

posが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関数を使用してください。"source"の文字列の中から"target"のパターンを検索し、その位置を返します。パターンが見つからない場合は-1を返します。

なお、"target"の文字列が空白か指定されていない場合、1を返します。これは一般的とは言えない挙動であり、特別に扱う必要があります。

<syntaxhighlight lang="moin">
{{#invoke:String|str_find|文字列|パターン}}
</syntaxhighlight>
もしくは
<syntaxhighlight lang="moin">
{{#invoke:String|str_find|source=文字列|target=パターン}}
</syntaxhighlight>

例:
*<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 }}

=== find ===
文字列の中からパターンを検索しその位置を返します。
<syntaxhighlight lang="moin">
{{#invoke:String|find|文字列|パターン|検索開始位置|プレーンフラグ}}
</syntaxhighlight>
もしくは
<syntaxhighlight lang="moin">
{{#invoke:String|find
|source=文字列
|target=パターン
|start=検索開始位置
|plain=プレーンフラグ
}}
</syntaxhighlight>
{| class="wikitable"
|+ 引数の一覧
! 引数 !! 内容 !! 既定値 !! 説明
|-
! source
| 文字列 || ''なし'' || 検索対象の文字列
|-
! target
| パターン || ''なし'' || 検索する文字列パターン
|-
! start
| 検索開始位置 || 1 || 検索を開始する文字の位置
|-
! plain
| プレーンフラグ || true ||
; false, no, 0, ''空文字'' : パターンを[[mw:Extension:Scribunto/Lua_reference_manual#Patterns|Luaパターン]]として解釈する
; trueなど上記以外の文字列 : パターンをプレーンテキストとして解釈する
|}
最初の文字の位置は1としています。文字列・パターンが指定されていなかったり、もしくは文字列の中にパターンがなかった場合は、0を返します。この関数は[[UTF-8]]の文字列にも使えます。

例:
*<code><nowiki>{{#invoke:String|find| abc123def }}</nowiki></code> → {{#invoke:String|find| abc123def }}
*<code><nowiki>{{#invoke:String|find|source= abc123def }}</nowiki></code> → {{#invoke:String|find|source= abc123def }}
*<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| abc123def |%d|3|false}}</nowiki></code> → {{#invoke:String|find| abc123def |%d|3|false}}
*<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 }}

=== replace ===
パターンと一致する部分を別の文字列で置き換えます。
<syntaxhighlight lang="moin">
{{#invoke:String|replace|文字列|パターン|置換文字列|置換回数|プレーンフラグ}}
</syntaxhighlight>
もしくは
<syntaxhighlight lang="moin">
{{#invoke:String|replace
|source=文字列
|pattern=パターン
|replace=置換文字列
|count=置換回数
|plain=プレーンフラグ
}}
</syntaxhighlight>

{| class="wikitable"
|+ 引数の一覧
! 引数 !! 内容 !! 既定値 !! 説明
|-
! source
| 文字列 || ''なし'' || 対象の文字列
|-
! pattern
| パターン || ''なし'' || 置換される文字列パターン
|-
! replace
| 置換文字列 || ''なし'' || 置換する文字列<br />何も指定しないとパターンを削除する（既定）
|-
! count
| 置換回数 || ''なし'' || 置換する回数<br />何も指定しないと可能な箇所すべてを置換する（既定）
|-
! plain
| プレーンフラグ || true ||
; false, no, 0, ''空文字'' : パターンを[[mw:Extension:Scribunto/Lua_reference_manual#Patterns|Luaパターン]]として解釈する
; trueなど上記以外の文字列 : パターンをプレーンテキストとして解釈する
|}

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

=== rep ===
Luaのstring.repをテンプレートにも使えるようにするための関数であり、文字列を指定回数返します。
<syntaxhighlight lang="moin">
{{#invoke:String|rep|文字列|繰り返し回数}}
</syntaxhighlight>

{| class="wikitable"
|+ 引数の一覧
! 引数 !! 内容 !! 既定値 !! 説明
|-
! source
| 文字列 || ''なし'' || 対象の文字列
|-
! count
| 繰り返し回数 || ''なし'' || 対象の文字列を繰り返す回数
|}

例:
*<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 }}"

== 関連項目 ==
*[[モジュール:String2]] - ほかの文字列処理用関数
*[[モジュール:StringFunc]]
*[[モジュール:Str endswith]]
*{{仮リンク|モジュール:Ustring|en|Module:Ustring}}
*[[mw:Extension:Scribunto/Lua reference manual#Ustring library]] - 使用しているメタ関数
*[[mw:Extension:Scribunto/Lua_reference_manual#Patterns]] - Luaパターン
*[[mw:Extension:Scribunto/Lua_reference_manual#Ustring_patterns]] - UTF-8関連の正規表現

<includeonly>{{#ifeq:{{SUBPAGENAME}}|sandbox | |
[[Category:Luaメタモジュール]] 
[[Category:追跡カテゴリを追加するモジュール]]
}}</includeonly>