$substrCP (Substring por Code Points)
Última atualização: 2026-10-09
$substrCP (Substring por Code Points)
$substrCP extrai uma substring contando posições em code points Unicode (aproximadamente caracteres). É totalmente seguro para texto multibyte, como chinês, japonês e emoji, o que o torna o operador recomendado para texto visível ao usuário. Comparado ao $substrBytes, que conta bytes, sua semântica coincide com a forma como humanos contam caracteres. Start negativo resulta em string vazia; length negativo resulta no restante.
| Categoria | String |
|---|---|
| Versão do MongoDB | 1.0+ |
| Idioma do Exemplo | mongosh (Shell) |
📝 Sintaxe
{ $substrCP: [ <expressão de string>, <início em code points>, <comprimento em code points> ] }⚙️ Parâmetros
| string | Obrigatório; a expressão de string de origem. |
|---|---|
| posição inicial em code points | Inteiro obrigatório em pontos de código, base zero. |
| comprimento em code points | Inteiro obrigatório em pontos de código. |
Retorno：A substring extraída; null se qualquer argumento for null.
▶ Exemplo
Execute os comandos abaixo no seu mongosh local (requer um mongod em execução):
// $substrCP: primeiros 2 caracteres de apelidos
db.users.aggregate([
{ $project: { nickname: { $substrCP: [ '$name', 0, 2 ] } } }
])Saída：
{ "_id": 1, "nickname": "ひか" }
{ "_id": 2, "nickname": "たろ" }📌 Notas
- Conta code points — um caractere chinês ou emoji conta como 1
- Start negativo resulta em string vazia; length negativo resulta no restante
- Combine com $strLenCP para evitar cortes fora do intervalo
🏷️ Tags Relacionados
💡 Casos Relacionados
Mais casos práticos em breve.
📚 Tutoriais Relacionados
❓ Perguntas Frequentes
QQuantos caracteres tem um emoji?
AA maioria dos emojis é um code point (conta como 1), mas emojis compostos podem ocupar vários.
QQuando escolher $substrCP em vez de $substrBytes?
AUse $substrCP para texto visível ao usuário; $substrBytes para contagens exatas de bytes.
QE se o comprimento exceder a string?
AEle retorna o que resta — sem erro.
