本文へスキップ
`Ctrl`+`K`

# 7.16.30. `string_truncate`

Added in version 16.0.9.

## 7.16.30.1. 概要

`string_truncate`は、文字列を指定された文字数以下に切り詰めます。文字列が切り詰められた場合、残された文字の末尾を省略記号に置き換えます。その結果、省略記号を含めて`length`文字の長さになります。これはRuby on Railsの`String#truncate`と同様の動作です。

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

    plugin_register functions/string

## 7.16.30.2. 構文

`string_truncate`は2つから3つの引数を指定できます。

    string_truncate(target, length[, options])

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

    {
      "omission": omission
    }

## 7.16.30.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 is a full text search engine"}
    ]
    # [[0,1337566253.89858,0.000355720520019531],1]

以下は簡単な使用例です。文字列が指定された`length`より長いため、切り詰められ`"..."`が追加されて、結果として15文字になります。

実行例：

    select Memos \
      --output_columns '_key, string_truncate(_key, 15)'
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         1
    #       ],
    #       [
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "string_truncate",
    #           null
    #         ]
    #       ],
    #       [
    #         "Groonga is a full text search engine",
    #         "Groonga is a..."
    #       ]
    #     ]
    #   ]
    # ]

文字列の長さが`length`以下である場合、省略記号を付けずにそのまま返されます。

実行例：

    select Memos \
      --output_columns '_key, string_truncate(_key, 100)'
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         1
    #       ],
    #       [
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "string_truncate",
    #           null
    #         ]
    #       ],
    #       [
    #         "Groonga is a full text search engine",
    #         "Groonga is a full text search engine"
    #       ]
    #     ]
    #   ]
    # ]

次の例では、`options`で`omission`を指定しています。

実行例：

    select Memos \
      --output_columns '_key, string_truncate(_key, 15, { "omission" : "＊＊＊" })'
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         1
    #       ],
    #       [
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "string_truncate",
    #           null
    #         ]
    #       ],
    #       [
    #         "Groonga is a full text search engine",
    #         "Groonga is a＊＊＊"
    #       ]
    #     ]
    #   ]
    # ]

`length`が`omission`の文字数よりも小さい状態で切り詰められた場合、`omission`の文字数が`length`より多くても、結果は`omission`のみとなります。

実行例：

    select Memos \
      --output_columns '_key, string_truncate(_key, 2)'
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         1
    #       ],
    #       [
    #         [
    #           "_key",
    #           "ShortText"
    #         ],
    #         [
    #           "string_truncate",
    #           null
    #         ]
    #       ],
    #       [
    #         "Groonga is a full text search engine",
    #         "..."
    #       ]
    #     ]
    #   ]
    # ]

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

実行例：

    select Memos \
      --output_columns 'string_truncate("Groonga is a fast fulltext search engine", 15)'
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         1
    #       ],
    #       [
    #         [
    #           "string_truncate",
    #           null
    #         ]
    #       ],
    #       [
    #         "Groonga is a..."
    #       ]
    #     ]
    #   ]
    # ]

## 7.16.30.4. 引数

### 7.16.30.4.1. 必須引数

#### 7.16.30.4.1.1. `target`

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

#### 7.16.30.4.1.2. `length`

切り詰めが発生した場合の`omission`の文字数を含め、結果の最大文字数を指定します。`target`の文字数が`length`以下である場合、`target`はそのまま返されます。

`target`の長さが`length`より長い場合、`string_truncate`は`target`の先頭から「`length` - `omission`の文字数」分を切り出し、末尾に`omission`を追加します。`omission`が`length`より長い場合や`length`が負の場合は、`omission`のみになります。

### 7.16.30.4.2. 省略可能引数

#### 7.16.30.4.2.1. `options`

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

- `omission`

  - 切り詰められたことを示す文字列を指定します。

  - デフォルトは`"..."`です。

## 7.16.30.5. 戻り値

`string_truncate`は`target`を切り詰めた結果を返します。切り詰めが行われた場合、結果（保持された部分と`omission`の合計）の長さは`length`文字になります。ただし、`omission`が`length`より長い場合や`length`が負の値の場合は、`omission`のみになります。

## 7.16.30.6. 参考

- snippet

- string_substring