Skip to content

Commit 3e76c21

Browse files
kay-kimkay-kim
committed
DOCS-8529 indexOfCP and indexOfArray (Chris Long) + edits
1 parent 36316e9 commit 3e76c21

File tree

7 files changed

+449
-173
lines changed

7 files changed

+449
-173
lines changed

‎source/includes/apiargs-agg-indexOfArray-fields.yaml‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
name: <string>
2+
position: 1
3+
type: string
4+
description: |
5+
6+
Can be any valid :ref:`expression <aggregation-expressions>` as long
7+
as it resolves to an array. For more information on expressions, see
8+
:ref:`aggregation-expressions`.
9+
10+
If the array expression resolves to a value of ``null`` or refers to
11+
a field that is missing, :expression:`$indexOfArray` returns
12+
``null``.
13+
14+
If the array expression does not resolve to an array or ``null`` nor
15+
refers to a missing field, :expression:`$indexOfArray` returns an
16+
error.
17+
optional: false
18+
operation: indexOfArray
19+
interface: pipeline
20+
arg_name: field
21+
---
22+
name: <substring>
23+
position: 2
24+
type: string
25+
description: |
26+
Can be any valid :ref:`expression <aggregation-expressions>`. For
27+
more information on expressions, see :ref:`aggregation-expressions`.
28+
optional: false
29+
operation: indexOfArray
30+
interface: pipeline
31+
arg_name: field
32+
---
33+
name: <start>
34+
position: 3
35+
type: integer
36+
description: |
37+
An integer, or a number that can be represented as integers (such as
38+
2.0), that specifies the starting index position for the search. Can
39+
be any valid :ref:`expression <aggregation-expressions>` that
40+
resolves to a non-negative integral number.
41+
42+
If unspecified, the starting index position for the search is the
43+
beginning of the string.
44+
optional: true
45+
operation: indexOfArray
46+
interface: pipeline
47+
arg_name: field
48+
---
49+
name: <end>
50+
position: 4
51+
type: integer
52+
description: |
53+
An integer, or a number that can be represented as integers (such as
54+
2.0), that specifies the ending index position for the search. Can
55+
be any valid :ref:`expression <aggregation-expressions>` that
56+
resolves to a non-negative integral number. If you specify a
57+
``<end>`` index value, you should also specify a ``<start>`` index
58+
value; otherwise, :expression:`$indexOfArray` uses the ``<end>``
59+
value as the ``<start>`` index value instead of the ``<end>`` value.
60+
61+
If unspecified, the ending index position for the search is the
62+
end of the string.
63+
optional: true
64+
operation: indexOfArray
65+
interface: pipeline
66+
arg_name: field
67+
...

‎source/includes/apiargs-agg-indexOfCP-fields.yaml‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
name: <string>
2+
position: 1
3+
type: string
4+
description: |
5+
6+
Can be any valid :ref:`expression <aggregation-expressions>` as long
7+
as it resolves to a string. For more information on expressions, see
8+
:ref:`aggregation-expressions`.
9+
10+
If the string expression resolves to a value of ``null`` or refers
11+
to a field that is missing, :expression:`$indexOfCP` returns
12+
``null``.
13+
14+
If the string expression does not resolve to a string or ``null``
15+
nor refers to a missing field, :expression:`$indexOfCP` returns an
16+
error.
17+
optional: false
18+
operation: indexOfCP
19+
interface: pipeline
20+
arg_name: field
21+
---
22+
name: <substring>
23+
position: 2
24+
type: string
25+
description: |
26+
Can be any valid :ref:`expression <aggregation-expressions>` as long
27+
as it resolves to a string. For more information on expressions, see
28+
:ref:`aggregation-expressions`.
29+
optional: false
30+
operation: indexOfCP
31+
interface: pipeline
32+
arg_name: field
33+
---
34+
name: <start>
35+
position: 3
36+
type: integer
37+
description: |
38+
An integer, or a number that can be represented as integers (such as
39+
2.0), that specifies the starting index position for the search. Can
40+
be any valid :ref:`expression <aggregation-expressions>` that
41+
resolves to a non-negative integral number.
42+
43+
If unspecified, the starting index position for the search is the
44+
beginning of the string.
45+
optional: true
46+
operation: indexOfCP
47+
interface: pipeline
48+
arg_name: field
49+
---
50+
name: <end>
51+
position: 4
52+
type: integer
53+
description: |
54+
An integer, or a number that can be represented as integers (such as
55+
2.0), that specifies the ending index position for the search. Can
56+
be any valid :ref:`expression <aggregation-expressions>` that
57+
resolves to a non-negative integral number. If you specify a
58+
``<end>`` index value, you should also specify a ``<start>`` index
59+
value; otherwise, :expression:`$indexOfCP` uses the ``<end>`` value
60+
as the ``<start>`` index value instead of the ``<end>`` value.
61+
62+
If unspecified, the ending index position for the search is the
63+
end of the string.
64+
optional: true
65+
operation: indexOfCP
66+
interface: pipeline
67+
arg_name: field
68+
...

‎source/includes/ref-toc-aggregation-array.yaml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,13 @@ description: |
1414
Selects a subset of the array to return an array with only the elements
1515
that match the filter condition.
1616
---
17+
name: :expression:`$indexOfArray`
18+
file: /reference/operator/aggregation/indexOfArray
19+
description: |
20+
Searches an array for an occurence of a specified value and returns
21+
the array index of the first occurence. If the substring is not found,
22+
returns ``-1``.
23+
---
1724
name: :expression:`$isArray`
1825
file: /reference/operator/aggregation/isArray
1926
description: |

‎source/includes/ref-toc-aggregation-string.yaml‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,13 @@ description: |
1010
UTF-8 byte index of the first occurence. If the substring is not
1111
found, returns ``-1``.
1212
---
13+
name: :expression:`$indexOfCP`
14+
file: /reference/operator/aggregation/indexOfCP
15+
description: |
16+
Searches a string for an occurence of a substring and returns the
17+
UTF-8 code point index of the first occurence. If the
18+
substring is not found, returns ``-1``.
19+
---
1320
name: :expression:`$split`
1421
file: /reference/operator/aggregation/split
1522
description: |
@@ -35,6 +42,13 @@ description: |
3542
Returns the number of UTF-8 `code points
3643
<http://www.unicode.org/glossary/#code_point>`_ in a string.
3744
---
45+
name: :expression:`$strcasecmp`
46+
file: /reference/operator/aggregation/strcasecmp
47+
description: |
48+
Performs case-insensitive string comparison and returns: ``0`` if two
49+
strings are equivalent, ``1`` if the first string is greater than the
50+
second, and ``-1`` if the first string is less than the second.
51+
---
3852
name: :expression:`$substr`
3953
file: /reference/operator/aggregation/substr
4054
description: |

‎source/reference/operator/aggregation/indexOfArray.txt‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
===========================
2+
$indexOfArray (aggregation)
3+
===========================
4+
5+
.. default-domain:: mongodb
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 1
11+
:class: singlecol
12+
13+
Definition
14+
----------
15+
16+
.. expression:: $indexOfArray
17+
18+
.. versionadded:: 3.4
19+
20+
Searches an array for an occurence of a specified value and returns
21+
the array index (zero-based) of the first occurence. If the
22+
value is not found, returns ``-1``.
23+
24+
:expression:`$indexOfArray` has the following :ref:`operator
25+
expression syntax <agg-quick-ref-operator-expressions>`:
26+
27+
.. code-block:: javascript
28+
29+
{ $indexOfArray: [ <array expression>, <search expression>, <start>, <end> ] }
30+
31+
.. include:: /includes/apiargs/agg-indexOfArray-fields.rst
32+
33+
Behavior
34+
--------
35+
36+
If the ``<search expression>`` is found multiple times within the
37+
``<array expression>``, then :expression:`$indexOfArray` returns the
38+
index of the first ``<search expression>`` from the starting index
39+
position.
40+
41+
:expression:`$indexOfArray` returns ``null``:
42+
43+
- If ``<array expression>`` is null, or
44+
45+
- If ``<array expression>`` refers to a non-existing field in the input
46+
document.
47+
48+
:expression:`$indexOfArray` returns an error:
49+
50+
- If ``<array expression>`` is not an array and not null, or
51+
52+
- If ``<start>`` or ``<end>`` is a negative integer (or a value that
53+
can be represented as a negative integer, like -5.0).
54+
55+
:expression:`$indexOfArray` returns ``-1``:
56+
57+
- If the <search expression> is not found in the array, or
58+
59+
- If ``<start>`` is a number greater than ``<end>``, or
60+
61+
- If ``<start>`` is a number greater than the length of the array.
62+
63+
.. list-table::
64+
:header-rows: 1
65+
:widths: 95 5
66+
67+
* - Example
68+
- Results
69+
70+
* - ``{ $indexOfArray: [ [ "a", "abc" ], "a" ] }``
71+
- ``0``
72+
73+
* - ``{ $indexOfArray: [ [ "a", "abc", "de", ["de"] ], ["de"] ] }``
74+
- ``3``
75+
76+
* - ``{ $indexOfArray: [ [ 1, 2 ], 5 ] }``
77+
- ``-1``
78+
79+
* - ``{ $indexOfArray: [ [ 1, 2, 3 ], [1, 2] ] }``
80+
- ``-1``
81+
82+
* - ``{ $indexOfArray: [ [ 10, 9, 9, 8, 9 ], 9, 3 ] }``
83+
- ``4``
84+
85+
* - ``{ $indexOfArray: [ [ "a", "abc", "b" ], "b", 0, 1 ] }``
86+
- ``-1``
87+
88+
* - ``{ $indexOfArray: [ [ "a", "abc", "b" ], "b", 1, 0 ] }``
89+
- ``-1``
90+
91+
* - ``{ $indexOfArray: [ [ "a", "abc", "b" ], "b", 20 ] }``
92+
- ``-1``
93+
94+
* - ``{ $indexOfArray: [ [ null, null, null ], null ] }``
95+
- ``0``
96+
97+
* - ``{ $indexOfArray: [ null, "foo" ] }``
98+
- ``null``
99+
100+
* - ``{ $indexOfArray: [ "foo", "foo" ] }``
101+
- Error
102+
103+
Examples
104+
--------
105+
106+
Consider an ``inventory`` collection with the following documents:
107+
108+
.. code-block:: javascript
109+
110+
{ "_id" : 1, "items" : ["one", "two", "three"] }
111+
{ "_id" : 2, "items" : [1, 2, 3] }
112+
{ "_id" : 3, "items" : [null, null, 2] }
113+
{ "_id" : 4, "items" : null }
114+
{ "_id" : 5, "amount" : 3 }
115+
116+
The following operation uses the :expression:`$indexOfArray` operator to
117+
return the array index at which the string ``foo`` is located in each ``items`` array:
118+
119+
.. code-block:: javascript
120+
121+
db.inventory.aggregate(
122+
[
123+
{
124+
$project:
125+
{
126+
index: { $indexOfArray: [ "$items", 2 ] },
127+
}
128+
}
129+
]
130+
)
131+
132+
The operation returns the following results:
133+
134+
.. code-block:: javascript
135+
136+
{ "_id" : 1, "index" : "-1" }
137+
{ "_id" : 2, "index" : "1" }
138+
{ "_id" : 3, "index" : "2" }
139+
{ "_id" : 4, "index" : null }
140+
{ "_id" : 5, "index" : null }
141+
142+
143+
.. seealso:: :expression:`$indexOfBytes`, :expression:`$indexOfCP`, and :expression:`$in`

0 commit comments

Comments
 (0)