# bitops

Dark Mode

- Manual
- Standard library
- Index
- devel, stable

Search:
Group by:

This module implements a series of low level methods for bit manipulation.

By default, this module use compiler intrinsics where possible to improve performance on supported compilers: `GCC`, `LLVM_GCC`, `CLANG`, `VCC`, `ICC`.

The module will fallback to pure nim procs incase the backend is not supported. You can also use the flag `noIntrinsicsBitOpts` to disable compiler intrinsics.

This module is also compatible with other backends: `Javascript`, `Nimscript` as well as the `compiletime VM`.

As a result of using optimized function/intrinsics some functions can return undefined results if the input is invalid. You can use the flag `noUndefinedBitOpts` to force predictable behaviour for all input, causing a small performance hit.

At this time only `fastLog2`, `firstSetBit, `countLeadingZeroBits`, `countTrailingZeroBits` may return undefined and/or platform dependent value if given invalid input.

# Imports

macros

# Types

    BitsRange[T] = range[0 .. sizeof(T) * 8 - 1]

  Returns a range with all bit positions for type `T` Source Edit

# Procs

    proc bitnot[T: SomeInteger](x: T): T {...}{.magic: "BitnotI", noSideEffect.}

  Computes the `bitwise complement` of the integer `x`. Source Edit

    proc bitand[T: SomeInteger](x, y: T): T {...}{.magic: "BitandI", noSideEffect.}

  Computes the `bitwise and` of numbers `x` and `y`. Source Edit

    proc bitor[T: SomeInteger](x, y: T): T {...}{.magic: "BitorI", noSideEffect.}

  Computes the `bitwise or` of numbers `x` and `y`. Source Edit

    proc bitxor[T: SomeInteger](x, y: T): T {...}{.magic: "BitxorI", noSideEffect.}

  Computes the `bitwise xor` of numbers `x` and `y`. Source Edit

    proc setMask[T: SomeInteger](v: var T; mask: T) {...}{.inline.}

  Returns `v`, with all the `1` bits from `mask` set to 1 Source Edit

    proc clearMask[T: SomeInteger](v: var T; mask: T) {...}{.inline.}

  Returns `v`, with all the `1` bits from `mask` set to 0 Source Edit

    proc flipMask[T: SomeInteger](v: var T; mask: T) {...}{.inline.}

  Returns `v`, with all the `1` bits from `mask` flipped Source Edit

    proc setBit[T: SomeInteger](v: var T; bit: BitsRange[T]) {...}{.inline.}

  Returns `v`, with the bit at position `bit` set to 1 Source Edit

    proc clearBit[T: SomeInteger](v: var T; bit: BitsRange[T]) {...}{.inline.}

  Returns `v`, with the bit at position `bit` set to 0 Source Edit

    proc flipBit[T: SomeInteger](v: var T; bit: BitsRange[T]) {...}{.inline.}

  Returns `v`, with the bit at position `bit` flipped Source Edit

    proc testBit[T: SomeInteger](v: T; bit: BitsRange[T]): bool {...}{.inline.}

  Returns true if the bit in `v` at positions `bit` is set to 1 Source Edit

    proc countSetBits(x: SomeInteger): int {...}{.inline, noSideEffect.}

  Counts the set bits in integer. (also called Hamming weight.) Source Edit

    proc popcount(x: SomeInteger): int {...}{.inline, noSideEffect.}

  Alias for for countSetBits (Hamming weight.) Source Edit

    proc parityBits(x: SomeInteger): int {...}{.inline, noSideEffect.}

  Calculate the bit parity in integer. If number of 1-bit is odd parity is 1, otherwise 0. Source Edit

    proc firstSetBit(x: SomeInteger): int {...}{.inline, noSideEffect.}

  Returns the 1-based index of the least significant set bit of x. If `x` is zero, when `noUndefinedBitOpts` is set, result is 0, otherwise result is undefined. Source Edit

    proc fastLog2(x: SomeInteger): int {...}{.inline, noSideEffect.}

  Quickly find the log base 2 of an integer. If `x` is zero, when `noUndefinedBitOpts` is set, result is -1, otherwise result is undefined. Source Edit

    proc countLeadingZeroBits(x: SomeInteger): int {...}{.inline, noSideEffect.}

  Returns the number of leading zero bits in integer. If `x` is zero, when `noUndefinedBitOpts` is set, result is 0, otherwise result is undefined. Source Edit

    proc countTrailingZeroBits(x: SomeInteger): int {...}{.inline, noSideEffect.}

  Returns the number of trailing zeros in integer. If `x` is zero, when `noUndefinedBitOpts` is set, result is 0, otherwise result is undefined. Source Edit

    proc rotateLeftBits(value: uint8; amount: range[0 .. 8]): uint8 {...}{.inline,
        noSideEffect, raises: [], tags: [].}

  Left-rotate bits in a 8-bits value. Source Edit

    proc rotateLeftBits(value: uint16; amount: range[0 .. 16]): uint16 {...}{.inline,
        noSideEffect, raises: [], tags: [].}

  Left-rotate bits in a 16-bits value. Source Edit

    proc rotateLeftBits(value: uint32; amount: range[0 .. 32]): uint32 {...}{.inline,
        noSideEffect, raises: [], tags: [].}

  Left-rotate bits in a 32-bits value. Source Edit

    proc rotateLeftBits(value: uint64; amount: range[0 .. 64]): uint64 {...}{.inline,
        noSideEffect, raises: [], tags: [].}

  Left-rotate bits in a 64-bits value. Source Edit

    proc rotateRightBits(value: uint8; amount: range[0 .. 8]): uint8 {...}{.inline,
        noSideEffect, raises: [], tags: [].}

  Right-rotate bits in a 8-bits value. Source Edit

    proc rotateRightBits(value: uint16; amount: range[0 .. 16]): uint16 {...}{.inline,
        noSideEffect, raises: [], tags: [].}

  Right-rotate bits in a 16-bits value. Source Edit

    proc rotateRightBits(value: uint32; amount: range[0 .. 32]): uint32 {...}{.inline,
        noSideEffect, raises: [], tags: [].}

  Right-rotate bits in a 32-bits value. Source Edit

    proc rotateRightBits(value: uint64; amount: range[0 .. 64]): uint64 {...}{.inline,
        noSideEffect, raises: [], tags: [].}

  Right-rotate bits in a 64-bits value. Source Edit

    proc reverseBits[T: SomeUnsignedInt](x: T): T {...}{.noSideEffect.}

  Return the bit reversal of x.

  Examples:

      doAssert reverseBits(0b10100100'u8) == 0b00100101'u8
      doAssert reverseBits(0xDD'u8) == 0xBB'u8
      doAssert reverseBits(0xDDBB'u16) == 0xDDBB'u16
      doAssert reverseBits(0xDEADBEEF'u32) == 0xF77DB57B'u32

  Source Edit

# Macros

    macro setBits(v: typed; bits: varargs[typed]): untyped

  Returns `v`, with the bits at positions `bits` set to 1 Source Edit

    macro clearBits(v: typed; bits: varargs[typed]): untyped

  Returns `v`, with the bits at positions `bits` set to 0 Source Edit

    macro flipBits(v: typed; bits: varargs[typed]): untyped

  Returns `v`, with the bits at positions `bits` set to 0 Source Edit