mirrors/Nim
1
0
Fork 0
mirror of https://github.com/nim-lang/Nim.git synced 2026-08-29 10:01:39 +00:00
Code Issues Packages Projects Releases Wiki Activity

doc: bitops: add runnableExamples

Browse Source
This commit is contained in:
jiro4989
2020-04-08 09:29:12 +09:00
parent 3036ec9c44
commit b476905c2a
1 changed files with 135 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

136
lib/pure/bitops.nim
View File

@@ -72,30 +72,69 @@ when defined(nimHasalignOf):
proc setMask*[T: SomeInteger](v: var T, mask: T) {.inline.} =
## Returns ``v``, with all the ``1`` bits from ``mask`` set to 1
runnableExamples:
var v = 0b0000_0011'u8
v.setMask(0b0000_1010'u8)
doAssert v == 0b0000_1011'u8
v = v or mask
proc clearMask*[T: SomeInteger](v: var T, mask: T) {.inline.} =
## Returns ``v``, with all the ``1`` bits from ``mask`` set to 0
runnableExamples:
var v = 0b0000_0011'u8
v.clearMask(0b0000_1010'u8)
doAssert v == 0b0000_0001'u8
v = v and not mask
proc flipMask*[T: SomeInteger](v: var T, mask: T) {.inline.} =
## Returns ``v``, with all the ``1`` bits from ``mask`` flipped
runnableExamples:
var v = 0b0000_0011'u8
v.flipMask(0b0000_1010'u8)
doAssert v == 0b0000_1001'u8
v = v xor mask
proc setBit*[T: SomeInteger](v: var T, bit: BitsRange[T]) {.inline.} =
## Returns ``v``, with the bit at position ``bit`` set to 1
runnableExamples:
var v = 0b0000_0011'u8
v.setBit(5'u8)
doAssert v == 0b0010_0011'u8
v.setMask(1.T shl bit)
proc clearBit*[T: SomeInteger](v: var T, bit: BitsRange[T]) {.inline.} =
## Returns ``v``, with the bit at position ``bit`` set to 0
runnableExamples:
var v = 0b0000_0011'u8
v.clearBit(1'u8)
doAssert v == 0b0000_0001'u8
v.clearMask(1.T shl bit)
proc flipBit*[T: SomeInteger](v: var T, bit: BitsRange[T]) {.inline.} =
## Returns ``v``, with the bit at position ``bit`` flipped
runnableExamples:
var v = 0b0000_0011'u8
v.flipBit(1'u8)
doAssert v == 0b0000_0001'u8
v = 0b0000_0011'u8
v.flipBit(2'u8)
doAssert v == 0b0000_0111'u8
v.flipMask(1.T shl bit)
macro setBits*(v: typed, bits: varargs[typed]): untyped =
## Returns ``v``, with the bits at positions ``bits`` set to 1
runnableExamples:
var v = 0b0000_0011'u8
v.setBits(3, 5, 7)
doAssert v == 0b1010_1011'u8
bits.expectKind(nnkBracket)
result = newStmtList()
for bit in bits:
@@ -103,6 +142,11 @@ when defined(nimHasalignOf):
macro clearBits*(v: typed, bits: varargs[typed]): untyped =
## Returns ``v``, with the bits at positions ``bits`` set to 0
runnableExamples:
var v = 0b1111_1111'u8
v.clearBits(1, 3, 5, 7)
doAssert v == 0b0101_0101'u8
bits.expectKind(nnkBracket)
result = newStmtList()
for bit in bits:
@@ -110,6 +154,11 @@ when defined(nimHasalignOf):
macro flipBits*(v: typed, bits: varargs[typed]): untyped =
## Returns ``v``, with the bits at positions ``bits`` set to 0
runnableExamples:
var v = 0b0000_1111'u8
v.flipBits(1, 3, 5, 7)
doAssert v == 0b1010_0101'u8
bits.expectKind(nnkBracket)
result = newStmtList()
for bit in bits:
@@ -117,6 +166,17 @@ 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
runnableExamples:
var v = 0b0000_1111'u8
doAssert v.testBit(0)
doAssert v.testBit(1)
doAssert v.testBit(2)
doAssert v.testBit(3)
doAssert not v.testBit(4)
doAssert not v.testBit(5)
doAssert not v.testBit(6)
doAssert not v.testBit(7)
let mask = 1.T shl bit
return (v and mask) == mask
@@ -272,6 +332,10 @@ elif useICC_builtins:
proc countSetBits*(x: SomeInteger): int {.inline, noSideEffect.} =
## Counts the set bits in integer. (also called `Hamming weight`:idx:.)
runnableExamples:
doAssert countSetBits(0b0000_0011'u8) == 2
doAssert countSetBits(0b1010_1010'u8) == 4
# TODO: figure out if ICC support _popcnt32/_popcnt64 on platform without POPCNT.
# like GCC and MSVC
when x is SomeSignedInt:
@@ -298,12 +362,18 @@ proc countSetBits*(x: SomeInteger): int {.inline, noSideEffect.} =
else: result = countSetBitsNim(x.uint64)
proc popcount*(x: SomeInteger): int {.inline, noSideEffect.} =
## Alias for for countSetBits (Hamming weight.)
## Alias for 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.
runnableExamples:
doAssert parityBits(0b0000_0000'u8) == 0
doAssert parityBits(0b0101_0001'u8) == 1
doAssert parityBits(0b0110_1001'u8) == 0
doAssert parityBits(0b0111_1111'u8) == 1
# Can be used a base if creating ASM version.
# https://stackoverflow.com/questions/21617970/how-to-check-if-value-has-even-parity-of-bits-or-odd
when x is SomeSignedInt:
@@ -322,6 +392,13 @@ 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.
runnableExamples:
doAssert firstSetBit(0b0000_0001'u8) == 1
doAssert firstSetBit(0b0000_0010'u8) == 2
doAssert firstSetBit(0b0000_0100'u8) == 3
doAssert firstSetBit(0b0000_1000'u8) == 4
doAssert firstSetBit(0b0000_1111'u8) == 1
# GCC builtin 'builtin_ffs' already handle zero input.
when x is SomeSignedInt:
let x = x.toUnsigned
@@ -359,6 +436,13 @@ 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.
runnableExamples:
doAssert fastLog2(0b0000_0001'u8) == 0
doAssert fastLog2(0b0000_0010'u8) == 1
doAssert fastLog2(0b0000_0100'u8) == 2
doAssert fastLog2(0b0000_1000'u8) == 3
doAssert fastLog2(0b0000_1111'u8) == 3
when x is SomeSignedInt:
let x = x.toUnsigned
when noUndefined:
@@ -392,6 +476,16 @@ 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.
##
## See also:
## * `countTrailingZeroBits proc <#countTrailingZeroBits,SomeInteger>`_
runnableExamples:
doAssert countLeadingZeroBits(0b0000_0001'u8) == 7
doAssert countLeadingZeroBits(0b0000_0010'u8) == 6
doAssert countLeadingZeroBits(0b0000_0100'u8) == 5
doAssert countLeadingZeroBits(0b0000_1000'u8) == 4
doAssert countLeadingZeroBits(0b0000_1111'u8) == 4
when x is SomeSignedInt:
let x = x.toUnsigned
when noUndefined:
@@ -411,6 +505,16 @@ 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.
##
## See also:
## * `countLeadingZeroBits proc <#countLeadingZeroBits,SomeInteger>`_
runnableExamples:
doAssert countTrailingZeroBits(0b0000_0001'u8) == 0
doAssert countTrailingZeroBits(0b0000_0010'u8) == 1
doAssert countTrailingZeroBits(0b0000_0100'u8) == 2
doAssert countTrailingZeroBits(0b0000_1000'u8) == 3
doAssert countTrailingZeroBits(0b0000_1111'u8) == 0
when x is SomeSignedInt:
let x = x.toUnsigned
when noUndefined:
@@ -429,6 +533,12 @@ proc countTrailingZeroBits*(x: SomeInteger): int {.inline, noSideEffect.} =
proc rotateLeftBits*(value: uint8;
amount: range[0..8]): uint8 {.inline, noSideEffect.} =
## Left-rotate bits in a 8-bits value.
runnableExamples:
doAssert rotateLeftBits(0b0000_0001'u8, 1) == 0b0000_0010'u8
doAssert rotateLeftBits(0b0000_0001'u8, 2) == 0b0000_0100'u8
doAssert rotateLeftBits(0b0100_0001'u8, 1) == 0b1000_0010'u8
doAssert rotateLeftBits(0b0100_0001'u8, 2) == 0b0000_0101'u8
# using this form instead of the one below should handle any value
# out of range as well as negative values.
# result = (value shl amount) or (value shr (8 - amount))
@@ -439,18 +549,27 @@ proc rotateLeftBits*(value: uint8;
proc rotateLeftBits*(value: uint16;
amount: range[0..16]): uint16 {.inline, noSideEffect.} =
## Left-rotate bits in a 16-bits value.
##
## See also:
## * `rotateLeftBits proc <#rotateLeftBits,uint8,range[]>`_
let amount = amount and 15
result = (value shl amount) or (value shr ( (-amount) and 15))
proc rotateLeftBits*(value: uint32;
amount: range[0..32]): uint32 {.inline, noSideEffect.} =
## Left-rotate bits in a 32-bits value.
##
## See also:
## * `rotateLeftBits proc <#rotateLeftBits,uint8,range[]>`_
let amount = amount and 31
result = (value shl amount) or (value shr ( (-amount) and 31))
proc rotateLeftBits*(value: uint64;
amount: range[0..64]): uint64 {.inline, noSideEffect.} =
## Left-rotate bits in a 64-bits value.
##
## See also:
## * `rotateLeftBits proc <#rotateLeftBits,uint8,range[]>`_
let amount = amount and 63
result = (value shl amount) or (value shr ( (-amount) and 63))
@@ -458,24 +577,39 @@ proc rotateLeftBits*(value: uint64;
proc rotateRightBits*(value: uint8;
amount: range[0..8]): uint8 {.inline, noSideEffect.} =
## Right-rotate bits in a 8-bits value.
runnableExamples:
doAssert rotateRightBits(0b0000_0001'u8, 1) == 0b1000_0000'u8
doAssert rotateRightBits(0b0000_0001'u8, 2) == 0b0100_0000'u8
doAssert rotateRightBits(0b0100_0001'u8, 1) == 0b1010_0000'u8
doAssert rotateRightBits(0b0100_0001'u8, 2) == 0b0101_0000'u8
let amount = amount and 7
result = (value shr amount) or (value shl ( (-amount) and 7))
proc rotateRightBits*(value: uint16;
amount: range[0..16]): uint16 {.inline, noSideEffect.} =
## Right-rotate bits in a 16-bits value.
##
## See also:
## * `rotateRightBits proc <#rotateRightBits,uint8,range[]>`_
let amount = amount and 15
result = (value shr amount) or (value shl ( (-amount) and 15))
proc rotateRightBits*(value: uint32;
amount: range[0..32]): uint32 {.inline, noSideEffect.} =
## Right-rotate bits in a 32-bits value.
##
## See also:
## * `rotateRightBits proc <#rotateRightBits,uint8,range[]>`_
let amount = amount and 31
result = (value shr amount) or (value shl ( (-amount) and 31))
proc rotateRightBits*(value: uint64;
amount: range[0..64]): uint64 {.inline, noSideEffect.} =
## Right-rotate bits in a 64-bits value.
##
## See also:
## * `rotateRightBits proc <#rotateRightBits,uint8,range[]>`_
let amount = amount and 63
result = (value shr amount) or (value shl ( (-amount) and 63))