bits(+Shift, +Width, ?Word, ?Bits, ?Rest) is semidet

 bits(+ShiftWidthPair, ?Word, ?Bits, ?Rest) is semidet

 bits(+ShiftWidthPair, ?Word, ?Bits) is semidet

Unifies Bits within a Word using Shift and Width. All arguments are integers treated as words of arbitrary bit-width.

The implementation uses relational integer arithmetic, i.e. CLP(FD). Hence allows for forward and backward transformations from Word to Bits and vice versa. Integer Word applies a Shift and bit Width mask to integer Bits. Bits is always a smaller integer. Decomposes the problem into shifting and masking. Treats these operations separately.

Arguments:

Width

- of Bits from Word after Shift. Width of zero always fails.

 bit_fields(+Fields:list, +Shift:integer, +Int:integer) is semidet

 bit_fields(+Fields:list, +Shift:integer, +Int0:integer, -Int:integer) is semidet

Two versions of the predicate unify Value:Width bit fields with integers. The arity-3 version requires a bound Int from which to find unbound (or bound) values in the Fields; used to extract values from integers else check values semi-deterministically. The arity-4 version of the predicate accumulates bit-field values by OR-wise merging shifted bits from Int0 to Int.

The predicates are semi-deterministic. They can fail. Failure occurs when the bit-field Width integers do not sum to Shift.

Arguments:

Fields	- is a list of value and width terms of the form Value:Width where Width is an integer; Value is either a variable or an integer.
Shift	- is an integer number of total bits, e.g. 8 for eight-bit bytes, 16 for sixteen-bit words and so on.

 rbit(+Shift:integer, +Int:integer, ?Reverse:integer) is semidet

Bit reversal over a given span of bits. The reverse bits equal the mirror image of the original; integer $1$ reversed in 16 bits becomes $8000_{16}$ for instance.

Arity-3 rbit/3 predicate throws away the residual. Any bit values lying outside the shifting span disappear; they do not appear in the residual and the predicate discards them. The order of the sub-terms is not very important, except for failures. Placing succ first ensures that recursive shifting fails if Shift is not a positive integer; it triggers an exception if not actually an integer.

Undocumented predicates

The following predicates are exported, but not or incorrectly documented.

 bits(Arg1, Arg2, Arg3, Arg4)

 bits(Arg1, Arg2, Arg3)

 bit_fields(Arg1, Arg2, Arg3, Arg4)