For Gauche 0.9.7

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

### 11.32 `srfi-151` - Bitwise operations

Module: srfi-151

This module provides comprehensive bitwise operations. It is mostly a superset of srfi-60, with some change of names for the consistency and the compatibility (see Integers as bits). We keep srfi-60 for legacy code, while recommend this module to be used in the new code.

The following procedures are Gauche built-in. See Basic bitwise operations, for the description.

```integer-length    copy-bit          bit-field
```

#### Basic operations

Function: bitwise-not n

[SRFI-151] {srfi-151} Returns the bitwise complement of n. Same as builtin `lognot` (see Basic bitwise operations).

Function: bitwise-and n …
Function: bitwise-ior n …
Function: bitwise-xor n …
Function: bitwise-eqv n …

[SRFI-151] {srfi-151} When no arguments are given, these procedures returns `-1`, `0`, `0` and `-1`, respectively. With one arguments, they return the argument as is. With two arguments, they return bitwise and, ior, xor, and eqv (complement of xor). With three or more arguments, they apply binary operations associaively, that is,

```(bitwise-xor a b c)
≡ (bitwise-xor a (bitwise-xor b c))
≡ (bitwise-xor (bitwise-xor a b) c)
```

Be careful that multi-argument `bitwise-eqv` does not produce bit 1 everywhere that all the argument’s bit agree.

The first three procedures are the same as built-in `logand`, `logior` and `logxor`, respectively (see Basic bitwise operations).

Function: bitwise-nand n0 n1
Function: bitwise-nor n0 n1
Function: bitwise-andc1 n0 n1
Function: bitwise-andc2 n0 n1
Function: bitwise-orc1 n0 n1
Function: bitwise-orc2 n0 n1

[SRFI-151] {srfi-151} These operations are not associative.

```nand n0 n1   ≡  (NOT (AND n0 n1))
nor n0 n1    ≡  (NOT (OR n0 n1))
andc1 n0 n1  ≡  (AND (NOT n0) n1)
andc2 n0 n1  ≡  (AND n0 (NOT n1))
orc1 n0 n1   ≡  (OR (NOT n0) n1)
orc2 n0 n1   ≡  (OR n0 (NOT n1))
```

#### Integer operations

Function: arithmetic-shift n count

[SRFI-151] {srfi-151} Shift n for count bits to left; if count is negative, it shifts n to right for -count bits.

Same as builtin `ash` (see Basic bitwise operations).

Function: bit-count n

[SRFI-151] {srfi-151} If n is positive, returns the number of `1`’s in n. If n is negative, returns the number of `0`’s in n.

Same as builtin `logcount` (see Basic bitwise operations).

[SRFI-151] {srfi-151} Returns integer, whose n-th bit is taken as follows: If the n-th bit of mask is 1, the n-th bit of n0; otherwise, the n-th bit of n1.

```(bitwise-if #b10101100 #b00110101 #b11001010)
⇒ #b01100110
```

#### Single-bit operations

Function: bit-set? index n

[SRFI-151] {srfi-151} Returns `#t` or `#f` if index-th bit (counted from LSB) of n is `1` or `0`, respectively.

Same as built-in `logbit?` (see Basic bitwise operations).

Function: bit-swap index1 index2 n

[SRFI-151] {srfi-151} Returns an integer with index1-th bit and index2-th bit are swapped. Index is counted from LSB.

[SRFI-151] {srfi-151} Returns `#t` iff any/all bits set in mask are also set in n.

`any-bit-set?` is the same as built-in `logtest`, except `logtest` accepts one or more arguments (see Basic bitwise operations).

Function: first-set-bit n

[SRFI-151] {srfi-151} Returns the number of factors of two of integer n; that is, returns a maximum `k` such that `(expt 2 k)` divides n without a remainder. It is the same as the index of the least significant `1` in n, hence the alias `first-set-bit`.

```(first-set-bit 0) ⇒ -1   ; edge case
(first-set-bit 1) ⇒ 0
(first-set-bit 2) ⇒ 1
(first-set-bit 15) ⇒ 0
(first-set-bit 16) ⇒ 4
```

This is equivalent to Gauche’s built-in `twos-exponent-factor` (see Basic bitwise operations).

#### Bit field operations

Function: bit-field-any? n start end
Function: bit-field-every? n start end

[SRFI-151] {srfi-151} Returns `#t` iff any/all bits of n from start (inclusive) to end (exclusive) are set.

Function: bit-field-clear n start end
Function: bit-field-set n start end

[SRFI-151] {srfi-151} Returns n with the bits from start (inclusive) to end (exclusive) are set to all `0`’s/`1`’s.

Function: bit-field-replace dst src start end

[SRFI-151] {srfi-151} Returns dst with the bitfield from start to end are replaced with the least-significant (end-start) bits of src.

```(bit-field-replace #b101010 #b010 1 4) ⇒ #b100100
```

Same as built-in `copy-bit-field` (see Basic bitwise operations).

Function: bit-field-replace-same dst src start end

[SRFI-151] {srfi-151} Returns dst with the bitfield from start to end are replaced with the `src`’s bitfield from start to end.

```(bit-field-replace-same #b111111 #b100100 1 4) ⇒ #b110101
```
Function: bit-field-rotate n count start end

[SRFI-151] {srfi-151} Rotate the region of n between start-th bit (inclusive) and end-th bit (exclusive) by count bits to the left. If count is negative, it rotates to the right by -count bits.

```(bit-field-rotate #b110100100010000 -1 5 9)
⇒ 26768 ;#b110100010010000

(bit-field-rotate #b110100100010000 1 5 9)
⇒ 26672 ;#b110100000110000
```
Function: bit-field-reverse n start end

[SRFI-151] {srfi-151} Reverse the order of bits of n between start-th bit (inclusive) and end-th bit (exclusive).

```(bit-field-reverse #b10100111 0 8)
⇒ 229 ; #b11100101
```

#### Bits conversion

Function: bits->list n :optional len
Function: bits->vector n :optional len

[SRFI-151] {srfi-151} Returns a list/vector of booleans of length len, corresponding to each bit in non-negative integer n, LSB-first. When len is omitted, `(integer-length n)` is used.

```(bits->vector #b101101110)
⇒ #(#f #t #t #t #f #t #t #f #t)
```

Note: Srfi-60 has a similar `integer->list`, but the order of bits is reversed.

Function: list->bits bool-list
Function: vector->bits bool-vector

[SRFI-151] {srfi-151} Returns an exact integer formed from boolean values in given list/vector, LSB first. The result will never be negative.

```(list->bits '(#f #t #t #t #f #t #t #f #t))
⇒ #b101101110
```

Note: Srfi-60 has a similar `list->integer`, but the order of bits is reversed.

Function: bits bool …

[SRFI-151] {srfi-151} Returns the integer coded by bools, LSB first. The result will never be negative.

```(bits #f #t #t #t #f #t #t #f #t)
⇒ #b101101110
```

Note: Srfi-60 has a similar `booleans->integer`, but the order of bits is reversed.

#### Fold, unfold and generate

Function: bitwise-fold kons knil n

[SRFI-151] {srfi-151} Traverse bits in integer n from LSB to the `(integer-length n)` bit, applying `kons` on the bit as boolean and the seed value, whose initial value is given by knil. Returns the last result of kons.

```(bitwise-fold cons '() #b10110111)
⇒ (#t #f #t #t #f #t #t #t)
```
Function: bitwise-for-each proc n

[SRFI-151] {srfi-151} Applies proc to the bit as boolean in n, from LSB to the `(integer-length n)` bit. The result is discarded.

Function: bitwise-unfold p f g seed

[SRFI-151] {srfi-151} Generates a non-negative integer bit by bit, from LSB to MSB. The seed gives the initial state value. For each iteration, p is applied to the current state value, and if it returns a true value, the iteration ends and `bitwise-unfold` returns the accumulated bits as an integer. Otherwise, f is applied to the current state value, and its result, coerced to a boolean value, determines the bit value. Then g is applied to the current state value to produce the next state value of the next iteration.

The following expression produces a bitfield of width 100, where n-th bit indicates whether n is prime or not:

```(use math.prime)
(bitwise-unfold (cut = 100 <>)
small-prime?
(cut + 1 <>)
0)
```
Function: make-bitwise-generator n

[SRFI-151] {srfi-151} Returns a generator that generates boolean values corresponding to the bits in n, LSB-first. The returned generator is infinite.

This is similar to `bits->generator` in `gauche.generator`, except that the generator created by it stops at the integer length of n (see Generators).

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