Improve documentation for bitops (#16961)
* Improve documentation for bitops Use func Use let in runnableExamples * Remove unnecessary tests Fix #7587
This commit is contained in:
konsumlamm
GitHub
parent
a03ec067da
commit
0a9a90d991
2 changed files with 296 additions and 456 deletions
|
|
@ -8,27 +8,27 @@
|
|||
#
|
||||
|
||||
## 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.
|
||||
## By default, compiler intrinsics are used where possible to improve performance
|
||||
## on supported compilers: `GCC`, `LLVM_GCC`, `CLANG`, `VCC`, `ICC`.
|
||||
##
|
||||
## The module will fallback to pure nim procs in case 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``.
|
||||
## 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
|
||||
## As a result of using optimized functions/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.
|
||||
## At this time only `fastLog2`, `firstSetBit`, `countLeadingZeroBits` and `countTrailingZeroBits`
|
||||
## may return undefined and/or platform dependent values if given invalid input.
|
||||
|
||||
import macros
|
||||
import std/private/since
|
||||
|
||||
proc bitnot*[T: SomeInteger](x: T): T {.magic: "BitnotI", noSideEffect.}
|
||||
func bitnot*[T: SomeInteger](x: T): T {.magic: "BitnotI".}
|
||||
## Computes the `bitwise complement` of the integer `x`.
|
||||
|
||||
func internalBitand[T: SomeInteger](x, y: T): T {.magic: "BitandI".}
|
||||
|
|
@ -89,10 +89,10 @@ template forwardImpl(impl, arg) {.dirty.} =
|
|||
|
||||
when defined(nimHasalignOf):
|
||||
type BitsRange*[T] = range[0..sizeof(T)*8-1]
|
||||
## A range with all bit positions for type ``T``
|
||||
## A range with all bit positions for type `T`.
|
||||
|
||||
func bitsliced*[T: SomeInteger](v: T; slice: Slice[int]): T {.inline, since: (1, 3).} =
|
||||
## Returns an extracted (and shifted) slice of bits from ``v``.
|
||||
## Returns an extracted (and shifted) slice of bits from `v`.
|
||||
runnableExamples:
|
||||
doAssert 0b10111.bitsliced(2 .. 4) == 0b101
|
||||
doAssert 0b11100.bitsliced(0 .. 2) == 0b100
|
||||
|
|
@ -104,7 +104,7 @@ when defined(nimHasalignOf):
|
|||
(uv shl (upmost - slice.b) shr (upmost - slice.b + slice.a)).T
|
||||
|
||||
proc bitslice*[T: SomeInteger](v: var T; slice: Slice[int]) {.inline, since: (1, 3).} =
|
||||
## Mutates ``v`` into an extracted (and shifted) slice of bits from ``v``.
|
||||
## Mutates `v` into an extracted (and shifted) slice of bits from `v`.
|
||||
runnableExamples:
|
||||
var x = 0b101110
|
||||
x.bitslice(2 .. 4)
|
||||
|
|
@ -130,32 +130,32 @@ when defined(nimHasalignOf):
|
|||
(bitmask shl (upmost - slice.b + slice.a) shr (upmost - slice.b)).T
|
||||
|
||||
proc masked*[T: SomeInteger](v, mask :T): T {.inline, since: (1, 3).} =
|
||||
## Returns ``v``, with only the ``1`` bits from ``mask`` matching those of
|
||||
## ``v`` set to 1.
|
||||
## Returns `v`, with only the `1` bits from `mask` matching those of
|
||||
## `v` set to 1.
|
||||
##
|
||||
## Effectively maps to a `bitand` operation.
|
||||
## Effectively maps to a `bitand <#bitand.m,T,T,varargs[T]>`_ operation.
|
||||
runnableExamples:
|
||||
var v = 0b0000_0011'u8
|
||||
let v = 0b0000_0011'u8
|
||||
doAssert v.masked(0b0000_1010'u8) == 0b0000_0010'u8
|
||||
|
||||
bitand(v, mask)
|
||||
|
||||
func masked*[T: SomeInteger](v: T; slice: Slice[int]): T {.inline, since: (1, 3).} =
|
||||
## Mutates ``v``, with only the ``1`` bits in the range of ``slice``
|
||||
## matching those of ``v`` set to 1.
|
||||
## Returns `v`, with only the `1` bits in the range of `slice`
|
||||
## matching those of `v` set to 1.
|
||||
##
|
||||
## Effectively maps to a `bitand` operation.
|
||||
## Effectively maps to a `bitand <#bitand.m,T,T,varargs[T]>`_ operation.
|
||||
runnableExamples:
|
||||
var v = 0b0000_1011'u8
|
||||
let v = 0b0000_1011'u8
|
||||
doAssert v.masked(1 .. 3) == 0b0000_1010'u8
|
||||
|
||||
bitand(v, toMask[T](slice))
|
||||
|
||||
proc mask*[T: SomeInteger](v: var T; mask: T) {.inline, since: (1, 3).} =
|
||||
## Mutates ``v``, with only the ``1`` bits from ``mask`` matching those of
|
||||
## ``v`` set to 1.
|
||||
## Mutates `v`, with only the `1` bits from `mask` matching those of
|
||||
## `v` set to 1.
|
||||
##
|
||||
## Effectively maps to a `bitand` operation.
|
||||
## Effectively maps to a `bitand <#bitand.m,T,T,varargs[T]>`_ operation.
|
||||
runnableExamples:
|
||||
var v = 0b0000_0011'u8
|
||||
v.mask(0b0000_1010'u8)
|
||||
|
|
@ -164,10 +164,10 @@ when defined(nimHasalignOf):
|
|||
v = bitand(v, mask)
|
||||
|
||||
proc mask*[T: SomeInteger](v: var T; slice: Slice[int]) {.inline, since: (1, 3).} =
|
||||
## Mutates ``v``, with only the ``1`` bits in the range of ``slice``
|
||||
## matching those of ``v`` set to 1.
|
||||
## Mutates `v`, with only the `1` bits in the range of `slice`
|
||||
## matching those of `v` set to 1.
|
||||
##
|
||||
## Effectively maps to a `bitand` operation.
|
||||
## Effectively maps to a `bitand <#bitand.m,T,T,varargs[T]>`_ operation.
|
||||
runnableExamples:
|
||||
var v = 0b0000_1011'u8
|
||||
v.mask(1 .. 3)
|
||||
|
|
@ -176,29 +176,29 @@ when defined(nimHasalignOf):
|
|||
v = bitand(v, toMask[T](slice))
|
||||
|
||||
func setMasked*[T: SomeInteger](v, mask :T): T {.inline, since: (1, 3).} =
|
||||
## Returns ``v``, with all the ``1`` bits from ``mask`` set to 1.
|
||||
## Returns `v`, with all the `1` bits from `mask` set to 1.
|
||||
##
|
||||
## Effectively maps to a `bitor` operation.
|
||||
## Effectively maps to a `bitor <#bitor.m,T,T,varargs[T]>`_ operation.
|
||||
runnableExamples:
|
||||
var v = 0b0000_0011'u8
|
||||
let v = 0b0000_0011'u8
|
||||
doAssert v.setMasked(0b0000_1010'u8) == 0b0000_1011'u8
|
||||
|
||||
bitor(v, mask)
|
||||
|
||||
func setMasked*[T: SomeInteger](v: T; slice: Slice[int]): T {.inline, since: (1, 3).} =
|
||||
## Returns ``v``, with all the ``1`` bits in the range of ``slice`` set to 1.
|
||||
## Returns `v`, with all the `1` bits in the range of `slice` set to 1.
|
||||
##
|
||||
## Effectively maps to a `bitor` operation.
|
||||
## Effectively maps to a `bitor <#bitor.m,T,T,varargs[T]>`_ operation.
|
||||
runnableExamples:
|
||||
var v = 0b0000_0011'u8
|
||||
let v = 0b0000_0011'u8
|
||||
doAssert v.setMasked(2 .. 3) == 0b0000_1111'u8
|
||||
|
||||
bitor(v, toMask[T](slice))
|
||||
|
||||
proc setMask*[T: SomeInteger](v: var T; mask: T) {.inline.} =
|
||||
## Mutates ``v``, with all the ``1`` bits from ``mask`` set to 1.
|
||||
## Mutates `v`, with all the `1` bits from `mask` set to 1.
|
||||
##
|
||||
## Effectively maps to a `bitor` operation.
|
||||
## Effectively maps to a `bitor <#bitor.m,T,T,varargs[T]>`_ operation.
|
||||
runnableExamples:
|
||||
var v = 0b0000_0011'u8
|
||||
v.setMask(0b0000_1010'u8)
|
||||
|
|
@ -207,9 +207,9 @@ when defined(nimHasalignOf):
|
|||
v = bitor(v, mask)
|
||||
|
||||
proc setMask*[T: SomeInteger](v: var T; slice: Slice[int]) {.inline, since: (1, 3).} =
|
||||
## Mutates ``v``, with all the ``1`` bits in the range of ``slice`` set to 1.
|
||||
## Mutates `v`, with all the `1` bits in the range of `slice` set to 1.
|
||||
##
|
||||
## Effectively maps to a `bitor` operation.
|
||||
## Effectively maps to a `bitor <#bitor.m,T,T,varargs[T]>`_ operation.
|
||||
runnableExamples:
|
||||
var v = 0b0000_0011'u8
|
||||
v.setMask(2 .. 3)
|
||||
|
|
@ -218,29 +218,32 @@ when defined(nimHasalignOf):
|
|||
v = bitor(v, toMask[T](slice))
|
||||
|
||||
func clearMasked*[T: SomeInteger](v, mask :T): T {.inline, since: (1, 3).} =
|
||||
## Returns ``v``, with all the ``1`` bits from ``mask`` set to 0.
|
||||
## Returns `v`, with all the `1` bits from `mask` set to 0.
|
||||
##
|
||||
## Effectively maps to a `bitand` operation with an *inverted mask.*
|
||||
## Effectively maps to a `bitand <#bitand.m,T,T,varargs[T]>`_ operation
|
||||
## with an *inverted mask*.
|
||||
runnableExamples:
|
||||
var v = 0b0000_0011'u8
|
||||
let v = 0b0000_0011'u8
|
||||
doAssert v.clearMasked(0b0000_1010'u8) == 0b0000_0001'u8
|
||||
|
||||
bitand(v, bitnot(mask))
|
||||
|
||||
func clearMasked*[T: SomeInteger](v: T; slice: Slice[int]): T {.inline, since: (1, 3).} =
|
||||
## Returns ``v``, with all the ``1`` bits in the range of ``slice`` set to 0.
|
||||
## Returns `v`, with all the `1` bits in the range of `slice` set to 0.
|
||||
##
|
||||
## Effectively maps to a `bitand` operation with an *inverted mask.*
|
||||
## Effectively maps to a `bitand <#bitand.m,T,T,varargs[T]>`_ operation
|
||||
## with an *inverted mask*.
|
||||
runnableExamples:
|
||||
var v = 0b0000_0011'u8
|
||||
let v = 0b0000_0011'u8
|
||||
doAssert v.clearMasked(1 .. 3) == 0b0000_0001'u8
|
||||
|
||||
bitand(v, bitnot(toMask[T](slice)))
|
||||
|
||||
proc clearMask*[T: SomeInteger](v: var T; mask: T) {.inline.} =
|
||||
## Mutates ``v``, with all the ``1`` bits from ``mask`` set to 0.
|
||||
## Mutates `v`, with all the `1` bits from `mask` set to 0.
|
||||
##
|
||||
## Effectively maps to a `bitand` operation with an *inverted mask.*
|
||||
## Effectively maps to a `bitand <#bitand.m,T,T,varargs[T]>`_ operation
|
||||
## with an *inverted mask*.
|
||||
runnableExamples:
|
||||
var v = 0b0000_0011'u8
|
||||
v.clearMask(0b0000_1010'u8)
|
||||
|
|
@ -249,9 +252,10 @@ when defined(nimHasalignOf):
|
|||
v = bitand(v, bitnot(mask))
|
||||
|
||||
proc clearMask*[T: SomeInteger](v: var T; slice: Slice[int]) {.inline, since: (1, 3).} =
|
||||
## Mutates ``v``, with all the ``1`` bits in the range of ``slice`` set to 0.
|
||||
## Mutates `v`, with all the `1` bits in the range of `slice` set to 0.
|
||||
##
|
||||
## Effectively maps to a `bitand` operation with an *inverted mask.*
|
||||
## Effectively maps to a `bitand <#bitand.m,T,T,varargs[T]>`_ operation
|
||||
## with an *inverted mask*.
|
||||
runnableExamples:
|
||||
var v = 0b0000_0011'u8
|
||||
v.clearMask(1 .. 3)
|
||||
|
|
@ -260,29 +264,29 @@ when defined(nimHasalignOf):
|
|||
v = bitand(v, bitnot(toMask[T](slice)))
|
||||
|
||||
func flipMasked*[T: SomeInteger](v, mask :T): T {.inline, since: (1, 3).} =
|
||||
## Returns ``v``, with all the ``1`` bits from ``mask`` flipped.
|
||||
## Returns `v`, with all the `1` bits from `mask` flipped.
|
||||
##
|
||||
## Effectively maps to a `bitxor` operation.
|
||||
## Effectively maps to a `bitxor <#bitxor.m,T,T,varargs[T]>`_ operation.
|
||||
runnableExamples:
|
||||
var v = 0b0000_0011'u8
|
||||
let v = 0b0000_0011'u8
|
||||
doAssert v.flipMasked(0b0000_1010'u8) == 0b0000_1001'u8
|
||||
|
||||
bitxor(v, mask)
|
||||
|
||||
func flipMasked*[T: SomeInteger](v: T; slice: Slice[int]): T {.inline, since: (1, 3).} =
|
||||
## Returns ``v``, with all the ``1`` bits in the range of ``slice`` flipped.
|
||||
## Returns `v`, with all the `1` bits in the range of `slice` flipped.
|
||||
##
|
||||
## Effectively maps to a `bitxor` operation.
|
||||
## Effectively maps to a `bitxor <#bitxor.m,T,T,varargs[T]>`_ operation.
|
||||
runnableExamples:
|
||||
var v = 0b0000_0011'u8
|
||||
let v = 0b0000_0011'u8
|
||||
doAssert v.flipMasked(1 .. 3) == 0b0000_1101'u8
|
||||
|
||||
bitxor(v, toMask[T](slice))
|
||||
|
||||
proc flipMask*[T: SomeInteger](v: var T; mask: T) {.inline.} =
|
||||
## Mutates ``v``, with all the ``1`` bits from ``mask`` flipped.
|
||||
## Mutates `v`, with all the `1` bits from `mask` flipped.
|
||||
##
|
||||
## Effectively maps to a `bitxor` operation.
|
||||
## Effectively maps to a `bitxor <#bitxor.m,T,T,varargs[T]>`_ operation.
|
||||
runnableExamples:
|
||||
var v = 0b0000_0011'u8
|
||||
v.flipMask(0b0000_1010'u8)
|
||||
|
|
@ -291,9 +295,9 @@ when defined(nimHasalignOf):
|
|||
v = bitxor(v, mask)
|
||||
|
||||
proc flipMask*[T: SomeInteger](v: var T; slice: Slice[int]) {.inline, since: (1, 3).} =
|
||||
## Mutates ``v``, with all the ``1`` bits in the range of ``slice`` flipped.
|
||||
## Mutates `v`, with all the `1` bits in the range of `slice` flipped.
|
||||
##
|
||||
## Effectively maps to a `bitxor` operation.
|
||||
## Effectively maps to a `bitxor <#bitxor.m,T,T,varargs[T]>`_ operation.
|
||||
runnableExamples:
|
||||
var v = 0b0000_0011'u8
|
||||
v.flipMask(1 .. 3)
|
||||
|
|
@ -302,7 +306,7 @@ when defined(nimHasalignOf):
|
|||
v = bitxor(v, toMask[T](slice))
|
||||
|
||||
proc setBit*[T: SomeInteger](v: var T; bit: BitsRange[T]) {.inline.} =
|
||||
## Mutates ``v``, with the bit at position ``bit`` set to 1
|
||||
## Mutates `v`, with the bit at position `bit` set to 1.
|
||||
runnableExamples:
|
||||
var v = 0b0000_0011'u8
|
||||
v.setBit(5'u8)
|
||||
|
|
@ -311,7 +315,7 @@ when defined(nimHasalignOf):
|
|||
v.setMask(1.T shl bit)
|
||||
|
||||
proc clearBit*[T: SomeInteger](v: var T; bit: BitsRange[T]) {.inline.} =
|
||||
## Mutates ``v``, with the bit at position ``bit`` set to 0
|
||||
## Mutates `v`, with the bit at position `bit` set to 0.
|
||||
runnableExamples:
|
||||
var v = 0b0000_0011'u8
|
||||
v.clearBit(1'u8)
|
||||
|
|
@ -320,7 +324,7 @@ when defined(nimHasalignOf):
|
|||
v.clearMask(1.T shl bit)
|
||||
|
||||
proc flipBit*[T: SomeInteger](v: var T; bit: BitsRange[T]) {.inline.} =
|
||||
## Mutates ``v``, with the bit at position ``bit`` flipped
|
||||
## Mutates `v`, with the bit at position `bit` flipped.
|
||||
runnableExamples:
|
||||
var v = 0b0000_0011'u8
|
||||
v.flipBit(1'u8)
|
||||
|
|
@ -333,7 +337,7 @@ when defined(nimHasalignOf):
|
|||
v.flipMask(1.T shl bit)
|
||||
|
||||
macro setBits*(v: typed; bits: varargs[typed]): untyped =
|
||||
## Mutates ``v``, with the bits at positions ``bits`` set to 1
|
||||
## Mutates `v`, with the bits at positions `bits` set to 1.
|
||||
runnableExamples:
|
||||
var v = 0b0000_0011'u8
|
||||
v.setBits(3, 5, 7)
|
||||
|
|
@ -345,7 +349,7 @@ when defined(nimHasalignOf):
|
|||
result.add newCall("setBit", v, bit)
|
||||
|
||||
macro clearBits*(v: typed; bits: varargs[typed]): untyped =
|
||||
## Mutates ``v``, with the bits at positions ``bits`` set to 0
|
||||
## Mutates `v`, with the bits at positions `bits` set to 0.
|
||||
runnableExamples:
|
||||
var v = 0b1111_1111'u8
|
||||
v.clearBits(1, 3, 5, 7)
|
||||
|
|
@ -357,7 +361,7 @@ when defined(nimHasalignOf):
|
|||
result.add newCall("clearBit", v, bit)
|
||||
|
||||
macro flipBits*(v: typed; bits: varargs[typed]): untyped =
|
||||
## Mutates ``v``, with the bits at positions ``bits`` set to 0
|
||||
## Mutates `v`, with the bits at positions `bits` set to 0.
|
||||
runnableExamples:
|
||||
var v = 0b0000_1111'u8
|
||||
v.flipBits(1, 3, 5, 7)
|
||||
|
|
@ -370,9 +374,9 @@ when defined(nimHasalignOf):
|
|||
|
||||
|
||||
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
|
||||
## Returns true if the bit in `v` at positions `bit` is set to 1.
|
||||
runnableExamples:
|
||||
var v = 0b0000_1111'u8
|
||||
let v = 0b0000_1111'u8
|
||||
doAssert v.testBit(0)
|
||||
doAssert not v.testBit(7)
|
||||
|
||||
|
|
@ -381,19 +385,19 @@ when defined(nimHasalignOf):
|
|||
|
||||
# #### Pure Nim version ####
|
||||
|
||||
proc firstSetBitNim(x: uint32): int {.inline, noSideEffect.} =
|
||||
func firstSetBitNim(x: uint32): int {.inline.} =
|
||||
## Returns the 1-based index of the least significant set bit of x, or if x is zero, returns zero.
|
||||
# https://graphics.stanford.edu/%7Eseander/bithacks.html#ZerosOnRightMultLookup
|
||||
const lookup: array[32, uint8] = [0'u8, 1, 28, 2, 29, 14, 24, 3, 30, 22, 20, 15,
|
||||
25, 17, 4, 8, 31, 27, 13, 23, 21, 19, 16, 7, 26, 12, 18, 6, 11, 5, 10, 9]
|
||||
var v = x.uint32
|
||||
var k = not v + 1 # get two's complement # cast[uint32](-cast[int32](v))
|
||||
let v = x.uint32
|
||||
let k = not v + 1 # get two's complement # cast[uint32](-cast[int32](v))
|
||||
result = 1 + lookup[uint32((v and k) * 0x077CB531'u32) shr 27].int
|
||||
|
||||
proc firstSetBitNim(x: uint64): int {.inline, noSideEffect.} =
|
||||
func firstSetBitNim(x: uint64): int {.inline.} =
|
||||
## Returns the 1-based index of the least significant set bit of x, or if x is zero, returns zero.
|
||||
# https://graphics.stanford.edu/%7Eseander/bithacks.html#ZerosOnRightMultLookup
|
||||
var v = uint64(x)
|
||||
let v = uint64(x)
|
||||
var k = uint32(v and 0xFFFFFFFF'u32)
|
||||
if k == 0:
|
||||
k = uint32(v shr 32'u32) and 0xFFFFFFFF'u32
|
||||
|
|
@ -402,7 +406,7 @@ proc firstSetBitNim(x: uint64): int {.inline, noSideEffect.} =
|
|||
result = 0
|
||||
result += firstSetBitNim(k)
|
||||
|
||||
proc fastlog2Nim(x: uint32): int {.inline, noSideEffect.} =
|
||||
func fastlog2Nim(x: uint32): int {.inline.} =
|
||||
## Quickly find the log base 2 of a 32-bit or less integer.
|
||||
# https://graphics.stanford.edu/%7Eseander/bithacks.html#IntegerLogDeBruijn
|
||||
# https://stackoverflow.com/questions/11376288/fast-computing-of-log2-for-64-bit-integers
|
||||
|
|
@ -416,7 +420,7 @@ proc fastlog2Nim(x: uint32): int {.inline, noSideEffect.} =
|
|||
v = v or v shr 16
|
||||
result = lookup[uint32(v * 0x07C4ACDD'u32) shr 27].int
|
||||
|
||||
proc fastlog2Nim(x: uint64): int {.inline, noSideEffect.} =
|
||||
func fastlog2Nim(x: uint64): int {.inline.} =
|
||||
## Quickly find the log base 2 of a 64-bit integer.
|
||||
# https://graphics.stanford.edu/%7Eseander/bithacks.html#IntegerLogDeBruijn
|
||||
# https://stackoverflow.com/questions/11376288/fast-computing-of-log2-for-64-bit-integers
|
||||
|
|
@ -479,24 +483,24 @@ when useGCC_builtins:
|
|||
|
||||
elif useVCC_builtins:
|
||||
# Counts the number of one bits (population count) in a 16-, 32-, or 64-byte unsigned integer.
|
||||
proc builtin_popcnt16(a2: uint16): uint16 {.
|
||||
importc: "__popcnt16", header: "<intrin.h>", noSideEffect.}
|
||||
proc builtin_popcnt32(a2: uint32): uint32 {.
|
||||
importc: "__popcnt", header: "<intrin.h>", noSideEffect.}
|
||||
proc builtin_popcnt64(a2: uint64): uint64 {.
|
||||
importc: "__popcnt64", header: "<intrin.h>", noSideEffect.}
|
||||
func builtin_popcnt16(a2: uint16): uint16 {.
|
||||
importc: "__popcnt16", header: "<intrin.h>".}
|
||||
func builtin_popcnt32(a2: uint32): uint32 {.
|
||||
importc: "__popcnt", header: "<intrin.h>".}
|
||||
func builtin_popcnt64(a2: uint64): uint64 {.
|
||||
importc: "__popcnt64", header: "<intrin.h>".}
|
||||
|
||||
# Search the mask data from most significant bit (MSB) to least significant bit (LSB) for a set bit (1).
|
||||
proc bitScanReverse(index: ptr culong, mask: culong): cuchar {.
|
||||
importc: "_BitScanReverse", header: "<intrin.h>", noSideEffect.}
|
||||
proc bitScanReverse64(index: ptr culong, mask: uint64): cuchar {.
|
||||
importc: "_BitScanReverse64", header: "<intrin.h>", noSideEffect.}
|
||||
func bitScanReverse(index: ptr culong, mask: culong): cuchar {.
|
||||
importc: "_BitScanReverse", header: "<intrin.h>".}
|
||||
func bitScanReverse64(index: ptr culong, mask: uint64): cuchar {.
|
||||
importc: "_BitScanReverse64", header: "<intrin.h>".}
|
||||
|
||||
# Search the mask data from least significant bit (LSB) to the most significant bit (MSB) for a set bit (1).
|
||||
proc bitScanForward(index: ptr culong, mask: culong): cuchar {.
|
||||
importc: "_BitScanForward", header: "<intrin.h>", noSideEffect.}
|
||||
proc bitScanForward64(index: ptr culong, mask: uint64): cuchar {.
|
||||
importc: "_BitScanForward64", header: "<intrin.h>", noSideEffect.}
|
||||
func bitScanForward(index: ptr culong, mask: culong): cuchar {.
|
||||
importc: "_BitScanForward", header: "<intrin.h>".}
|
||||
func bitScanForward64(index: ptr culong, mask: uint64): cuchar {.
|
||||
importc: "_BitScanForward64", header: "<intrin.h>".}
|
||||
|
||||
template vcc_scan_impl(fnc: untyped; v: untyped): int =
|
||||
var index: culong
|
||||
|
|
@ -508,22 +512,22 @@ elif useICC_builtins:
|
|||
# Intel compiler intrinsics: http://fulla.fnal.gov/intel/compiler_c/main_cls/intref_cls/common/intref_allia_misc.htm
|
||||
# see also: https://software.intel.com/en-us/node/523362
|
||||
# Count the number of bits set to 1 in an integer a, and return that count in dst.
|
||||
proc builtin_popcnt32(a: cint): cint {.
|
||||
importc: "_popcnt", header: "<immintrin.h>", noSideEffect.}
|
||||
proc builtin_popcnt64(a: uint64): cint {.
|
||||
importc: "_popcnt64", header: "<immintrin.h>", noSideEffect.}
|
||||
func builtin_popcnt32(a: cint): cint {.
|
||||
importc: "_popcnt", header: "<immintrin.h>".}
|
||||
func builtin_popcnt64(a: uint64): cint {.
|
||||
importc: "_popcnt64", header: "<immintrin.h>".}
|
||||
|
||||
# Returns the number of trailing 0-bits in x, starting at the least significant bit position. If x is 0, the result is undefined.
|
||||
proc bitScanForward(p: ptr uint32, b: uint32): cuchar {.
|
||||
importc: "_BitScanForward", header: "<immintrin.h>", noSideEffect.}
|
||||
proc bitScanForward64(p: ptr uint32, b: uint64): cuchar {.
|
||||
importc: "_BitScanForward64", header: "<immintrin.h>", noSideEffect.}
|
||||
func bitScanForward(p: ptr uint32, b: uint32): cuchar {.
|
||||
importc: "_BitScanForward", header: "<immintrin.h>".}
|
||||
func bitScanForward64(p: ptr uint32, b: uint64): cuchar {.
|
||||
importc: "_BitScanForward64", header: "<immintrin.h>".}
|
||||
|
||||
# Returns the number of leading 0-bits in x, starting at the most significant bit position. If x is 0, the result is undefined.
|
||||
proc bitScanReverse(p: ptr uint32, b: uint32): cuchar {.
|
||||
importc: "_BitScanReverse", header: "<immintrin.h>", noSideEffect.}
|
||||
proc bitScanReverse64(p: ptr uint32, b: uint64): cuchar {.
|
||||
importc: "_BitScanReverse64", header: "<immintrin.h>", noSideEffect.}
|
||||
func bitScanReverse(p: ptr uint32, b: uint32): cuchar {.
|
||||
importc: "_BitScanReverse", header: "<immintrin.h>".}
|
||||
func bitScanReverse64(p: ptr uint32, b: uint64): cuchar {.
|
||||
importc: "_BitScanReverse64", header: "<immintrin.h>".}
|
||||
|
||||
template icc_scan_impl(fnc: untyped; v: untyped): int =
|
||||
var index: uint32
|
||||
|
|
@ -531,8 +535,8 @@ elif useICC_builtins:
|
|||
index.int
|
||||
|
||||
|
||||
proc countSetBits*(x: SomeInteger): int {.inline, noSideEffect.} =
|
||||
## Counts the set bits in integer. (also called `Hamming weight`:idx:.)
|
||||
func countSetBits*(x: SomeInteger): int {.inline.} =
|
||||
## Counts the set bits in an integer (also called `Hamming weight`:idx:).
|
||||
runnableExamples:
|
||||
doAssert countSetBits(0b0000_0011'u8) == 2
|
||||
doAssert countSetBits(0b1010_1010'u8) == 4
|
||||
|
|
@ -562,13 +566,13 @@ proc countSetBits*(x: SomeInteger): int {.inline, noSideEffect.} =
|
|||
when sizeof(x) <= 4: result = countSetBitsNim(x.uint32)
|
||||
else: result = countSetBitsNim(x.uint64)
|
||||
|
||||
proc popcount*(x: SomeInteger): int {.inline, noSideEffect.} =
|
||||
## Alias for for `countSetBits <#countSetBits,SomeInteger>`_. (Hamming weight.)
|
||||
func popcount*(x: SomeInteger): int {.inline.} =
|
||||
## Alias for `countSetBits <#countSetBits,SomeInteger>`_ (Hamming weight).
|
||||
result = countSetBits(x)
|
||||
|
||||
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.
|
||||
func parityBits*(x: SomeInteger): int {.inline.} =
|
||||
## Calculate the bit parity in an integer. If the number of 1-bits
|
||||
## is odd, the parity is 1, otherwise 0.
|
||||
runnableExamples:
|
||||
doAssert parityBits(0b0000_0000'u8) == 0
|
||||
doAssert parityBits(0b0101_0001'u8) == 1
|
||||
|
|
@ -589,10 +593,10 @@ proc parityBits*(x: SomeInteger): int {.inline, noSideEffect.} =
|
|||
when sizeof(x) <= 4: result = parityImpl(x.uint32)
|
||||
else: result = parityImpl(x.uint64)
|
||||
|
||||
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.
|
||||
func firstSetBit*(x: SomeInteger): int {.inline.} =
|
||||
## Returns the 1-based index of the least significant set bit of `x`.
|
||||
## If `x` is zero, when `noUndefinedBitOpts` is set, the result is 0,
|
||||
## otherwise the result is undefined.
|
||||
runnableExamples:
|
||||
doAssert firstSetBit(0b0000_0001'u8) == 1
|
||||
doAssert firstSetBit(0b0000_0010'u8) == 2
|
||||
|
|
@ -633,10 +637,10 @@ proc firstSetBit*(x: SomeInteger): int {.inline, noSideEffect.} =
|
|||
when sizeof(x) <= 4: result = firstSetBitNim(x.uint32)
|
||||
else: result = firstSetBitNim(x.uint64)
|
||||
|
||||
proc fastLog2*(x: SomeInteger): int {.inline, noSideEffect.} =
|
||||
func fastLog2*(x: SomeInteger): int {.inline.} =
|
||||
## Quickly find the log base 2 of an integer.
|
||||
## If `x` is zero, when ``noUndefinedBitOpts`` is set, result is -1,
|
||||
## otherwise result is undefined.
|
||||
## If `x` is zero, when `noUndefinedBitOpts` is set, the result is -1,
|
||||
## otherwise the result is undefined.
|
||||
runnableExamples:
|
||||
doAssert fastLog2(0b0000_0001'u8) == 0
|
||||
doAssert fastLog2(0b0000_0010'u8) == 1
|
||||
|
|
@ -673,12 +677,12 @@ proc fastLog2*(x: SomeInteger): int {.inline, noSideEffect.} =
|
|||
when sizeof(x) <= 4: result = fastlog2Nim(x.uint32)
|
||||
else: result = fastlog2Nim(x.uint64)
|
||||
|
||||
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.
|
||||
func countLeadingZeroBits*(x: SomeInteger): int {.inline.} =
|
||||
## Returns the number of leading zero bits in an integer.
|
||||
## If `x` is zero, when `noUndefinedBitOpts` is set, the result is 0,
|
||||
## otherwise the result is undefined.
|
||||
##
|
||||
## See also:
|
||||
## **See also:**
|
||||
## * `countTrailingZeroBits proc <#countTrailingZeroBits,SomeInteger>`_
|
||||
runnableExamples:
|
||||
doAssert countLeadingZeroBits(0b0000_0001'u8) == 7
|
||||
|
|
@ -702,12 +706,12 @@ proc countLeadingZeroBits*(x: SomeInteger): int {.inline, noSideEffect.} =
|
|||
when sizeof(x) <= 4: result = sizeof(x)*8 - 1 - fastlog2Nim(x.uint32)
|
||||
else: result = sizeof(x)*8 - 1 - fastlog2Nim(x.uint64)
|
||||
|
||||
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.
|
||||
func countTrailingZeroBits*(x: SomeInteger): int {.inline.} =
|
||||
## Returns the number of trailing zeros in an integer.
|
||||
## If `x` is zero, when `noUndefinedBitOpts` is set, the result is 0,
|
||||
## otherwise the result is undefined.
|
||||
##
|
||||
## See also:
|
||||
## **See also:**
|
||||
## * `countLeadingZeroBits proc <#countLeadingZeroBits,SomeInteger>`_
|
||||
runnableExamples:
|
||||
doAssert countTrailingZeroBits(0b0000_0001'u8) == 0
|
||||
|
|
@ -769,7 +773,7 @@ when useBuiltinsRotate:
|
|||
when defined(amd64):
|
||||
func builtin_rotl64(value: culonglong, shift: culonglong): culonglong
|
||||
{.importc: "__builtin_rotateleft64", nodecl.}
|
||||
|
||||
|
||||
func builtin_rotr8(value: cuchar, shift: cuchar): cuchar
|
||||
{.importc: "__builtin_rotateright8", nodecl.}
|
||||
func builtin_rotr16(value: cushort, shift: cushort): cushort
|
||||
|
|
@ -863,7 +867,7 @@ func rotateLeftBits*(value: uint8, shift: range[0..8]): uint8 {.inline.} =
|
|||
## Left-rotate bits in a 8-bits value.
|
||||
runnableExamples:
|
||||
doAssert rotateLeftBits(0b0110_1001'u8, 4) == 0b1001_0110'u8
|
||||
|
||||
|
||||
when nimvm:
|
||||
rotl(value, shift.int32)
|
||||
else:
|
||||
|
|
@ -891,7 +895,7 @@ func rotateLeftBits*(value: uint32, shift: range[0..32]): uint32 {.inline.} =
|
|||
runnableExamples:
|
||||
doAssert rotateLeftBits(0b0000111111110000_1111000000001111'u32, 16) ==
|
||||
0b1111000000001111_0000111111110000'u32
|
||||
|
||||
|
||||
when nimvm:
|
||||
rotl(value, shift.int32)
|
||||
else:
|
||||
|
|
@ -969,15 +973,14 @@ func rotateRightBits*(value: uint64, shift: range[0..64]): uint64 {.inline.} =
|
|||
else:
|
||||
rotr(value, shift.int32)
|
||||
|
||||
proc repeatBits[T: SomeUnsignedInt](x: SomeUnsignedInt; retType: type[T]): T {.
|
||||
noSideEffect.} =
|
||||
func repeatBits[T: SomeUnsignedInt](x: SomeUnsignedInt; retType: type[T]): T =
|
||||
result = x
|
||||
var i = 1
|
||||
while i != (sizeof(T) div sizeof(x)):
|
||||
result = (result shl (sizeof(x)*8*i)) or result
|
||||
i *= 2
|
||||
|
||||
proc reverseBits*[T: SomeUnsignedInt](x: T): T {.noSideEffect.} =
|
||||
func reverseBits*[T: SomeUnsignedInt](x: T): T =
|
||||
## Return the bit reversal of x.
|
||||
runnableExamples:
|
||||
doAssert reverseBits(0b10100100'u8) == 0b00100101'u8
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue