►Rebellion
▼6 Binary Data
On this page:
bitstring?
bitstring
empty-bitstring
bitstring-ref
bitstring-size
in-bitstring
into-bitstring
for/  bitstring
for*/  bitstring
bitstring->padded-bytes
bytes->bitstring
sequence->bitstring
8.16.0.1
  top  contents    up   

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

value

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

value

into-bitstring : (reducer/c bit? bitstring?)

A reducer that collects a sequence of bits into a bitstring.

Example:
> (transduce (list 1 0 0 1 0 1)
             #:into into-bitstring)

(bitstring 1 0 0 1 0 1)

syntax

(for/bitstring (for-clause ...) body-or-break ... body)

 
  body : bit?
Iterates like for, but collects each body result (which must be a bit?) into a bitstring.

Example:
> (for/bitstring ([bit (in-list (list 1 0 0 1 0 1 0 1))])
    bit)

(bitstring 1 0 0 1 0 1 0 1)

syntax

(for*/bitstring (for-clause ...) body-or-break ... body)

 
  body : bit?
Iterates like for*, but collects each body result (which must be a bit?) into a bitstring.

Example:
> (for*/bitstring ([byte (in-bytes #"hi")]
                   [bit (in-byte byte)])
    bit)

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

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)

procedure

(sequence->bitstring seq) → bitstring?

  seq : (sequence/c bit?)
Converts seq into a bitstring by converting each 1 or 0 into a bit.

Examples:
> (sequence->bitstring (list 1 0 1 1))

(bitstring 1 0 1 1)

> (sequence->bitstring (vector 0 1 1 0))

(bitstring 0 1 1 0)

  top  contents    up