$substrBytes (agregação)
Nesta página
Definição
$substrBytes
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> ] } CampoTipoDescriçãostring expression
stringA string da qual a substring será extraída.
string expression
pode ser qualquer expressão válida desde que resolva para uma string. Para obter mais informações sobre expressões, consulte Operadores de Expressão.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úmeroIndica 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úmeroPode 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, os 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.
Exemplo | Resultados | ||
---|---|---|---|
|
| ||
|
| ||
|
| ||
|
| ||
| Erro com mensagem:
| ||
| Erro com mensagem:
|
Exemplo
Conjunto de caracteres de byte único
Considere uma coleção inventory
com os seguintes documentos:
{ "_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 }
A operação a seguir usa o operador $substrBytes
para separar o valor quarter
(contendo apenas caracteres US-ASCII de byte único) em um yearSubstring
e um quarterSubstring
. O campo quarterSubstring
representa o resto da string a partir do byte index
especificado depois de yearSubstring
. Ele é calculado subtraindo o byte index
do comprimento da string utilizando $strLenBytes
.
db.inventory.aggregate( [ { $project: { item: 1, yearSubstring: { $substrBytes: [ "$quarter", 0, 2 ] }, quarterSubtring: { $substrBytes: [ "$quarter", 2, { $subtract: [ { $strLenBytes: "$quarter" }, 2 ] } ] } } } ] )
A operação retorna os seguintes resultados:
{ "_id" : 1, "item" : "ABC1", "yearSubstring" : "13", "quarterSubtring" : "Q1" } { "_id" : 2, "item" : "ABC2", "yearSubstring" : "13", "quarterSubtring" : "Q4" } { "_id" : 3, "item" : "XYZ1", "yearSubstring" : "14", "quarterSubtring" : "Q2" }
Conjunto de caracteres de byte único e multibyte
Criar uma coleção food
com os seguintes documentos:
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" } ] )
A seguinte operação utiliza o operador $substrBytes
para criar um menuCode
de três bytes a partir do valor name
:
db.food.aggregate( [ { $project: { "name": 1, "menuCode": { $substrBytes: [ "$name", 0, 3 ] } } } ] )
A operação retorna os seguintes resultados:
{ "_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" : "寿" }