# 7.15.23. `string_slice`

バージョン 11.0.3 で追加.

## 7.15.23.1. 概要

`string_slice` は文字列の部分文字列を抽出します。引数によって部分文字列の抽出方法を使い分けることが出来ます。抽出方法は以下の2つがあります。

- 位置による抽出

- 正規表現による抽出

Groongaでは正規表現にRubyと同じ構文を使います。

この関数を有効にするには、以下のコマンドで `functions/string` プラグインを登録します:

    plugin_register functions/string

## 7.15.23.2. 構文

`string_slice` は2つから4つの引数を指定できます。抽出方法によって指定可能な引数が変わります。

### 7.15.23.2.1. 位置による抽出

    string_slice(target, nth[, options])
    string_slice(target, nth, length[, options])

`options` には以下のキーを指定します。すべてのキー・値のペアは省略可能です。:

    {
      "default_value": default_value
    }

### 7.15.23.2.2. 正規表現による抽出

    string_slice(target, regexp, nth[, options])
    string_slice(target, regexp, name[, options])

`options` には以下のキーを指定します。すべてのキー・値のペアは省略可能です。:

    {
      "default_value": default_value
    }

## 7.15.23.3. 使い方

使い方を示すために使うスキーマ定義とサンプルデータは以下の通りです。

サンプルスキーマ:

実行例:

    plugin_register functions/string
    # [[0, 1337566253.89858, 0.000355720520019531], true]
    table_create Memos TABLE_HASH_KEY ShortText
    # [[0, 1337566253.89858, 0.000355720520019531], true]

サンプルデータ:

実行例:

    load --table Memos
    [
    {"_key": "Groonga"}
    ]
    # [[0, 1337566253.89858, 0.000355720520019531], 1]

位置により抽出する場合の簡単な例です。

実行例:

    select Memos --output_columns '_key, string_slice(_key, 2, 3)'
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         1
    #       ],
    #       [
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "string_slice",
    #           null
    #         ]
    #       ],
    #       [
    #         "Groonga",
    #         "oon"
    #       ]
    #     ]
    #   ]
    # ]

正規表現により抽出する場合の簡単な例です。

以下の例では、捕獲式集合 `(式)` の番号を指定して抽出しています。

実行例:

    select Memos --output_columns '_key, string_slice(_key, "(Gro+)(.*)", 2)'
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         1
    #       ],
    #       [
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "string_slice",
    #           null
    #         ]
    #       ],
    #       [
    #         "Groonga",
    #         "nga"
    #       ]
    #     ]
    #   ]
    # ]

以下の例では、名前付き捕獲式集合 `(?<name>式)` の名前を指定して抽出しています。

実行例:

    select Memos --output_columns '_key, string_slice(_key, "(Gr)(?<Name1>o*)(?<Name2>.*)", "Name1")'
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         1
    #       ],
    #       [
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "string_slice",
    #           null
    #         ]
    #       ],
    #       [
    #         "Groonga",
    #         "oo"
    #       ]
    #     ]
    #   ]
    # ]

以下の例では、デフォルト値を指定しています。

実行例:

    select Memos --output_columns '_key, string_slice(_key, "mismatch", 2, { "default_value" : "default" })'
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         1
    #       ],
    #       [
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "string_slice",
    #           null
    #         ]
    #       ],
    #       [
    #         "Groonga",
    #         {
    #           "default_value": "default"
    #         }
    #       ]
    #     ]
    #   ]
    # ]

カラムの代わりに文字列リテラルを指定することもできます。

実行例:

    select Memos --output_columns 'string_slice("Groonga", "(roon)(g)", 2)'
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         1
    #       ],
    #       [
    #         [
    #           "string_slice",
    #           null
    #         ]
    #       ],
    #       [
    #         "g"
    #       ]
    #     ]
    #   ]
    # ]

## 7.15.23.4. 引数

### 7.15.23.4.1. 位置による抽出

必須引数は2つあります。 `target` と `nth` です。

省略可能引数は2つあります。 `length` と `options` です。

#### 7.15.23.4.1.1. `target`

対象となる文字列または文字列型カラムを指定します。

#### 7.15.23.4.1.2. `nth`

`target` から抽出を開始する位置を0始まりの文字数単位で指定します。

負の値を指定した場合は終端から数えます。

#### 7.15.23.4.1.3. `length`

`nth` から抽出する文字数を指定します。

省略時は1です。

#### 7.15.23.4.1.4. `options`

以下のキーを指定します。

`default_value`

  `length` に0を指定した場合を除いて、部分文字列が空文字列になった場合に返される文字列を指定します。

  省略時は空文字列です。

### 7.15.23.4.2. 正規表現による抽出

必須引数は3つあります。 `target` と `regexp` と `nth` または `name` です。 `nth` と `name` はいずれか一方のみを指定します。

省略可能引数は1つあります。 `options` です。

#### 7.15.23.4.2.1. `target`

対象となる文字列または文字列型カラムを指定します。

#### 7.15.23.4.2.2. `regexp`

正規表現文字列を指定します。

`nth` を使用し、かつ1以上の値を指定する場合は、捕獲式集合 `(式)` を使用する必要があります。

`name` を使用する場合は、名前付き捕獲式集合 `(?<name>式)` または `(?'name'式)` を使用する必要があります。

#### 7.15.23.4.2.3. `nth`

`regexp` の捕獲式集合の番号を指定します。

`regexp` で指定したパターンに一致した時、 `nth` 番目の捕獲式集合の文字列が返却されます。

0を指定すると、 `regexp` で指定したパターンに一致した全体が返却されます。

`nth` か `name` のいずれか一方のみを指定します。

#### 7.15.23.4.2.4. `name`

`regexp` の名前付き捕獲式集合の名前を指定します。

`regexp` で指定したパターンに一致した時、この名前に一致する名前付き捕獲式集合の文字列が返却されます。

`nth` か `name` のいずれか一方のみを指定します。

#### 7.15.23.4.2.5. `options`

以下のキーを指定します。

`default_value`

  `regexp` に一致しなかった場合に返却される文字列を指定します。 `nth` や `name` の値に誤りがある場合もこの値が返却されます。

  省略時は空文字列です。

## 7.15.23.5. 戻り値

`string_slice` は指定した条件で抽出された部分文字列を返却します。