Documentation for package rsm.bitcomp

Author : R. Scott McIntire

Version: 1.0

Overview:

Overview: This package provides a set of functions to 
create, and perform boolean operations on compressed bit strings.
Effectively, a run length encoding of bits is used as a representation.

REQUIRES: package rsm.queue.

REPRESENTATION DESCRIPTION: 
Operations on compressed bit strings.
The representation of compressed bit strings is 
of the form '((start1 . duration1) (start2 . duration2)...).

Example: The compressed bit string 
         '((1 . 3) (6 . 2) (10 . 4))
         is interpreted to mean the bit string:
         1 1 1 0 0 1 1 0 0 1 1 1 1
         That is, the first three bits are 1, 
         bits 6 and 7 are 1, and bits 10 through 13 are 1.


A compressed bit string may be created using the constructor make-compressed 
with 4 key words: :list, :number, :comp, and :rep.

Example: Example bit string constructions and the resulting compressed pairs:
         Note: Compressed pairs are not what is returned by make-compressed
               but representative of the returned structure.

(rsm.bitcomp:make-compressed :list '(0 1 0 0 1 1 1 0 0 1))
  ((2 . 1) (5 . 3) (10 . 1))

(rsm.bitcomp:make-compressed :number 11)  ; The bits of 11 are considered 
                                          ; running from lowest to highest.
  ((1 . 2) (4 . 1))

(rsm.bitcomp:make-compressed :comp '((1 . 2) (2 . 3))) ; Make from compressed 
                                                       ; pairs.
  ((1 . 4))

(rsm.bitcomp:make-compressed :rep '(((1 . 2) (4 . 3)) (4 . 3)) ; Make from 
                                                             ; compressed queue.
  ((1 . 2) (4 . 3))

  Note: Use get-compressed-pairs to return a list of compressed pairs from 
  a object of type compressed-p.
  
Export Summary:
  
and: And zero or more compressed bit strings.
or : Or zero or more compressed bit strings.
not: Negate a compressed bit string.
xor: Xor zero or more compressed bit strings.

get-number-of-bits   : The the number of bits which are 1.
get-compressed-pairs : Get the list of compressed pairs.
make-compressed      : Make a compressed bit-string structure.
compressed-p         : Is an object a compressed structure?

and   (&rest reps)

Computes the representation of the ANDING of <reps>.

Example: (rsm.bitcomp:and rep1 rep2) 
          where rep1 represents '((1 . 3) (5 . 2))
          and rep2 represents '((4 . 2) (10 . 2))
          yields ((5 . 1)).
          (actually a compressed type which has this as a
           run length encoded list.)

compressed-data   (struct)

nil

compressed-p   (object)

nil

get-compressed-pairs   (compressed &key (fresh t))

Get the list of compressed pairs that represent the compressed bit string
<compressed>. If <fresh> is true, make a copy of the list; otherwise, the 
internal list of compressed pairs is returned.

get-number-of-bits   (rep)

Get the number of bits in the representation <rep>.

not   (begin end rep)

Computes the new representation of the COMPLEMENT of <rep> in the range 
 [begin, end].
 Example: (rsm.bitcomp:not 0 11 rep)
           where rep represents '((2 . 1) (5 . 3) (10 . 1))
           yields '((0 . 2) (3 . 2) (8 . 2) (11 . 1)).
          (actually a compressed type which has this as a
           run length encoded list.)

or   (&rest reps)

Computes the representation of the ORING of <reps>.

Example: (rsm.bitcomp:or rep1 rep2) 
          where rep1 represents '((1 . 3) (5 . 2)) 
          and rep2 represents '((4 . 2) (10 . 2))
          yields ((1 . 6) (10 . 2)).
          (actually a compressed type which has this as a
           run length encoded list.)

xor   (&rest reps)

Computes the representation of the XORING of <reps>.

Example: (rsm.bitcomp:xor rep1 rep2) 
          where rep1 represents '((1 . 3) (5 . 2))
          and rep2 represents '((4 . 2) (10 . 2))
          yields '((1 . 4) (6 . 1) (10 . 2)).
          (actually a compressed type which has this as a
           run length encoded list.)