Next: String library (reduced), Previous: Mappings and hashmaps, Up: Library modules - SRFIs [Contents][Index]

`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

- 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))

- 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).

- Function:
**bitwise-if***mask n0 n1* [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

- 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.

- Function:
**any-bit-set?***mask n* - Function:
**every-bit-set?***mask n* [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).

- 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

- 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`bool`s, 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.

- 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).