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

bitops

Imports

Types

Procs

Macros