kex docs Standard Library 0.4.0-alpha kex.run ↗

Bits

module Bits

Bitwise operations on Integer.

Bits.and(0xff, 0x0f)      # => 15
Bits.shiftLeft(1, 8)      # => 256
Bits.test?(0b1010, 1)     # => true

Useful for packing flags into one number, reading a binary format, or working with a protocol that describes its fields in bits.

Integers are arbitrary precision, and a negative one behaves as if it were written in infinite-precision two's complement, so Bits.not(0) is -1 and Bits.and(-1, 255) is 255, with no word size to overflow. Shifts and bit indices count from bit 0 (the least significant bit).

function and

Bitwise AND of a and b.

and(a, b) : Integer -> Integer -> Integer
Parameters
a Integer
the first operand
b Integer
the second operand

Returns: Integer — the result

Examples
Bits.and(0b1100, 0b1010)   # => 0b1000
Bits.and(0xff, 0x0f)       # => 15

Masking off the low byte of a value

Bits.and(value, 0xff)

Testing whether a flag is present in a bitmask

Bits.and(flags, READONLY) != 0

function or

Bitwise OR of a and b.

or(a, b) : Integer -> Integer -> Integer
Parameters
a Integer
the first operand
b Integer
the second operand

Returns: Integer — the result

Examples
Bits.or(0b1100, 0b1010)   # => 0b1110

Combining flags into one value

Bits.or(Bits.or(READ, WRITE), APPEND)

function xor

Bitwise exclusive OR of a and b.

xor(a, b) : Integer -> Integer -> Integer
Parameters
a Integer
the first operand
b Integer
the second operand

Returns: Integer — the result

Examples
Bits.xor(0b1100, 0b1010)   # => 0b0110

Toggling a set of flags

Bits.xor(flags, VERBOSE)

function not

Bitwise complement of a. Every integer is signed and unbounded, so this is always -(a 1)+ rather than a width-dependent mask.

not(a) : Integer -> Integer
Parameters
a Integer
the operand

Returns: Integer — the complement

Examples
Bits.not(0)   # => -1
Bits.not(5)   # => -6

function shiftLeft

Shifts n left by by bits. Raises if by is negative.

shiftLeft(n, by) : Integer -> Integer -> Integer
Parameters
n Integer
the value to shift
by Integer
how many bits to shift by

Returns: Integer — the shifted value

Examples
Bits.shiftLeft(1, 8)   # => 256
Bits.shiftLeft(3, 2)   # => 12

Building a flag constant for bit n

Bits.shiftLeft(1, n)

function shiftRight

Shifts n right by by bits, propagating the sign: the result of shifting a negative number stays negative. Raises if by is negative.

shiftRight(n, by) : Integer -> Integer -> Integer
Parameters
n Integer
the value to shift
by Integer
how many bits to shift by

Returns: Integer — the shifted value

Examples
Bits.shiftRight(256, 8)   # => 1
Bits.shiftRight(-8, 1)    # => -4

function test?

True when the bit at index of n is set. Raises if index is negative.

test?(n, index) : Integer -> Integer -> Bool
Parameters
n Integer
the value to inspect
index Integer
the bit position, counting from 0

Returns: Bool — true when that bit is set

Examples
Bits.test?(0b1000, 3)   # => true
Bits.test?(0b1000, 0)   # => false

function set

n with the bit at index set. Raises if index is negative.

set(n, index) : Integer -> Integer -> Integer
Parameters
n Integer
the value to modify
index Integer
the bit position, counting from 0

Returns: Integer — the modified value

Examples
Bits.set(0, 3)   # => 8

function clear

n with the bit at index cleared. Raises if index is negative.

clear(n, index) : Integer -> Integer -> Integer
Parameters
n Integer
the value to modify
index Integer
the bit position, counting from 0

Returns: Integer — the modified value

Examples
Bits.clear(0b1111, 0)   # => 14

function toggle

n with the bit at index flipped. Raises if index is negative.

toggle(n, index) : Integer -> Integer -> Integer
Parameters
n Integer
the value to modify
index Integer
the bit position, counting from 0

Returns: Integer — the modified value

Examples
Bits.toggle(0b1010, 0)   # => 11

function count

Number of set bits in n (population count). A negative value has infinitely many under two's complement, so this raises for one.

count(n) : Integer -> Integer
Parameters
n Integer
the value to measure

Returns: Integer — the count

Examples
Bits.count(0b1011)   # => 3
Bits.count(255)      # => 8

How many flags are set

Bits.count(flags)

function width

Number of bits needed to represent n, i.e. the position of its highest set bit plus one. Zero needs none. Raises for a negative value.

width(n) : Integer -> Integer
Parameters
n Integer
the value to measure

Returns: Integer — the count

Examples
Bits.width(0)     # => 0
Bits.width(255)   # => 8
Bits.width(256)   # => 9