$bitsAllSet

  • $bitsAllSet

New in version 3.2.

$bitsAllSet matches documents where all of the bit positionsgiven by the query are set (i.e. 1) in field.

{ <field>: { $bitsAllSet: <numeric bitmask> } }{ <field>: { $bitsAllSet: < BinData bitmask> } }{ <field>: { $bitsAllSet: [ <position1>, <position2>, … ] } }

The field value must be either numeric or aBinData instance. Otherwise, $bitsAllSetwill 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,$bitsAllSet will return an error.
  • BinData Bitmask
  • You can also use an arbitrarily large BinDatainstance as a bitmask.
  • Position List
  • If querying a list of bit positions, each <position> must be a non-negativeinteger. Bit positions start at 0 from the least significant bit. Forexample, the decimal number 254 would have the following bit positions:

Bit Value11111110Position76543210

Behavior

Indexes

Queries cannot use indexes for the $bitsAllSet portion of aquery, although the other portions of a query can use indexes, ifapplicable.

Floating Point Values

$bitsAllSet will not match numerical values that cannot be represented asa signed 64-bit integer. This can be the case if a value is either too largeor too small to fit in a signed 64-bit integer, or if it has a fractionalcomponent.

Sign Extension

Numbers are sign extended. For example, $bitsAllSet considers bit position 200to be set for the negative number -5, but bit position 200 to be clearfor the positive number +5.

In contrast, BinData instances are zero-extended.For example, given the following document:

  1. 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:

  1. db.collection.save({ _id: 1, a: 54, binaryValueofA: "00110110" })
  2. db.collection.save({ _id: 2, a: 20, binaryValueofA: "00010100" })
  3. db.collection.save({ _id: 3, a: 20.0, binaryValueofA: "00010100" })
  4. db.collection.save({ _id: 4, a: BinData(0, "Zg=="), binaryValueofA: "01100110" })

Bit Position Array

The following query uses the $bitsAllSet operator to testwhether field a has bits set at position 1 and position5, where the least significant bit is position 0.

  1. db.collection.find( { a: { $bitsAllSet: [ 1, 5 ] } } )

The query matches the following documents:

  1. { "_id" : 1, "a" : 54, "binaryValueofA" : "00110110" }
  2. { "_id" : 4, "a" : BinData(0,"Zg=="), "binaryValueofA" : "01100110" }

Integer Bitmask

The following query uses the $bitsAllSet operator to testwhether field a has bits set at positions 1, 4, and 5(the binary representation of the bitmask 50 is 00110010).

  1. db.collection.find( { a: { $bitsAllSet: 50 } } )

The query matches the following document:

  1. { "_id" : 1, "a" : 54, "binaryValueofA" : "00110110" }

BinData Bitmask

The following query uses the $bitsAllSet operator to testwhether field a has bits set at positions 4 and 5(the binary representation of BinData(0, "MC==") is 00110000).

  1. db.collection.find( { a: { $bitsAllSet: BinData(0, "MC==") } } )

The query matches the following document:

  1. { _id: 1, a: 54, binaryValueofA: "00110110" }