For Gauche 0.9.10

Next: , Previous: , Up: Library modules - SRFIs   [Contents][Index]

### 11.34 `srfi-178` - Bitvector library

Module: srfi-178

Gauche supports bitvectors as a native type, but the core library only offers a handful of primitives. This module complements the comprehensive operations on bitvectors.

The following procedures are built-in. See Bitvectors, for the description.

```bit->integer      bit->boolean
bitvector         make-bitvector     list->bitvector
bitvector?        bitvector-length
string->bitvector bitvector->string
bitvector-ref/int bitvector-ref/bool
bitvector-set!    bitvector-copy     bitvector-copy!
```

#### Constructors

Function: bitvector-unfold f length seed …
Function: bitvector-unfold-right f length seed …

[SRFI-178] {srfi-178} 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 first 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 R7RS vectors), and has a different protocol from other `unfold` procedures (see R7RS lists).

Function: bitvector-reverse-copy bv :optional start end

[SRFI-178] {srfi-178} 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
```
Function: bitvector-append bv …

[SRFI-178] {srfi-178} All arguments must be bytevectors. Returns a fresh bytevector which is concatenation of all arguments.

Function: bitvector-concatenate bvs

[SRFI-178] The argument must be a list of bytevectors. Returns a fresh bytevector which is concatenation of all arguments. {srfi-178}

Function: bitvector-append-subbitvectors bv start end …

[SRFI-178] {srfi-178} 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.

#### Predicates

Function: bitvector-emtpy? bv

[SRFI-178] {srfi-178} Returns `#t` iff bv is an empty bytevector.

Function: bitvector=? bv …

[SRFI-178] {srfi-178} Returns `#t` iff all the bytevectors have the same content. If there’s zero or one argument, it returns `#t`.

#### Iteration

Function: bitvector-take bv n
Function: bitvector-take-right bv n

[SRFI-178] {srfi-178} 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 Sequence framework.

Function: bitvector-drop bv n
Function: bitvector-drop-right bv n

[SRFI-178] {srfi-178} 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 Sequence framework.

Function: bitvector-segment bv n

[SRFI-178] {srfi-178} 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.

Function: bitvector-fold/int kons knil bv1 bv2 …
Function: bitvector-fold/bool kons knil bv1 bv2 …
Function: bitvector-fold-right/int kons knil bv1 bv2 …
Function: bitvector-fold-right/bool kons knil bv1 bv2 …

[SRFI-178] {srfi-178} 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 R7RS vectors). (Note that list `fold` procedure calls the knil procedure with different order; see Walking over lists).

All bitvectors must have the same length; otherwise, an error is thrown.

Function: bitvector-map/int f bv1 bv2 …
Function: bitvector-map/bool f bv1 bv2 …

[SRFI-178] {srfi-178} Apply a procedure f over each element taken from given bitvectors. The result of the procedure is gathered as a fresh bitvector and returned.

All bitvectors must have the same length; otherwise, an error is thrown.

Function: bitvector-map!/int f bv1 bv2 …
Function: bitvector-map!/bool f bv1 bv2 …

[SRFI-178] {srfi-178} 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.

All bitvectors must have the same length; otherwise, an error is thrown.

Function: bitvector-map->list/int f bv1 bv2 …
Function: bitvector-map->list/bool f bv1 bv2 …

[SRFI-178] {srfi-178} 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.

Function: bitvector-for-reach/int f bv1 bv2 …
Function: bitvector-for-reach/bool f bv1 bv2 …

[SRFI-178] {srfi-178} 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.

#### Prefixes, suffixes, trimming and padding

Function: bitvector-prefix-length bv1 bv2
Function: bitvector-suffix-length bv1 bv2

[SRFI-178] {srfi-178} 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
```
Function: bitvector-prefix? needle haystack
Function: bitvector-suffix? needle haystack

[SRFI-178] {srfi-178} 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] {srfi-178} 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 equal to or greater than len, bv is returned as is.

```(bitvector-pad 1 #*00010 10) ⇒ #*1111100010
(bitvector-pad-right 1 #*00010 10) ⇒ #*0001011111
```
Function: bitvector-trim bit bv
Function: bitvector-trim-right bit bv
Function: bitvector-trim-both bit bv

[SRFI-178] {srfi-178} Returns a 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
```

#### Mutators

Function: bitvector-swap! bv i j

[SRFI-178] {srfi-178} Swap the i-th value and j-th value of a bitvector bv. If the index is out of range, an error is thrown.

Function: bitvector-reverse! bv :optional start end

[SRFI-178] {srfi-178} 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.

Function: bitvector-reverse-copy! to tstart from :optional start end

[SRFI-178] {srfi-178} Same as `(bitvector-copy! to start (bitvector-reverse-copy from start end))`, but potentially more efficient.

#### Conversion

Function: bitvector->list/int bv :optional start end
Function: bitvector->list/bool bv :optional start end
Function: reverse-bitvector->list/int bv :optional start end
Function: reverse-bitvector->list/bool bv :optional start end

[SRFI-178] {srfi-178}

Function: reverse-list->bitvector lis

[SRFI-178] {srfi-178}

Function: bitvector->vector/int bv :optional start end
Function: bitvector->vector/bool bv :optional start end
Function: revrese-bitvector->vector/int bv :optional start end
Function: reverse-bitvector->vector/bool bv :optional start end

[SRFI-178] {srfi-178}

Function: vector->bitvetor vec :optional start end
Function: reverse-vector->bitvector vec :optional start end

[SRFI-178] {srfi-178}

Function: bitvector->integer bv
Function: integer->bitvector n :optional len

[SRFI-178] {srfi-178}

#### Generators

Function: make-bitvector/int-generator bv
Function: make-bitvector/bool-generator bv

[SRFI-178] {srfi-178}

Function: make-bitvector-accumulator

[SRFI-178] {srfi-178}

#### Bitwise operations

Function: bitvector-not bv
Function: bitvector-not! bv

[SRFI-178] {srfi-178}

Function: bitvector-and bv1 bv2 bv …
Function: bitvector-and! bv1 bv2 bv …
Function: bitvector-ior bv1 bv2 bv …
Function: bitvector-ior! bv1 bv2 bv …
Function: bitvector-xor bv1 bv2 bv …
Function: bitvector-xor! bv1 bv2 bv …
Function: bitvector-eqv bv1 bv2 bv …
Function: bitvector-eqv! bv1 bv2 bv …

[SRFI-178] {srfi-178}

Function: bitvector-nand bv1 bv2
Function: bitvector-nand! bv1 bv2
Function: bitvector-nor bv1 bv2
Function: bitvector-nor! bv1 bv2
Function: bitvector-andc1 bv1 bv2
Function: bitvector-andc1! bv1 bv2
Function: bitvector-andc2 bv1 bv2
Function: bitvector-andc2! bv1 bv2
Function: bitvector-orc1 bv1 bv2
Function: bitvector-orc1! bv1 bv2
Function: bitvector-orc2 bv1 bv2
Function: bitvector-orc2! bv1 bv2

[SRFI-178] {srfi-178}

#### Quasi-integer operations

Function: bitvector-logical-shift bv count bit

[SRFI-178] {srfi-178}

Function: bitvector-count bit bv

[SRFI-178] {srfi-178}

Function: bitvector-count-run bit bv start

[SRFI-178] {srfi-178}

Function: bitvector-if bv-if bv-then bv-else

[SRFI-178] {srfi-178}

Function: bitvector-first-bit bit bv

[SRFI-178] {srfi-178}

#### Bit field operations

Function: bitvector-field-any? bv start end

[SRFI-178] {srfi-178}

Function: bitvector-field-every? bv start end

[SRFI-178] {srfi-178}

Function: bitvector-field-clear bv start end
Function: bitvector-field-clear! bv start end
Function: bitvector-field-set bv start end
Function: bitvector-field-set! bv start end

[SRFI-178] {srfi-178}

Function: bitvector-field-replace to from start end
Function: bitvector-field-replace! to from start end

[SRFI-178] {srfi-178}

Function: bitvector-field-replace-same to from start end
Function: bitvector-field-replace-same! to from start end

[SRFI-178] {srfi-178}

Function: bitvector-field-rotate bv count start end

[SRFI-178] {srfi-178}

Function: bitvector-field-flip bv start end
Function: bitvector-field-flip! bv start end

[SRFI-178] {srfi-178}

Next: , Previous: , Up: Library modules - SRFIs   [Contents][Index]