Module bitops

This module implements a series of low level methods for bit manipulation. By default, this module use compiler intrinsics 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 dependant value if given invalid input.

Procs

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

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

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

Alias for for countSetBits (Hamming weight.)

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.

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.

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.

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.

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.

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

Left-rotate bits in a 8-bits value.

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

Left-rotate bits in a 16-bits value.

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

Left-rotate bits in a 32-bits value.

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

Left-rotate bits in a 64-bits value.

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

Right-rotate bits in a 8-bits value.

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

Right-rotate bits in a 16-bits value.

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

Right-rotate bits in a 32-bits value.

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

Right-rotate bits in a 64-bits value.