- Reference >
- Operators >
- Query and Projection Operators >
- Bitwise Query Operators >
- $bitsAllClear
$bitsAllClear¶
- $bitsAllClear¶
3.2 新版功能.
$bitsAllClear matches documents where all of the bit positions given by the query are clear (i.e. 0) in field.
{ <field>: { $bitsAllClear: <numeric bitmask> } } { <field>: { $bitsAllClear: < BinData bitmask> } } { <field>: { $bitsAllClear: [ <position1>, <position2>, ... ] } } The field value must be either numerical or a BinData 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 at 0 from the least significant bit. For example, the decimal number 254 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¶
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 small to fit in a signed 64-bit integer, or if it has a fractional component.
Sign Extension¶
Numbers are sign extended. For example, $bitsAllSet 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:
db.collection.save({ x: BinData(0, "ww=="), binaryValueofA: "11000011" })
$bitsAllSet will consider all bits outside of x to be clear.
Examples¶
The following examples will use a collection with the following documents:
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" })
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.
db.collection.find( { a: { $bitsAllClear: [ 1, 5 ] } } )
The query matches the following documents:
{ "_id" : 2, "a" : 20, "binaryValueofA" : "00010100" }
{ "_id" : 3, "a" : 20, "binaryValueofA" : "00010100" }
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).
db.collection.find( { a: { $bitsAllClear: 35 } } )
The query matches the following documents:
{ "_id" : 2, "a" : 20, "binaryValueofA" : "00010100" }
{ "_id" : 3, "a" : 20, "binaryValueofA" : "00010100" }
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.
db.collection.find( { a: { $bitsAllClear: BinData(0, "ID==") } } )
The query matches the following documents:
{ "_id" : 2, "a" : 20, "binaryValueofA" : "00010100" }
{ "_id" : 3, "a" : 20, "binaryValueofA" : "00010100" }