Next: gauche.cgen - Generating C code, Previous: gauche.base - Importing gauche built-ins, Up: Library modules - Gauche extensions [Contents][Index]
gauche.bitvector - Bitvector utilitiesThis module adds more operations on bitvectors.
This module and built-in bitvector procedures covers SRFI-178
Bitvector library interface (see srfi.178 - Bitvector library)
Gauche supports bitvectors as a native type, but the core library only offers a handful of primitives (see Bitvectors). This module provides the comprehensive operations on bitvectors.
[SRFI-178]{gauche.bitvector} Creates a bitvector of length length, and fill its contents by repeatedly applying f. The procedure f must take one more than the number of seeds, and must return the same number of values. First, f is applied to the index and seed …, then its first return value (which must be a bit, i.e. 0, 1 or a boolean value) is used to initialize the index-th element of the bitvector, and the rest of the return value is used as the next argument to f. It is repeated length times.
While bitvector-unfold fills the bits from left to right,
bitvector-unfold-right does from right to left.
(use math.prime)
(bitvector-unfold (^[index n]
(values (small-prime? n) (+ n 1)))
20 0)
⇒ #*00110101000101000101
(bitvector-unfold-right (^[index n]
(values (small-prime? n) (+ n 1)))
20 0)
⇒ #*10100010100010101100
Note: This procedure follows the protocol of vector-unfold
(see scheme.vector - R7RS vectors), and has a different protocol from other
unfold procedures (see scheme.list - R7RS lists).
[SRFI-178]{gauche.bitvector} Copies a bitvector bv in reverse order. Optional start and end arguments limits the range of the input.
(bitvector-reverse-copy #*10110011100011110000 4 16) ⇒ #*111100011100
[SRFI-178]{gauche.bitvector} All arguments must be bytevectors. Returns a fresh bytevector which is concatenation of all arguments.
[SRFI-178]{gauche.bitvector} The argument must be a list of bitvectors. Returns a fresh bytevector which is concatenation of all bitvectors.
[SRFI-178]{gauche.bitvector} The number of arguments must be a multiple of 3. Each triplet of the arguments is a bytevector followed by start and end index, specifying the input bytevector range. Returns a fresh bytevector which is concatenation of all the subvectors.
(bitvector-append-subbitvectors #*11100011 2 6 #*01010101 3 8) ⇒ #*100010101
[SRFI-178]{gauche.bitvector}
Returns #t if bv is an empty bytevector,
#f if it is a non-empty bitvector.
An error is thrown if bv is not a bitvector.
[SRFI-178]{gauche.bitvector}
All arguments must be bitvectors.
Returns #t iff all the bitvectors have the same length and content.
If there’s zero or one argument, it returns #t.
[SRFI-178]{gauche.bitvector} Returns a new bitvector with the first/last n bits of a bitvector bv. An error is thrown if length of bv is less than n.
In Gauche, you can also use generic (subseq bv 0 n) to take the
first n bits. See gauche.sequence - Sequence framework.
[SRFI-178]{gauche.bitvector} Returns a new bitvector with bits except first/last n bits of a bitvector bv. An error is thrown if length of bv is less than n.
In Gauche, you can also use generic (subseq bv n)
to drop the first n bits. See gauche.sequence - Sequence framework.
[SRFI-178]{gauche.bitvector} Slices a bitvector bv with n-bits each, and returns a list of bitvectors. If the length of bv isn’t a multiple of n, the last bitvector may be shorter.
[SRFI-178]{gauche.bitvector} Fold kons over the elements of bitvectors with knil as the initial state value.
The kons procedure is always called as
(kons state e1 e2 …), where e1 e2 …
are elements from each bitvectors, as integer 0/1 (for /int procdures)
or boolean #f/#t (for /bool procedures).
This is the same order as vector-fold in
scheme.vector module (see scheme.vector - R7RS vectors).
(Note that list fold procedure calls the kons procedure
with different order; see Walking over lists).
All bitvectors must have the same length; otherwise, an error is thrown.
[SRFI-178]{gauche.bitvector} Apply a procedure f over each element taken from given bitvectors. The result of the procedure is gathered as a fresh bitvector and returned.
(bitvector-map/int logand #*10101 #*00111) ⇒ #*00101
All bitvectors must have the same length; otherwise, an error is thrown.
[SRFI-178]{gauche.bitvector} Apply a procedure f over each element taken from given bitvectors. The result of the procedure is set into bv1.
These procedure returns undefined value; you should count on the side effect onto bv1. In other words, they are not linear-updating procedures.
All bitvectors must have the same length; otherwise, an error is thrown.
[SRFI-178]{gauche.bitvector} Apply a procedure f over each element taken from given bitvectors. The result of the procedure is gathered as a list and returned.
All bitvectors must have the same length; otherwise, an error is thrown.
{gauche.bitvector}
Apply a procedure f over each index such that the index-th element
of bv is val, which must be either a boolean value or 0
or 1. The result of applications are gathered into a list,
from smaller index.
For example, the following returns a list of indices where the bit is true.
(bitvector-value-map-index->list identity #*10011 #t) ⇒ (0 3 4)
[SRFI-178]{gauche.bitvector} Apply a procedure f over each element taken from given bitvectors. The result of the procedure is discarded.
All bitvectors must have the same length; otherwise, an error is thrown.
(bitvector-for-each/int print #*11100 #*01110 #00111)
⇒ prints
100
110
111
011
001
{gauche.bitvector}
Apply a procedure f over each index such that the index-th element
of bv is val, which must be either a boolean value or 0
or 1. The result of f is discarded.
(bitvector-value-for-each-index print #*1101111010 #f)
⇒ prints
2
7
9
See also bitvector-value-map-index->list above.
[SRFI-178]{gauche.bitvector} Returns the length of common prefix/suffix of two bitvectors bv1 and bv2.
(bitvector-prefix-length #*1100101001 #*110001101) ⇒ 4 (bitvector-suffix-length #*1100101001 #*110001101) ⇒ 2
[SRFI-178]{gauche.bitvector}
Both arguments must be bitvectors. Returns #t
iff needle is a prefix/suffix of haystack.
(bitvector-prefix? #*101 #*1010100) ⇒ #t (bitvector-prefix? #*101 #*1000110) ⇒ #f (bitvector-suffix? #*110 #*1000110) ⇒ #t (bitvector-suffix? #*110 #*1010100) ⇒ #f
[SRFI-178]{gauche.bitvector} If the length of a bitvector bv is smaller than len, returns a bitvector of length len by adding bit before/after bv. If the length of bv is greater than len, returns a bitvector of length len such that bv left/right bits of bv are trimmed. If the length of bv is equal to len, a copy of bv is returned as is.
(bitvector-pad 1 #*00010 10) ⇒ #*1111100010 (bitvector-pad-right 1 #*00010 10) ⇒ #*0001011111 (bitvector-pad 1 #*0100011 3) ⇒ #*011 (bitvector-pad-right 1 #*0100011 3) ⇒ #*010
[SRFI-178]{gauche.bitvector} Returns a fresh bitvector without preceding and/or trailing consecutive bit from bv.
(bitvector-trim 0 #*000101000) ⇒ #*101000 (bitvector-trim-right 0 #*000101000) ⇒ #*000101 (bitvector-trim-both 0 #*000101000) ⇒ #*101
[SRFI-178]{gauche.bitvector} Swap the i-th value and j-th value of a bitvector bv. Returns an undefined value. If the index is out of range, an error is thrown.
[SRFI-178]{gauche.bitvector} Reverse the order of the content of a bitvector bv destructively. The optional start/end indexes limit the range of the operation; elements outside of the range won’t be affected. Returns an undefined value.
[SRFI-178]{gauche.bitvector}
Same as (bitvector-copy! to start (bitvector-reverse-copy from start end)),
but potentially more efficient.
Returns an undefined value.
[SRFI-178]{gauche.bitvector}
Returns a list of integers (0 or 1) or boolean values of bitvector
bv. The first two procedures returns the leftmost bit first,
while the reverse- variations returns the rightmost bit first.
The optional start/end arguments limit the range of bv
to be extracted.
(bitvector->list/int #*010011000111 2 10) ⇒ (0 0 1 1 0 0 0 1) (reverse-bitvector->list/int #*010011000111 2 10) ⇒ (1 0 0 0 1 1 0 0)
[SRFI-178]{gauche.bitvector}
Like list->bitvector (see Bitvectors), but pack bits
from right to left.
(reverse-list->bitvector '(1 0 #f #f #t #t)) ⇒ #*110001
[SRFI-178]{gauche.bitvector}
Returns a vector of integers (0 or 1) or boolean values of
bitvector bv. The first two procedures returns the leftmost bit first,
while the reverse- variations returns the rightmost bit first.
The optional start/end arguments limit the range of bv
to be extracted.
[SRFI-178]{gauche.bitvector}
Converts vec to a fresh bitvector;
vec must be a vector of 0/1 or boolean values.
The first procedure packs bits in the same left to right order,
while the reverse- version reverses the order.
The optional start/end arguments limit the range of vec
to be extracted.
(vector->bitvector #(0 0 1 1 #t #f #t #t) 2 7) ⇒ #*11101 (reverse-vector->bitvector #(0 0 1 1 #t #f #t #t) 2 7) ⇒ #*10111
[SRFI-178]{gauche.bitvector} Convert between bitvectors and exact nonnegative integers. Note that the leftmost bit of bv corresponds to the least significant bit.
(bitvector->integer #*1000) ⇒ 1 (bitvector->integer #*0001) ⇒ 8
This is consistent with bits->list etc. of SRFI-151
(see scheme.bitwise - R7RS bitwise operations), where least significant bit
corresponts to the first element of the list.
integer->bitvector takes an optional argument len to
specify the number of bits in n (count from the least siginificant
bit) to be taken. When omitted, (integer-length n) is used
(see Basic bitwise operations).
(integer->bitvector 11) ⇒ #*1101 (integer->bitvector 11 8) ⇒ #*11010000
{gauche.bitvector} Returns a generator of integers (0 or 1) and boolean values, respectively. The value is taken from a bitvector bv from left to right. The optional start/end arguments limits the range of the bitvector to be used.
(generator->list (bitvector->int-generator #*10111000)) ⇒ (1 0 1 1 1 0 0 0)
The names are consistent with Gauche convention.
SRFI-178 defines these procedures with the name
make-bitvector/int-generator and make-bitvector/bool-generator.
See gauche.generator - Generators, for the details of generators.
[SRFI-178]{gauche.bitvector}
These are same as bitvector->int-generator and
bitvector->bool-generator except the optional arguments,
and defined in SRFI-178.
{gauche.bitvector} Returns a generator that generates indexes of bv such that the index-th value of bv matches val, which must be either 0, 1 or a boolean value. The bitvector is scanned from left to right. The optional start/end arguments limits the range of the bitvector to be used.
This is handy when you have a bitvector as a bitmap, and want to process something where bit is set (or reset).
(generator->list (bitvector->index-generator #*101110001 1)) ⇒ (0 2 3 4 8)
[SRFI-178]{gauche.bitvector} Returns an accumulator that collects given bits, and returns a bitvector at the end of accumulation.
(let ((a (make-bitvector-accumulator))) (a 1) (a 0) (a 0) (a 1) (a 1) (a (eof-object))) ⇒ #*10011
See scheme.generator - R7RS generators, for the details of accumulators.
[SRFI-178]{gauche.bitvector}
Returns a bitvector whose bits are logical negation of bv.
The linear updating version bitvector-not! may reuse bv to
produce the result.
(bitvector-not #*10100) ⇒ #*01011
[SRFI-178]{gauche.bitvector}
Returns a bitvector whose bits are the result of logical operaion of
corresponding bits of the given bitvectors. All bitvectors must be
the same length.
The linear updating version (procedures with !) may reuse bv1 to
produce the result.
When more than two bitvectors are given to xor and eqv operation, it works left-associatively, that is,
(bitvector-xor a b c) ≡ (bitvector-xor (bitvector-xor a b) c) (bitvector-eqv a b c) ≡ (bitvector-eqv (bitvector-eqv a b) c)
[SRFI-178]{gauche.bitvector} Returns a bitvector, where each bit is the result of logical operation of corresponding bits of bv1 and bv2. Two bitvectors must be the same length.
nand : (not (and bv1 bv2)) nor : (not (or bv1 bv2) andc1 : (and (not bv1) bv2) andc2 : (and bv1 (not bv2)) orc1 : (or (not bv1) bv2) orc2 : (or bv1 (not bv2))
The linear updating version (procedures with !) may reuse bv1 to
produce the result.
[SRFI-178]{gauche.bitvector} Returns a bitvector with the same length of bv, but the content is shifted count bits to the left (when count >= 0) or -count bits to the right (when count < 0). The spilled bits are discarded. The vacated bits are filled with bit.
(bitvector-logical-shift #*101100111000 4 1) ⇒ #*001110001111 (bitvector-logical-shift #*101100111000 -4 0) ⇒ #*000010110011
[SRFI-178]{gauche.bitvector} Returns the number of bit values in bv.
[SRFI-178]{gauche.bitvector} Returns the number of consecutive bit values in bv, starting from index i.
(bitvector-count-run 1 #*11111111100 0) ⇒ 9
[SRFI-178]{gauche.bitvector} All bitvectors must be the same length. Returns a new bitvector with the same length, composed as follows.
The k-th bit of resulting vector is the same as k-th bit
of bv-then if k-th bit of bv-if is #t (1),
otherwise the same as k-th bit of bv-else
[SRFI-178]{gauche.bitvector}
Returns the index of the leftmost bit in bv.
If bv doesn’t have bit, returns -1.
(bitvector-first-bit 1 #*0010011) ⇒ 2 (bitvector-first-bit 0 #*1111111) ⇒ -1
Those procedures operates on a partial field of a bitvector, between start-th bit (inclusive) and end-th bit (exclusive).
[SRFI-178]{gauche.bitvector}
Returns #t iff at least one bit between start and end
in bv is 1.
This is equivalent to (bitvector-any-value? bv 1 start end),
using Gauche’s built-in procedure (see Bitvectors).
[SRFI-178]{gauche.bitvector}
Returns #t iff every bit between start and end
in bv is 1.
This is equivalent to (bitvector-every-value? bv 1 start end),
using Gauche’s built-in procedure (see Bitvectors).
[SRFI-178]{gauche.bitvector} Returns a bitvector with the same content as bv, except the bits between start (inclusive) and end (exclusive) are cleared or set, respectively.
The liner-updating version may mutate bv to produce the result.
(bitvector-field-clear #*10010010101001 2 7) ⇒ #*10000000101001 (bitvector-field-set #*10010010101001 2 7) ⇒ #*10111110101001
[SRFI-178]{gauche.bitvector} Returns a bitvector with the same content as to-bv, except its bits between start (inclusive) and end (exclusive) are replaced with the content of from-bv.
The length of from-bv must be at least end-start. If it is longer, the exceeding bits are ignored.
The liner-updating version may mutate to-bv to produce the result.
(bitvector-field-replace #*10010010101001 #*110011 2 8) ⇒ #*10110011101001
See also bitvector-field-replace-same below.
[SRFI-178]{gauche.bitvector} Returns a bitvector with the same content as to-bv, except its bits between start (inclusive) and end (exclusive) are replaced with the content of from-bv between start and end.
The length of from-bv must be greater than or equal to end.
The liner-updating version may mutate to-bv to produce the result.
(bitvector-field-replace-same #*10010010101001 #*11001100 2 8) ⇒ #*10001100101001
See also bitvector-field-replace above.
[SRFI-178]{gauche.bitvector} Returns a bitvector whose content is the same as bv except the range between start-th bit (inclusive) and end-th bit (exclusive) being rotated by count bits toward right. You can give a negative count to rotate towards left.
(bitvector-field-rotate #*001100110011 1 4 8) ⇒ #*001101100011 (bitvector-field-rotate #*001100110011 -1 4 8) ⇒ #*001110010011
[SRFI-178]{gauche.bitvector} Returns a bitvector whose content is the same as bv except the bits in the range between start-th bit (inclusive) and end-th bit (exclusive) are inverted.
The liner-updating version may mutate to-bv to produce the result.
(bitvector-field-flip #*001100110011 4 8) ⇒ #*001111000011
Next: gauche.cgen - Generating C code, Previous: gauche.base - Importing gauche built-ins, Up: Library modules - Gauche extensions [Contents][Index]