$substrCP (Substring by Code Points)

Last updated: 2026-10-09

$substrCP (Substring by Code Points)

$substrCP extracts a substring counting positions in Unicode code points (roughly characters). It is fully safe for multi-byte text such as Chinese, Japanese, and emoji, making it the recommended operator for user-visible text. Compared with byte-counting $substrBytes, its semantics match how humans count characters. Negative start yields an empty string; negative length yields the rest.

📝 Syntax

{ $substrCP: [ <string-expression>, <code-point-start>, <code-point-length> ] }

⚙️ Parameters

Returns：The extracted substring; null if any argument is null.

▶ Example

Run the commands below in your local mongosh (requires a running mongod):

// $substrCP: first 2 characters of nicknames
 db.users.aggregate([
  { $project: { nickname: { $substrCP: [ '$name', 0, 2 ] } } }
])

Output：

{ "_id": 1, "nickname": "阿明" }
{ "_id": 2, "nickname": "小美" }

📌 Notes

• Counts code points — one Chinese character or emoji counts as 1
• Negative start gives an empty string; negative length gives the rest
• Pair with $strLenCP to avoid out-of-range cutting

🏷️ Related Tags

💡 Related Cases

📚 Related Tutorials

❓ FAQ

Web-Tutorial Tech Team

A team of developers maintaining programming tutorials. Each tutorial is written and reviewed by developers with expertise in that field. We work to keep our content accurate and reliable — if you spot an issue, please let us know.

About Us