On this page:
bitstring?
bitstring
empty-bitstring
bitstring-ref
bitstring-size
in-bitstring
bitstring->padded-bytes
bytes->bitstring
7.4

5.2 Bitstrings

 (require rebellion/binary/bitstring) package: rebellion

A bitstring is an immutable, contiguous sequence of bits. Bitstrings are represented compactly; a bitstring of 8N bits consumes N bytes of memory, plus some constant overhead. Bitstrings implement the sequence interface.

procedure

(bitstring? v)  boolean?

  v : any/c
A predicate for bitstrings.

procedure

(bitstring b ...)  bitstring?

  b : bit?
Constructs a bitstring containing the given bits.

Examples:
> (bitstring 1 0 0 1 0)

(bitstring 1 0 0 1 0)

> (bitstring 0 0 0 0 0 0 0 0
             1 1 1 1 1 1 1 1
             0 1 0 1 0 1 0 1
             0 1 1)

(bitstring 0 0 0 0 0 0 0 0 1 1 1 1 1 1 1 1 0 1 0 1 0 1 0 1 0 1 1)

> (bitstring)

(bitstring)

The empty bitstring.

procedure

(bitstring-ref bits pos)  bit?

  bits : bitstring?
  pos : (integer-in 0 (bitstring-size bits))
Returns the bit at pos in bits.

Examples:
> (define bits (bitstring 1 1 1 0 0 1 0 0 0 1 1))
> (bitstring-ref bits 0)

1

> (bitstring-ref bits 5)

1

> (bitstring-ref bits 6)

0

> (bitstring-ref bits 8)

0

procedure

(bitstring-size bits)  natural?

  bits : bitstring?
Returns the number of bits in bits. Note that bitstrings can have sizes that are not multiples of eight.

Examples:
> (bitstring-size (bitstring))

0

> (bitstring-size (bitstring 1 1 1 1 0 0 0 0))

8

> (bitstring-size (bitstring 1 1 1 1 0 0 0 0 1))

9

procedure

(in-bitstring bits)  (sequence/c bit?)

  bits : bitstring?
Returns a sequence that traverses each bit in bits. Note that bitstrings already implement the sequence interface, but using this function in a for comprehension may improve performance and error messages over using bits directly.

Example:
> (for ([position (in-naturals)]
        [bit (in-bitstring (bitstring 1 1 0 0 1 0 1 0 0 1))]
        #:unless (zero? bit))
    (printf "Bit ~a is set\n" position))

Bit 0 is set

Bit 1 is set

Bit 4 is set

Bit 6 is set

Bit 9 is set

procedure

(bitstring->padded-bytes bits)  immutable-bytes?

  bits : bitstring?
Returns an immutable byte string where each byte corresponds to eight bits of bits. If bits has a size that is not a multiple of eight, the last byte is constructed by adding zeros to the end of bits until the size is a multiple of eight. This is a constant-time operation.

Examples:
> (bitstring->padded-bytes (bitstring 0 0 0 0 0 1 1 1))

#"\a"

> (bitstring->padded-bytes (bitstring 0 0 0 0 0 1 1 1 1))

#"\a\200"

procedure

(bytes->bitstring bstr [#:padding padding])  bitstring?

  bstr : immutable-bytes?
  padding : (integer-in 0 7) = 0
Converts bstr into a bitstring by converting each of its bytes into eight bits. The last padding bits are ignored, which allows constructing bitstrings with sizes that are not a multiple of eight.

Examples:
> (bytes->bitstring #"apple")

(bitstring

 0

 1

 1

 0

 0

 0

 0

 1

 0

 1

 1

 1

 0

 0

 0

 0

 0

 1

 1

 1

 0

 0

 0

 0

 0

 1

 1

 0

 1

 1

 0

 0

 0

 1

 1

 0

 0

 1

 0

 1)

> (bytes->bitstring #"Apple")

(bitstring

 0

 1

 0

 0

 0

 0

 0

 1

 0

 1

 1

 1

 0

 0

 0

 0

 0

 1

 1

 1

 0

 0

 0

 0

 0

 1

 1

 0

 1

 1

 0

 0

 0

 1

 1

 0

 0

 1

 0

 1)