DOCSP-29680 bitAnd Aggregation Operator (#3082)

* DOCSP-2960 bitAnd Aggregation Operator

* DOCSP-29680 bitAnd Aggregation Operator

* add to TOC, aggregation operator page

* update title

* JA feedback

* typos

* JA feedback pt 2

* davis feedback

* unordered lists

* learn more bullets

Author: ajhuh-mdb

source/includes/fact-mongosh-integer-long-constructors.rst

@@ -0,0 +1,12 @@
+.. note:: 
+    
+    All numbers in :binary:`~bin.mongosh` are doubles, not integers. To to 
+    specify integers in :binary:`~bin.mongosh`, use the ``NumberInt()`` or the 
+    ``NumberLong()`` constructor. To learn more, see :ref:`shell-type-int` or 
+    :ref:`shell-type-long`.
+
+    To learn how your MongoDB driver handles numeric values, refer to your 
+    :driver:`driver's documentation </>`.
+
+    
+    

source/meta/aggregation-quick-reference.txt

@@ -355,6 +355,7 @@ Index of Expression Operators
    - :expression:`$atanh`
    - :group:`$avg`
    - :expression:`$binarySize`
+   - :expression:`$bitAnd`
    - :expression:`$bsonSize`
    - :expression:`$ceil`
    - :expression:`$cmp`

source/reference/operator/aggregation.txt

@@ -267,6 +267,13 @@ Alphabetical Listing of Expression Operators
 
        .. versionadded:: 4.4
 
+   * - :expression:`$bitAnd`
+
+     - Returns the result of a bitwise ``and`` operation on an array of ``int`` 
+       or ``long`` values. 
+
+       .. versionadded:: 6.3
+
    * - :group:`$bottom`
 
      - Returns the bottom element within a group according to the specified 
@@ -1278,6 +1285,7 @@ Alphabetical Listing of Expression Operators
    /reference/operator/aggregation/atanh
    /reference/operator/aggregation/avg
    /reference/operator/aggregation/binarySize
+   /reference/operator/aggregation/bitAnd
    /reference/operator/aggregation/bottom
    /reference/operator/aggregation/bottomN
    /reference/operator/aggregation/bsonSize

source/reference/operator/aggregation/bitAnd.txt

@@ -0,0 +1,121 @@
+=====================
+$bitAnd (aggregation)
+=====================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+  :local:
+  :backlinks: none
+  :depth: 1
+  :class: singlecol
+
+Definition
+----------
+
+.. versionadded:: 6.3
+
+.. expression:: $bitAnd 
+
+    Returns the result of a bitwise ``and`` operation on an array of ``int`` or 
+    ``long`` values. 
+
+Syntax 
+------
+
+The :expression:`$bitAnd` operator has the following syntax: 
+
+.. code-block:: javascript
+
+      { $bitAnd: { [ <expression1>, <expression2>, ... ] }
+
+Behavior
+--------
+
+If the operands include both integers and long values, MongoDB sign-extends the 
+calculated integer result and returns a long value. Otherwise, if the operands 
+include only integers or only longs, MongoDB returns results with the 
+corresponding value type.
+
+.. include:: /includes/fact-mongosh-integer-long-constructors.rst
+
+If any of the operands equate to ``null``, the operation returns ``null``. 
+
+Examples
+--------
+
+The examples on this page use the ``switches`` collection, which contains the 
+following documents: 
+
+.. code-block:: javascript 
+
+    db.switches.insertMany( [
+        { _id: 0, a: NumberInt(0), b: NumberInt(127) },
+        { _id: 1, a: NumberInt(2), b: NumberInt(3) },
+        { _id: 2, a: NumberInt(3), b: NumberInt(5) }
+    ] )
+
+Bitwise ``AND`` with Two Integers 
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following aggregation uses the :expression:`$bitAnd` operator in the 
+:pipeline:`$project` stage:
+
+.. code-block:: javascript 
+
+    db.switches.aggregate( [
+      { 
+        $project: { 
+          result: { 
+            $bitAnd: [ "$a", "$b" ]
+          }
+        }
+      }
+    ])
+
+The operation returns the following results:
+
+.. code-block:: javascript 
+  :copyable: false
+
+    [
+      { _id: 0, result: 0 }
+      { _id: 1, result: 2 }
+      { _id: 2, result: 1 }
+    ]
+
+Bitwise ``AND`` with a Long and Integer 
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following aggregation uses the :expression:`$bitAnd` operator in the 
+:pipeline:`$project` stage:
+
+.. code-block:: javascript 
+
+    db.switches.aggregate( [
+      { 
+        $project: { 
+          result: { 
+            $bitAnd: [ "$a", NumberLong("63") ]
+          }
+        }
+      }
+    ])
+
+The operation returns the following results:
+
+.. code-block:: javascript 
+  :copyable: false
+    
+    [
+      { _id: 0, result: Long("0") }
+      { _id: 1, result: Long("2") }
+      { _id: 2, result: Long("3") }
+    ]
+
+Learn More 
+----------
+
+- :ref:`aggregation-pipeline-operators`
+
+- :ref:`update-bit`

source/reference/operator/update/bit.txt

@@ -1,3 +1,5 @@
+.. _update-bit:
+
 ====
 $bit
 ====
@@ -30,12 +32,7 @@ Definition
 
    .. include:: /includes/use-dot-notation.rst
 
-   .. note::
-
-      All numbers in :binary:`~bin.mongosh` are doubles, not
-      integers. Use the ``NumberInt()`` or the ``NumberLong()``
-      constructor to specify integers. See :ref:`shell-type-int` or
-      :ref:`shell-type-long` for more information.
+   .. include:: /includes/fact-mongosh-integer-long-constructors.rst
 
 Behavior
 --------