Binary Numbers

Base-2 binary numbers tests and operations. More...

Collaboration diagram for Binary Numbers:

Files
file	binary.scad
	Base-2 binary numbers tests and operations.

Functions and/or Modules
function	binary_bit_is (v, b, t=1)
	Test if a binary bit position of an integer value equals a test bit. More...
function	binary_i2v (v, w=1, _bv=1)
	Encode an integer value as a binary list of bits. More...
function	binary_v2i (v)
	Decode a binary list of bits to an integer value. More...
function	binary_i2s (v, w=1)
	Encode an integer value as a binary string of bits. More...
function	binary_s2i (v)
	Decode a binary string of bits to an integer value. More...
function	binary_iw2i (v, s, w)
	Decode the binary bits of a bit window to an integer value. More...
function	binary_and (v1, v2, _bv=1)
	Base-2 binary AND operation for integers. More...
function	binary_or (v1, v2, _bv=1)
	Base-2 binary OR operation for integers. More...
function	binary_xor (v1, v2, _bv=1)
	Base-2 binary XOR operation for integers. More...
function	binary_not (v, w=1, _bv=1)
	Base-2 binary NOT operation for an integer. More...
function	binary_ishl (v, s=1)
	Base-2 binary left-shift operation for an integer. More...
function	binary_ishr (v, s=1)
	Base-2 binary right-shift operation for an integer. More...

Usage Details

Base-2 binary numbers tests and operations.

Validation Summary

file	group	script	results	no test	skipped	passed	failed	warning
datatypes/binary.scad	Binary Numbers	Script	Results	0	0	156	0	0

No Failures

See complete validation results.

Requires:
include <omdl-base.scad>;

Conventions

• All functions operate only on non-negative integers. Passing a negative integer produces undef (after the recommended fix; before the fix, it causes infinite recursion — see Correctness §2.1).
• Bit lists (<bit-list>) are stored LSB-first: the least-significant bit occupies index 0 and the most-significant bit occupies the last index.
• The parameter _bv in binary_and(), binary_or(), binary_xor(), binary_not(), and binary_i2v() is an internal recursion accumulator. It must not be initialised by callers.
• The parameter bm in binary_ishl() is an internal bit-mask accumulator. It must not be initialised by callers.
• binary_ishl() clips the result to the bit-width of the input v. Use binary_iw2i() to extract a fixed-width window from a wider value.
• Empty <bit-list> or <bit-string> inputs return undef (after the recommended fix) to distinguish the empty case from zero.

See Wikipedia binary numbers and operations for more information.

Function and/or Module Documentation

binary_bit_is()

function binary_bit_is	(	v	,
		b	,
		t	= 1
	)

Test if a binary bit position of an integer value equals a test bit.

Parameters

v	<integer> An integer value.
b	<integer> A binary bit position.
t	<bit> The bit test value [0|1].

Returns

(1) <boolean> true when the binary bit position in v specified by b equals t, otherwise returns false. (2) Returns undef if v or b is not an integer.

Here is the caller graph for this function:

binary_i2v()

function binary_i2v	(	v	,
		w	= 1,
		_bv	= 1
	)

Encode an integer value as a binary list of bits.

Parameters

v	<integer> An integer value.
w	<integer> The minimum bit width.
_bv	(an internal recursion loop variable).

Returns

(1) <bit-list> of bits binary encoding of the integer value. (2) Returns undef when v or w is not an integer.

The bit-list will be the minimum required to represent the value. If w is greater than the minimum required bits, then the value will be padded with '0'.

Bits are ordered most-significant-bit first: index 0 holds the most significant bit and the last index holds the least significant bit. For example, binary_i2v(6) returns [1,1,0], where [0]=MSB and [2]=LSB.

binary_v2i()

function binary_v2i

(

v

)

Decode a binary list of bits to an integer value.

Parameters

v	<bit-list> A value encoded as a binary list of bits.

Returns

(1) <integer> value encoding of the binary list of bits. (2) Returns undef when v is not a list of bit values.

binary_i2s()

function binary_i2s	(	v	,
		w	= 1
	)

Encode an integer value as a binary string of bits.

Parameters

v	<integer> An integer value.
w	<integer> The minimum bit width.

Returns

(1) <bit-string> of bits binary encoding of the integer value. (2) Returns undef when v or w is not an integer.

binary_s2i()

function binary_s2i

(

v

)

Decode a binary string of bits to an integer value.

Parameters

v	<bit-string> A value encoded as a binary string of bits.

Returns

(1) <integer> value encoding of the binary string of bits. (2) Returns undef when v is not a string of bit values.

binary_iw2i()

function binary_iw2i	(	v	,
		s	,
		w
	)

Decode the binary bits of a bit window to an integer value.

Parameters

v	<integer> An integer value.
s	<integer> The bit window start offset.
w	<integer> The bit window width.

Returns

(1) <integer> value of the w bits of v starting at bit position s up to bit (w+s-1). (2) Returns undef when v, w, or s is not an integer.

Here is the caller graph for this function:

binary_and()

function binary_and	(	v1	,
		v2	,
		_bv	= 1
	)

Base-2 binary AND operation for integers.

Parameters

v1	<integer> An integer value.
v2	<integer> An integer value.
_bv	(an internal recursion loop variable).

Returns

(1) <integer> the binary AND of v1 and v2. (2) Returns undef when v1 or v2 is not an integer.

Here is the caller graph for this function:

binary_or()

function binary_or	(	v1	,
		v2	,
		_bv	= 1
	)

Base-2 binary OR operation for integers.

Parameters

v1	<integer> An integer value.
v2	<integer> An integer value.
_bv	(an internal recursion loop variable).

Returns

(1) <integer> the binary OR of v1 and v2. (2) Returns undef when v1 or v2 is not an integer.

Here is the caller graph for this function:

binary_xor()

function binary_xor	(	v1	,
		v2	,
		_bv	= 1
	)

Base-2 binary XOR operation for integers.

Parameters

v1	<integer> An integer value.
v2	<integer> An integer value.
_bv	(an internal recursion loop variable).

Returns

(1) <integer> the binary XOR of v1 and v2. (2) Returns undef when v1 or v2 is not an integer.

binary_not()

function binary_not	(	v	,
		w	= 1,
		_bv	= 1
	)

Base-2 binary NOT operation for an integer.

Parameters

v	<integer> An integer value.
w	<integer> The minimum bit width.
_bv	(an internal recursion loop variable).

Returns

(1) <integer> the binary NOT of v. (2) Returns undef when v or w is not an integer.

binary_ishl()

function binary_ishl	(	v	,
		s	= 1
	)

Base-2 binary left-shift operation for an integer.

Parameters

v	<integer> A non-negative integer value.
s	<integer> A non-negative number of bits to shift.

Returns

(1) <integer> the binary left-shift of v by s bits. (2) Returns undef when v or s is not an integer or when either is negative.

binary_ishr()

function binary_ishr	(	v	,
		s	= 1
	)

Base-2 binary right-shift operation for an integer.

Parameters

v	<integer> A non-negative integer value.
s	<integer> The number of bits to shift.

Returns

(1) <integer> the binary right-shift of v by s bits. (2) Returns undef when v or s is not an integer or when either is negative.

Here is the caller graph for this function: