$indexOfCP (aggregation)

Definition

• $indexOfCP

New in version 3.4.

Searches a string for an occurence of a substring and returns theUTF-8 code pointindex (zero-based) of the first occurence. If thesubstring is not found, returns -1.

$indexOfCP has the following operatorexpression syntax:

{ $indexOfCP: [ <string expression>, <substring expression>, <start>, <end> ] }

FieldTypeDescription<string>stringCan be any valid expression as longas it resolves to a string. For more information on expressions, seeExpressions.

If the string expression resolves to a value of null or refersto a field that is missing, $indexOfCP returnsnull.

If the string expression does not resolve to a string or nullnor refers to a missing field, $indexOfCP returns anerror.<substring>stringCan be any valid expression as longas it resolves to a string. For more information on expressions, seeExpressions.<start>integerOptional. An integer, or a number that can be represented as integers (such as2.0), that specifies the starting index position for the search. Canbe any valid expression thatresolves to a non-negative integral number.

If unspecified, the starting index position for the search is thebeginning of the string.<end>integerOptional. An integer, or a number that can be represented as integers (such as2.0), that specifies the ending index position for the search. Canbe any valid expression thatresolves to a non-negative integral number. If you specify a<end> index value, you should also specify a <start> indexvalue; otherwise, $indexOfCP uses the <end> valueas the <start> index value instead of the <end> value.

If unspecified, the ending index position for the search is theend of the string.

Behavior

If the <substring expression> is found multiple times within the<string expression>, then $indexOfCP returns theindex of the first <substring expression> found from the startingindex position.

$indexOfCP returns null:

• If <string expression> is null, or
• If <string expression> refers to a non-existing field in theinput document.

$indexOfCP returns an error:

• If <string expression> is not a string and not null, or
• If <substring expression> is null or is not a string or refers toa nonexistent field in the input document, or
• If <start> or <end> is a negative integer (or a value thatcan be represented as a negative integer, like -5.0).

$indexOfCP returns -1:

• If the substring is not found in the <string expression>, or
• If <start> is a number greater than <end>, or
• If <start> is a number greater than the byte length of the string.

Examples

Consider an inventory collection with the following documents:

{ "_id" : 1, "item" : "foo" }
{ "_id" : 2, "item" : "fóofoo" }
{ "_id" : 3, "item" : "the foo bar" }
{ "_id" : 4, "item" : "hello world fóo" }
{ "_id" : 5, "item" : null }
{ "_id" : 6, "amount" : 3 }

The following operation uses the $indexOfCP operator toreturn the code point index at which the string foo is located ineach item string:

db.inventory.aggregate(
   [
     {
       $project:
          {
            cpLocation: { $indexOfCP: [ "$item", "foo" ] },
          }
      }
   ]
)

The operation returns the following results:

{ "_id" : 1, "cpLocation" : "0" }
{ "_id" : 2, "cpLocation" : "3" }
{ "_id" : 3, "cpLocation" : "4" }
{ "_id" : 4, "cpLocation" : "-1" }
{ "_id" : 5, "cpLocation" : null }
{ "_id" : 6, "cpLocation" : null }

See also

$indexOfBytes and $indexOfArray