DOCS-5855: Document the new bitwise query operators

source/includes/extracts-fact-query-bitwise.yaml

@@ -0,0 +1,183 @@
+ref: _fact-query-bitwise-description
+content: |
+  .. list-table::
+
+     * - ``{ <field>: { {{op}}: <numeric bitmask> } }``
+
+     * - ``{ <field>: { {{op}}: <`` :bsontype:`BinData <data_binary>` ``bitmask> } }``
+
+     * - ``{ <field>: { {{op}}: [ <position1>, <position2>, ... ] } }``
+
+  The ``field`` value must be either numerical or a
+  :bsontype:`BinData <data_binary>` instance. Otherwise, :query:`{{op}}`
+  will not match the current document.
+
+  Numeric Bitmask
+    You can provide a numeric bitmask to be matched against the operand field.
+    It must be representable as a non-negative 32-bit signed integer. Otherwise,
+    :query:`{{op}}` will return an error.
+
+  BinData Bitmask
+    You can also use an arbitrarily large :bsontype:`BinData <data_binary>`
+    instance as a bitmask.
+
+  Position List
+    If querying a list of bit positions, each ``<position>`` must be a non-negative
+    integer. Bit positions start at ``0`` from the least significant bit. For
+    example, the decimal number ``254`` would have the following bit positions:
+
+  .. list-table::
+
+     * - **Bit Value**
+
+       - 1
+
+       - 1
+
+       - 1
+
+       - 1
+
+       - 1
+
+       - 1
+
+       - 1
+
+       - 0
+
+     * - **Position**
+
+       - 7
+
+       - 6
+
+       - 5
+
+       - 4
+
+       - 3
+
+       - 2
+
+       - 1
+
+       - 0
+---
+ref: fact-query-bitsallset-description
+replacement:
+  op: "$bitsAllSet"
+inherit:
+  ref: _fact-query-bitwise-description
+  file: extracts-fact-query-bitwise.yaml
+---
+ref: fact-query-bitsanyset-description
+replacement:
+  op: "$bitsAnySet"
+inherit:
+  ref: _fact-query-bitwise-description
+  file: extracts-fact-query-bitwise.yaml
+---
+ref: fact-query-bitsallclear-description
+replacement:
+  op: "$bitsAllClear"
+inherit:
+  ref: _fact-query-bitwise-description
+  file: extracts-fact-query-bitwise.yaml
+---
+ref: fact-query-bitsanyclear-description
+replacement:
+  op: "$bitsAnyClear"
+inherit:
+  ref: _fact-query-bitwise-description
+  file: extracts-fact-query-bitwise.yaml
+---
+ref: _fact-query-bitwise-floating-point
+content: |
+  :query:`{{op}}` will not match numerical values that cannot be represented as
+  a signed 64-bit integer. This can be the case if a value is either too large
+  or small to fit in a signed 64-bit integer, or if it has a fractional
+  component.
+---
+ref: fact-query-bitsallset-floating-point
+replacement:
+  op: "$bitsAllSet"
+inherit:
+  ref: _fact-query-bitwise-floating-point
+  file: extracts-fact-query-bitwise.yaml
+---
+ref: fact-query-bitsanyset-floating-point
+replacement:
+  op: "$bitsAnySet"
+inherit:
+  ref: _fact-query-bitwise-floating-point
+  file: extracts-fact-query-bitwise.yaml
+---
+ref: fact-query-bitsallclear-floating-point
+replacement:
+  op: "$bitsAllClear"
+inherit:
+  ref: _fact-query-bitwise-floating-point
+  file: extracts-fact-query-bitwise.yaml
+---
+ref: fact-query-bitsanyclear-floating-point
+replacement:
+  op: "$bitsAnyClear"
+inherit:
+  ref: _fact-query-bitwise-floating-point
+  file: extracts-fact-query-bitwise.yaml
+---
+ref: _fact-query-bitwise-sign-extension
+content: |
+  Numbers are sign extended. For example, {{op}} considers bit position ``200``
+  to be set for the negative number ``-5``, but bit position ``200`` to be clear
+  for the positive number ``+5``.
+
+  In contrast, :bsontype:`BinData <data_binary>` instances are zero-extended.
+  For example, given the following document:
+
+  .. code-block:: javascript
+
+     db.collection.save({ x: BinData(0, "ww=="), binaryValueofA: "11000011" })
+
+  {{op}} will consider all bits outside of ``x`` to be clear.
+---
+ref: fact-query-bitsallset-sign-extension
+replacement:
+  op: "$bitsAllSet"
+inherit:
+  ref: _fact-query-bitwise-sign-extension
+  file: extracts-fact-query-bitwise.yaml
+---
+ref: fact-query-bitsanyset-sign-extension
+replacement:
+  op: "$bitsAnySet"
+inherit:
+  ref: _fact-query-bitwise-sign-extension
+  file: extracts-fact-query-bitwise.yaml
+---
+ref: fact-query-bitsallclear-sign-extension
+replacement:
+  op: "$bitsAllClear"
+inherit:
+  ref: _fact-query-bitwise-sign-extension
+  file: extracts-fact-query-bitwise.yaml
+---
+ref: fact-query-bitsanyclear-sign-extension
+replacement:
+  op: "$bitsAnyClear"
+inherit:
+  ref: _fact-query-bitwise-sign-extension
+  file: extracts-fact-query-bitwise.yaml
+---
+ref: fact-query-bitwise-example-collection
+content: |
+  The following examples will use a collection with the following documents:
+
+  .. code-block:: javascript
+
+     db.collection.save({ _id: 1, a: 54, binaryValueofA: "00110110" })
+     db.collection.save({ _id: 2, a: 20, binaryValueofA: "00010100" })
+     db.collection.save({ _id: 3, a: 20.0, binaryValueofA: "00010100" })
+     db.collection.save({ _id: 4, a: BinData(0, "Zg=="), binaryValueofA: "01100110" })
+...

source/includes/ref-toc-operator-query-bitwise.yaml

@@ -0,0 +1,16 @@
+name: ":query:`$bitsAllSet`"
+file: /reference/operator/query/bitsAllSet
+description: "Matches numeric or binary values in which a set of bit positions *all* have a value of ``1``."
+---
+name: ":query:`$bitsAnySet`"
+file: /reference/operator/query/bitsAnySet
+description: "Matches numeric or binary values in which *any* bit from a set of bit positions has a value of ``1``."
+---
+name: ":query:`$bitsAllClear`"
+file: /reference/operator/query/bitsAllClear
+description: "Matches numeric or binary values in which a set of bit positions *all* have a value of ``0``."
+---
+name: ":query:`$bitsAnyClear`"
+file: /reference/operator/query/bitsAnyClear
+description: "Matches numeric or binary values in which *any* bit from a set of bit positions has a value of ``0``."
+...

source/reference/operator/query-bitwise.txt

@@ -0,0 +1,9 @@
+=======================
+Bitwise Query Operators
+=======================
+
+.. default-domain:: mongodb
+
+.. include:: /includes/toc/table-operator-query-bitwise.rst
+
+.. include:: /includes/toc/operator-query-bitwise.rst

source/reference/operator/query.txt

@@ -94,6 +94,20 @@ Array
 
       /reference/operator/query-array
 
+Bitwise
+~~~~~~~
+
+.. only:: website
+
+   .. include:: /includes/toc/table-operator-query-bitwise.rst
+
+.. class:: hidden
+
+   .. toctree::
+      :titlesonly:
+
+      /reference/operator/query-bitwise
+
 Comments
 ~~~~~~~~
 

source/reference/operator/query/bitsAllClear.txt

@@ -0,0 +1,87 @@
+=============
+$bitsAllClear
+=============
+
+.. default-domain:: mongodb
+
+.. query:: $bitsAllClear
+
+   .. versionadded:: 3.2
+
+   :query:`$bitsAllClear` matches documents where *all* of the bit positions
+   given by the query are clear (i.e. ``0``) in ``field``.
+
+   .. include:: /includes/extracts/fact-query-bitsallclear-description.rst
+
+Behavior
+--------
+
+Floating Point Values
+~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/extracts/fact-query-bitsallclear-floating-point.rst
+
+Sign Extension
+~~~~~~~~~~~~~~
+
+.. include:: /includes/extracts/fact-query-bitsallset-sign-extension.rst
+
+Examples
+--------
+
+.. include:: /includes/extracts/fact-query-bitwise-example-collection.rst
+
+Bit Position Array
+~~~~~~~~~~~~~~~~~~
+
+The following query uses the :query:`$bitsAllClear` operator to test
+whether field ``a`` has bits clear at position ``1`` and position
+``5``, where the least significant bit is position ``0``.
+
+.. code-block:: javascript
+
+   db.collection.find( { a: { $bitsAllClear: [ 1, 5 ] } } )
+
+The query matches the following documents:
+
+.. code-block:: javascript
+
+   { "_id" : 2, "a" : 20, "binaryValueofA" : "00010100" }
+   { "_id" : 3, "a" : 20, "binaryValueofA" : "00010100" }
+
+
+Integer Bitmask
+~~~~~~~~~~~~~~~
+
+The following query uses the :query:`$bitsAllClear` operator to test
+whether field ``a`` has bits clear at positions ``0``, ``1``, and ``5``,
+because the binary representation of the bitmask ``35`` is ``00100011``.
+
+.. code-block:: javascript
+
+   db.collection.find( { a: { $bitsAllClear: 35 } } )
+
+The query matches the following documents:
+
+.. code-block:: javascript
+
+   { "_id" : 2, "a" : 20, "binaryValueofA" : "00010100" }
+   { "_id" : 3, "a" : 20, "binaryValueofA" : "00010100" }
+
+BinData Bitmask
+~~~~~~~~~~~~~~~
+
+The following query uses the :query:`$bitsAllClear` operator to test
+whether field ``a`` has bits clear at positions `1`, `4`, and `5`, because the
+binary representation of ``BinData(0, "MC==")`` is ``00110010``.
+
+.. code-block:: javascript
+
+   db.collection.find( { a: { $bitsAllClear: BinData(0, "ID==") } } )
+
+The query matches the following documents:
+
+.. code-block:: javascript
+
+   { "_id" : 2, "a" : 20, "binaryValueofA" : "00010100" }
+   { "_id" : 3, "a" : 20, "binaryValueofA" : "00010100" }