On this page:
make-bit-vector
bit-vector
bit-vector?
bit-vector-ref
bit-vector-set!
bit-vector-length
bit-vector-popcount
bit-vector-copy
in-bit-vector
for/  bit-vector
for*/  bit-vector
bit-vector->list
list->bit-vector
bit-vector->string
string->bit-vector
7.8

9 Bit Vectors

Jens Axel Søgaard <soegaard@racket-lang.org>

 (require data/bit-vector) package: base

A bit vector is a mutable sequence whose elements are booleans. A bit vector also acts as a dictionary (dict? from racket/dict), where the keys are zero-based indexes and the values are the elements of the bit-vector. A bit-vector has a fixed size.

Two bit-vectors are equal? if they contain the same number of elements and if they contain equal elements at each index.

procedure

(make-bit-vector size [fill])  bit-vector?

  size : exact-integer?
  fill : boolean? = #f
Creates a new bit-vector of size size. All elements are initialized to fill.

Examples:

procedure

(bit-vector elem ...)  bit-vector?

  elem : boolean?
Creates a new bit-vector containing each elem in order.

Example:
> (bit-vector-ref (bit-vector #f #t #f) 1)

#t

procedure

(bit-vector? v)  boolean?

  v : any/c
Returns #t if v is a bit-vector, #f otherwise.

procedure

(bit-vector-ref bv index [default])  any/c

  bv : bit-vector?
  index : exact-nonnegative-integer?
  default : any/c = (error ....)
Returns the element at index index, if index is less than (bit-vector-length bv). Otherwise, default is invoked if it is a procedure, returned otherwise.

Examples:
> (bit-vector-ref (bit-vector #f #t) 1)

#t

> (bit-vector-ref (bit-vector #f #t) 5 'not-there)

'not-there

procedure

(bit-vector-set! bv index value)  void?

  bv : bit-vector?
  index : 
(and/c exact-nonnegative-integer?
       (</c (+ 1 (bit-vector-length vv))))
  value : boolean?
Sets the value at index index to be value.

Examples:
> (define bv (bit-vector #f #t))
> (bit-vector-ref bv 0)

#f

> (bit-vector-set! bv 0 #t)
> (bit-vector-ref bv 0)

#t

Returns the number of items in the bit-vector bv.

Returns the number of set bits in the bit-vector bv.

Example:
> (bit-vector-popcount (bit-vector #f #t #t))

2

procedure

(bit-vector-copy bv [start end])  bit-vector?

  bv : bit-vector?
  start : exact-nonnegative-integer? = 0
  end : exact-nonnegative-integer? = (vector-length v)
Creates a fresh bit-vector with the same elements as bv from start (inclusive) to end (exclusive).

procedure

(in-bit-vector bv)  sequence?

  bv : bit-vector?
Returns a sequence whose elements are the elements of the bit-vector bv. Mutation of bv while the sequence is running changes the elements produced by the sequence. To obtain a sequence from a snapshot of bv, use (in-bit-vector (bit-vector-copy bv)) instead.

Examples:
> (define bv (bit-vector #f #t #f))
> (for/list ([x (in-bit-vector bv)]) x)

'(#f #t #f)

syntax

(for/bit-vector maybe-length (for-clause ...)
  body-or-break ... body)
 
maybe-length = 
  | #:length length-expr
  | #:length length-expr #:fill fill-expr
 
  length-expr : exact-nonnegative-integer?
Iterates like for/vector, but results are accumulated into a bit-vector instead of a vector.

If the optional #:length clause is specified, the result of length-expr determines the length of the result bit-vector. In that case, the iteration can be performed more efficiently, and it terminates when the bit-vector is full or the requested number of iterations have been performed, whichever comes first. If length-expr specifies a length longer than the number of iterations, then the remaining slots of the vector are initialized to the value of fill-expr, which defaults to #f (i.e., the default argument of make-bit-vector).

Examples:
> (bit-vector->list
   (for/bit-vector ([i '(1 2 3)]) (odd? i)))

'(#t #f #t)

> (bit-vector->list
   (for/bit-vector #:length 2 ([i '(1 2 3)]) (odd? i)))

'(#t #f)

> (bit-vector->list
   (for/bit-vector #:length 4 ([i '(1 2 3)]) (odd? i)))

'(#t #f #t #f)

> (bit-vector->list
   (for/bit-vector #:length 4 #:fill #t ([i '(1 2 3)]) (odd? i)))

'(#t #f #t #t)

The for/bit-vector form may allocate a bit-vector and mutate it after each iteration of body, which means that capturing a continuation during body and applying it multiple times may mutate a shared bit-vector.

syntax

(for*/bit-vector maybe-length (for-clause ...)
  body-or-break ... body)
Like for/bit-vector but with the implicit nesting of for*.

procedure

(bit-vector->list bv)  (listof boolean?)

  bv : bit-vector?

procedure

(list->bit-vector bits)  bit-vector?

  bits : (listof boolean?)

procedure

(bit-vector->string bv)  (and/c string? #rx"^[01]*$")

  bv : bit-vector?

procedure

(string->bit-vector s)  bit-vector?

  s : (and/c string? #rx"^[01]*$")
Converts between bit-vectors and their representations as lists and strings.

Examples:
> (bit-vector->list (string->bit-vector "100111"))

'(#t #f #f #t #t #t)

> (bit-vector->string (list->bit-vector '(#t #f #t #t)))

"1011"