/ /

$substrBytes（式演算子）

定義

$substrBytes

文字列の部分文字列を返します。部分文字列は次で始まります: 指定された UTF-8 バイトインデックス (ゼロベース) の文字文字列で、指定されたバイト数だけ続行します。

$substrBytes has the following operator expression syntax:

{ $substrBytes: [ <string expression>, <byte index>, <byte count> ] }

フィールド	タイプ	説明
`string expression`	string	部分文字列が抽出される string。 `string expression`は、string に変換される限り、任意の有効な式にすることができます。式の詳細については、「式」を参照してください。 If the argument resolves to a value of `null` or refers to a field that is missing, `$substrBytes` returns an empty string. If the argument does not resolve to a string or `null` nor refers to a missing field, `$substrBytes` returns an error.
`byte index`	数値	部分文字列の開始点を示します。 `byte index`は、整数で表せる負でない整数または数値（2.0 など）に変換される限り、任意の有効な式にすることができます。 `byte index` は、マルチバイトの UTF-8 文字の途中にある開始インデックスを参照できません。
`byte count`	数値	は、整数で表せる負でない整数または数値（2.0など）に解決される限り、任意の有効な式を指定できます。 `byte count` は、UTF-8 文字の途中で終了するインデックスを生成することはできません。

動作

$substrBytes演算子は、UTF-8 でエンコードされたバイトのインデックスを使用します。ここで、各コード点、または文字は 1 バイトから 4 バイトの間をエンコードに使用できます。

たとえば、US-ASCII 文字は 1 バイトを使用してエンコードされます。発音区別符号を持つ文字と追加のラテン文字（アルファベットの外のラテン文字）を持つ文字は、2 バイトを使用してエンコードされます。中国語、日本語、韓国語の文字は通常 3 バイト必要であり、Unicode の他のプレーン（文字列、数学記号など）には 4 バイトが必要です。

UTF-8 文字の中間にbyte indexまたはbyte countを配置するとエラーが発生するため、 string expressionの内容に注意することが重要です。

$substrBytes differs from $substrCP in that $substrBytes counts the bytes of each character, whereas $substrCP counts the code points, or characters, regardless of how many bytes a character uses.

例

結果

{ $substrBytes: [ "abcde", 1, 2 ] }

"bc"

{ $substrBytes: [ "Hello World!", 6, 5 ] }

 "World"

{ $substrBytes: [ "cafétéria", 0, 5 ] }

"café"

{ $substrBytes: [ "cafétéria", 5, 4 ] }

"tér"

{ $substrBytes: [ "cafétéria", 7, 3 ] }

次のメッセージ付きのエラー。

"Error: Invalid range, starting index is a UTF-8 continuation byte."

{ $substrBytes: [ "cafétéria", 3, 1 ] }

次のメッセージ付きのエラー。

"Error: Invalid range, ending index is in the middle of a UTF-8 character."

例

1 バイトの文字セット

以下のドキュメントを持つinventoryコレクションを検討してください。

db.inventory.insertMany( [
   { _id: 1, item: "ABC1", quarter: "13Q1", description: "product 1" },
   { _id: 2, item: "ABC2", quarter: "13Q4", description: "product 2" },
   { _id: 3, item: "XYZ1", quarter: "14Q2", description: null }
] )

The following operation uses the $substrBytes operator separate the quarter value (containing only single byte US-ASCII characters) into a yearSubstring and a quarterSubstring. The quarterSubstring field represents the rest of the string from the specified byte index following the yearSubstring. It is calculated by subtracting the byte index from the length of the string using $strLenBytes.

db.inventory.aggregate(
  [
    {
      $project: {
        item: 1,
        yearSubstring: { $substrBytes: [ "$quarter", 0, 2 ] },
        quarterSubstring: {
          $substrBytes: [
            "$quarter", 2, { $subtract: [ { $strLenBytes: "$quarter" }, 2 ] }
          ]
        }
      }
    }
  ]
)

この操作は次の結果を返します。

{ _id: 1, item: "ABC1", yearSubstring: "13", quarterSubstring: "Q1" }
{ _id: 2, item: "ABC2", yearSubstring: "13", quarterSubstring: "Q4" }
{ _id: 3, item: "XYZ1", yearSubstring: "14", quarterSubstring: "Q2" }

シングルバイトおよびマルチバイト文字セット

次のドキュメントを使用して food コレクションを作成します。

db.food.insertMany(
 [
    { _id: 1, name: "apple" },
    { _id: 2, name: "banana" },
    { _id: 3, name: "éclair" },
    { _id: 4, name: "hamburger" },
    { _id: 5, name: "jalapeño" },
    { _id: 6, name: "pizza" },
    { _id: 7, name: "tacos" },
    { _id: 8, name: "寿司sushi" }
 ]
)

次の操作では、 $substrBytes演算子を使用して、 nameの値から 3 バイトのmenuCodeを作成します。

db.food.aggregate(
  [
    {
      $project: {
        "name": 1,
        "menuCode": { $substrBytes: [ "$name", 0, 3 ] }
      }
    }
  ]
)

この操作は次の結果を返します。

{ _id: 1, name: "apple", menuCode: "app" }
{ _id: 2, name: "banana", menuCode: "ban" }
{ _id: 3, name: "éclair", menuCode: "éc" }
{ _id: 4, name: "hamburger", menuCode: "ham" }
{ _id: 5, name: "jalapeño", menuCode: "jal" }
{ _id: 6, name: "pizza", menuCode: "piz" }
{ _id: 7, name: "tacos", menuCode: "tac" }
{ _id: 8, name: "寿司sushi", menuCode: "寿" }

Tip