$substrBytes (agregação)

Definição

$substrBytes

Novidade na versão 3.4.

Retorna a substring de uma string. A substring começa com o caractere no índice de bytes UTF-8 especificado (baseado em zero) na string e continua para o número de bytes especificados.

$substrBytes tem a seguintesintaxe de expressão do operador :

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

Campo	Tipo	Descrição
string expression	string	A string da qual a substring será extraída. string expression pode ser qualquer expressão válida desde que resolva para uma string. Para mais informações sobre expressões, consulte Expressões. Se o argumento for resolvido para um valor de null ou se referir a um campo ausente, $substrBytes retornará uma string vazia. Se o argumento não se resolver em uma string ou null nem se referir a um campo ausente, $substrBytes retornará um erro.
byte index	número	Indica o ponto de partida da substring. byte index pode ser qualquer expressão válida, desde que resolva para um número inteiro não negativo ou número que possa ser representado como um número inteiro (como 2.0). byte index não pode se referir a um índice inicial localizado no meio de um caractere UTF-8 de vários bytes.
byte count	número	Pode ser qualquer expressão válida, desde que resolva para um número inteiro não negativo ou número que possa ser representado como um número inteiro (como 2.0). byte count não pode resultar em um índice final que esteja no meio de um caractere UTF-8.

Comportamento

O operador $substrBytes usa os índices de bytes codificados em UTF-8 em que cada ponto de código, ou caractere, pode usar entre um e quatro bytes para codificar.

Por exemplo, caracteres US-ASCII são codificados usando um byte. Caracteres com diacríticos e caracteres alfabéticos latinos adicionais (caracteres latinos fora do alfabeto inglês) são codificados usando dois bytes. Caracteres chineses, tailandeses e coreanos normalmente exigem três bytes, e outros planos de unicode (emoji, símbolos matemáticos etc.) exigem quatro bytes.

É importante estar atento ao conteúdo do string expression porque fornecer um byte index ou byte count localizado no meio de um caractere UTF-8 resultará em um erro.

$substrBytes difere de $substrCP em que $substrBytes conta os bytes de cada caractere, enquanto $substrCP conta os pontos de código, ou caracteres, independentemente de quantos bytes um caractere utiliza.

{ $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 ] }

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

Exemplo

{ "_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 }

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

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

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" }
 ]
)

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" : "寿" }