diff --git a/doc/ref/srfi-modules.texi b/doc/ref/srfi-modules.texi index e24cce34f..81d8335a5 100644 --- a/doc/ref/srfi-modules.texi +++ b/doc/ref/srfi-modules.texi @@ -38,6 +38,7 @@ get the relevant SRFI documents from the SRFI home page * SRFI-26:: Specializing parameters * SRFI-31:: A special form `rec' for recursive evaluation * SRFI-39:: Parameter objects +* SRFI-60:: Integers as bits. @end menu @@ -2379,6 +2380,151 @@ threads, so the threading behaviour described here should be regarded as Guile-specific. +@node SRFI-60 +@subsection SRFI-60 - Integers as Bits +@cindex SRFI-60 +@cindex integers as bits +@cindex bitwise logical + +This SRFI provides various functions for treating integers as bits and +for bitwise manipulations. These functions can be obtained with, + +@example +(use-modules (srfi srfi-60)) +@end example + +Integers are treated as infinite precision twos-complement, the same +as in the core logical functions (@pxref{Bitwise Operations}). And +likewise bit indexes start from 0 for the least significant bit. The +following functions in this SRFI are already in the Guile core, + +@quotation +@code{logand}, +@code{logior}, +@code{logxor}, +@code{lognot}, +@code{logtest}, +@code{logcount}, +@code{integer-length}, +@code{logbit?}, +@code{ash} +@end quotation + +@sp 1 +@defun bitwise-and n1 ... +@defunx bitwise-ior n1 ... +@defunx bitwise-xor n1 ... +@defunx bitwise-not n +@defunx any-bits-set? j k +@defunx bit-set? index n +@defunx arithmetic-shift n count +@defunx bit-field n start end +@defunx bit-count n +Aliases for @code{logand}, @code{logior}, @code{logxor}, +@code{lognot}, @code{logtest}, @code{logbit?}, @code{ash}, +@code{bit-extract} and @code{logcount} respectively. + +Note that the name @code{bit-count} conflicts with @code{bit-count} in +the core (@pxref{Bit Vectors}). +@end defun + +@defun bitwise-if mask n1 n0 +@defunx bitwise-merge mask n1 n0 +Return an integer with bits selected from @var{n1} and @var{n0} +according to @var{mask}. Those bits where @var{mask} has 1s are taken +from @var{n1}, and those where @var{mask} has 0s are taken from +@var{n0}. + +@example +(bitwise-if 3 #b0101 #b1010) @result{} 9 +@end example +@end defun + +@defun log2-binary-factors n +@defunx first-set-bit n +Return a count of how many factors of 2 are present in @var{n}. This +is also the bit index of the lowest 1 bit in @var{n}. If @var{n} is +0, the return is @math{-1}. + +@example +(log2-binary-factors 6) @result{} 1 +(log2-binary-factors -8) @result{} 3 +@end example +@end defun + +@defun copy-bit index n newbit +Return @var{n} with the bit at @var{index} set according to +@var{newbit}. @var{newbit} should be @code{#t} to set the bit to 1, +or @code{#f} to set it to 0. Bits other than at @var{index} are +unchanged in the return. + +@example +(copy-bit 1 #b0101 #t) @result{} 7 +@end example +@end defun + +@defun copy-bit-field n newbits start end +Return @var{n} with the bits from @var{start} (inclusive) to @var{end} +(exclusive) changed to the value @var{newbits}. + +The least significant bit in @var{newbits} goes to @var{start}, the +next to @math{@var{start}+1}, etc. Anything in @var{newbits} past the +@var{end} given is ignored. + +@example +(copy-bit-field #b10000 #b11 1 3) @result{} #b10110 +@end example +@end defun + +@defun rotate-bit-field n count start end +Return @var{n} with the bit field from @var{start} (inclusive) to +@var{end} (exclusive) rotated upwards by @var{count} bits. + +@var{count} can be positive or negative, and it can be more than the +field width (it'll be reduced modulo the width). + +@example +(rotate-bit-field #b0110 2 1 4) @result{} #b1010 +@end example +@end defun + +@defun reverse-bit-field n start end +Return @var{n} with the bits from @var{start} (inclusive) to @var{end} +(exclusive) reversed. + +@example +(reverse-bit-field #b101001 2 4) @result{} #b100101 +@end example +@end defun + +@defun integer->list n [len] +Return bits from @var{n} in the form of a list of @code{#t} for 1 and +@code{#f} for 0. The least significant @var{len} bits are returned, +and the first list element is the most significant of those bits. If +@var{len} is not given, the default is @code{(integer-length @var{n})} +(@pxref{Bitwise Operations}). + +@example +(integer->list 6) @result{} (#t #t #f) +(integer->list 1 4) @result{} (#f #f #f #t) +@end example +@end defun + +@defun list->integer lst +@defunx booleans->integer bool@dots{} +Return an integer formed bitwise from the given @var{lst} list of +booleans, or for @code{booleans->integer} from the @var{bool} +arguments. + +Each boolean is @code{#t} for a 1 and @code{#f} for a 0. The first +element becomes the most significant bit in the return. + +@example +(list->integer '(#t #f #t #f)) @result{} 10 +@end example +@end defun + + @c srfi-modules.texi ends here @c Local Variables: