# Bit functions

> 13 Bit functions in NYXDB: names, aliases, signatures and behaviour.

{/* AUTO-GENERATED from the function catalog. DO NOT EDIT — overwritten on every build. */}

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.

| Function | Summary |
| --- | --- |
| [`bit_and`](#bit_and) | Retains only the set positions shared by two equal-width integers. |
| [`bit_count`](#bit_count) | Counts enabled digits across an integer’s complete two’s-complement representation. |
| [`bit_hamming_distance`](#bit_hamming_distance) | Measures the number of unequal bit positions between compatible integers. |
| [`bit_not`](#bit_not) | Flips every binary digit within the input integer’s declared width. |
| [`bit_or`](#bit_or) | Combines enabled binary positions from either integer operand. |
| [`bit_rotate_left`](#bit_rotate_left) | Circulates an integer’s high-order digits back into its low-order positions. |
| [`bit_rotate_right`](#bit_rotate_right) | Cycles low-order bits upward by a width-modulo rotation count. |
| [`bit_shift_left`](#bit_shift_left) | Moves an integer’s representation toward higher positions and fills with zeros. |
| [`bit_shift_right`](#bit_shift_right) | Moves binary digits downward, extending signed inputs from their sign bit. |
| [`bit_test`](#bit_test) | Reports whether one zero-based binary position is enabled in an integer. |
| [`bit_test_all`](#bit_test_all) | Checks that every requested integer bit is set. |
| [`bit_test_any`](#bit_test_any) | Finds whether at least one selected binary location contains a one. |
| [`bit_xor`](#bit_xor) | Marks binary positions where two integer representations disagree. |

## bit_and

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

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

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/binary` |
| Returns | `I` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | Any NULL argument gives NULL. |

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**

```sql
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.

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

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/unary` |
| Returns | `uint8 for widths <=128; uint16 for width 256` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | Any NULL argument gives NULL. |

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**

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

## bit_hamming_distance

Measures the number of unequal bit positions between compatible integers.

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

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/binary` |
| Returns | `uint16` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | Any NULL argument gives NULL. |

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**

```sql
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.

```text
bit_not(x:I) -> I
```

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/unary` |
| Returns | `I` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | Any NULL argument gives NULL. |

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**

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

## bit_or

Combines enabled binary positions from either integer operand.

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

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/binary` |
| Returns | `I` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | Any NULL argument gives NULL. |

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**

```sql
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.

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

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/binary` |
| Returns | `I` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | Any NULL argument gives NULL. |

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**

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

## bit_rotate_right

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

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

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/binary` |
| Returns | `I` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | Any NULL argument gives NULL. |

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**

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

## bit_shift_left

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

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

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/binary` |
| Returns | `I` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | Any NULL argument gives NULL. |

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**

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

## bit_shift_right

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

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

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/binary` |
| Returns | `I` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | Any NULL argument gives NULL. |

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**

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

## bit_test

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

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

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/binary` |
| Returns | `bool` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | Any NULL argument gives NULL. |

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**

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

## bit_test_all

Checks that every requested integer bit is set.

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

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/variadic` |
| Returns | `bool` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | Any NULL argument gives NULL. |

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**

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

## bit_test_any

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

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

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/variadic` |
| Returns | `bool` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | Any NULL argument gives NULL. |

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**

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

## bit_xor

Marks binary positions where two integer representations disagree.

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

| | |
| --- | --- |
| Kind | scalar |
| Signature class | `scalar/binary` |
| Returns | `I` |
| Streaming | Continuous — evaluated per row with no retained state. |
| Determinism | Deterministic — the same arguments always give the same result. |
| NULL handling | Any NULL argument gives NULL. |

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**

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

---

Source: https://nyxdb.io/docs/functions/bit/