Bit functions

13 functions. Names resolve case-insensitively; an alias binds the same function as its canonical name. Each entry gives the signatures, the behaviour and an example.

bit_and

Retains only the set positions shared by two equal-width integers.

bit_and(a:I,b:I) -> I

Computes a bitwise conjunction in the exact signed or unsigned width of both operands. A NULL operand produces NULL; mixed widths require an explicit cast and otherwise raise TYPE_MISMATCH. Sign bits participate in the operation just like other positions.

Example

bit_and(cast(12 AS UINT8), cast(10 AS UINT8))
-- → 8

bit_count

Counts enabled digits across an integer’s complete two’s-complement representation.

bit_count(x:int8|int16|int32|int64|int128|uint8|uint16|uint32|uint64|uint128) -> uint8
bit_count(x:int256|uint256) -> uint16

Counts one bits, including a signed integer’s sign-extension bits within its declared width. NULL produces NULL and noninteger inputs raise TYPE_MISMATCH. The result is uint8 through 128-bit inputs and uint16 for 256-bit inputs so that a population of 256 remains representable.

Example

bit_count(cast(15 AS UINT8))
-- → 4

bit_hamming_distance

Measures the number of unequal bit positions between compatible integers.

bit_hamming_distance(a:I,b:I) -> uint16

Returns the population count of the bitwise difference between operands as uint16. Arguments with distinct integer widths or signedness raise TYPE_MISMATCH, and either NULL propagates. The comparison covers all declared bits, including 256-bit values and signed representation bits.

Example

bit_hamming_distance(cast(7 AS UINT8), cast(11 AS UINT8))
-- → 2

bit_not

Flips every binary digit within the input integer’s declared width.

bit_not(x:I) -> I

Complements the complete fixed-width two’s-complement representation and retains its signedness. NULL remains NULL, while a noninteger argument raises TYPE_MISMATCH. The width matters: complementing uint8 zero gives 255 rather than an unbounded negative value.

Example

bit_not(cast(0 AS UINT8))
-- → 255

bit_or

Combines enabled binary positions from either integer operand.

bit_or(a:I,b:I) -> I

Takes the inclusive disjunction of corresponding bits without changing the integer descriptor. NULL propagates from either argument, and incompatible signedness or widths raise TYPE_MISMATCH. Bits present in both operands are retained once rather than added arithmetically.

Example

bit_or(cast(12 AS UINT8), cast(10 AS UINT8))
-- → 14

bit_rotate_left

Circulates an integer’s high-order digits back into its low-order positions.

bit_rotate_left(x:I,n:uint64) -> I

Rotates the complete fixed-width representation left rather than discarding outgoing bits. The count is reduced modulo that width, so a full-width rotation returns the original value. NULL yields NULL and an invalid unsigned rotation count raises INVALID_ARGUMENT; signed inputs retain their descriptor.

Example

bit_rotate_left(cast(129 AS UINT8), 1)
-- → 3

bit_rotate_right

Cycles low-order bits upward by a width-modulo rotation count.

bit_rotate_right(x:I,n:uint64) -> I

The rightward rotation wraps every outgoing bit into the opposite end of the same integer width. NULL arguments propagate, and a negative count cannot bind to uint64 and raises INVALID_ARGUMENT. Rotation by a multiple of the width is an identity even when the signed input is negative.

Example

bit_rotate_right(cast(3 AS UINT8), 1)
-- → 129

bit_shift_left

Moves an integer’s representation toward higher positions and fills with zeros.

bit_shift_left(x:I,n:uint64) -> I

Shifts left within the original integer width, discarding bits that cross the high boundary. NULL in either argument yields NULL; a negative or otherwise invalid shift count raises INVALID_ARGUMENT. Counts at least as large as the width return typed zero, with no widening to preserve discarded bits.

Example

bit_shift_left(cast(3 AS UINT8), 2)
-- → 12

bit_shift_right

Moves binary digits downward, extending signed inputs from their sign bit.

bit_shift_right(x:I,n:uint64) -> I

An unsigned operand receives zero fill, whereas a signed operand receives sign extension for shifts smaller than its width. A count at least equal to the width gives zero for either signedness; NULL propagates and an invalid count raises INVALID_ARGUMENT. The output keeps the exact input integer type.

Example

bit_shift_right(cast(12 AS UINT8), 2)
-- → 3

bit_test

Reports whether one zero-based binary position is enabled in an integer.

bit_test(x:I,n:uint64) -> bool

Examines the requested position with zero denoting the least significant bit. A NULL integer or position returns NULL; a position outside the declared width raises INVALID_ARGUMENT. The result is Boolean rather than a shifted integer mask.

Example

bit_test(cast(10 AS UINT8), 1)
-- → true

bit_test_all

Checks that every requested integer bit is set.

bit_test_all(x:I,positions:uint64...) -> bool

Returns true only when every supplied zero-based position is set in the integer representation. NULL input or a NULL position yields NULL, and any out-of-width position raises INVALID_ARGUMENT. Repeated positions do not change the result; an empty position list is vacuously true.

Example

bit_test_all(cast(10 AS UINT8), 1, 3)
-- → true

bit_test_any

Finds whether at least one selected binary location contains a one.

bit_test_any(x:I,positions:uint64...) -> bool

Tests a variadic set of positions and succeeds when at least one examined bit is present. An empty position list returns false, while any NULL argument returns NULL. Every position must fit the integer width, including when an earlier position matched, or INVALID_ARGUMENT is raised.

Example

bit_test_any(cast(10 AS UINT8), 0, 2)
-- → false

bit_xor

Marks binary positions where two integer representations disagree.

bit_xor(a:I,b:I) -> I

Exclusive disjunction sets a result bit exactly when one operand has that bit set. Both arguments must share one exact integer type or binding raises TYPE_MISMATCH; a NULL argument yields NULL. Applying the operation to an integer and itself produces typed zero.

Example

bit_xor(cast(12 AS UINT8), cast(10 AS UINT8))
-- → 6