$bitsAllClear
-
$bitsAllClear
-
New in version 3.2.
$bitsAllClear
matches documents where all of the bit positions given by the query are clear (i.e.0
) infield
.{ <field>: { $bitsAllClear: <numeric bitmask> } }
{ <field>: { $bitsAllClear: <
BinData
bitmask> } }
{ <field>: { $bitsAllClear: [ <position1>, <position2>, ... ] } }
The
field
value must be either numerical or aBinData
instance. Otherwise,$bitsAllClear
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,
$bitsAllClear
will return an error. - BinData Bitmask
-
You can also use an arbitrarily large
BinData
instance as a bitmask. - Position List
-
If querying a list of bit positions, each
<position>
must be a non-negative integer. Bit positions start at0
from the least significant bit. For example, the decimal number254
would have the following bit positions:
Bit Value 1 1 1 1 1 1 1 0 Position 7 6 5 4 3 2 1 0
Behavior
Indexes
Queries cannot use indexes for the $bitsAllClear
portion of a query, although the other portions of a query can use indexes, if applicable.
Floating Point Values
$bitsAllClear
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 too small to fit in a signed 64-bit integer, or if it has a fractional component.
Sign Extension
Numbers are sign extended. For example, $bitsAllClear
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, BinData
instances are zero-extended. For example, given the following document:
$bitsAllClear
will consider all bits outside of x
to be clear.
Examples
The following examples will use a collection with the following documents:
Bit Position Array
The following query uses the $bitsAllClear
operator to test whether field a
has bits clear at position 1
and position 5
, where the least significant bit is position 0
.
The query matches the following documents:
Integer Bitmask
The following query uses the $bitsAllClear
operator to test whether field a
has bits clear at positions 0
, 1
, and 5
(the binary representation of the bitmask 35
is 00100011
).
The query matches the following documents:
BinData Bitmask
The following query uses the $bitsAllClear
operator to test whether field a
has bits clear at positions 2 and 4 (the binary representation of BinData(0, "ID==")
is 00010100
.
The query matches the following documents: