HELP BITVECTORS                                  John Williams, Oct 1986
                                               Updated A.Sloman May 1990

The package LIB * BITVECTORS creates a data class "bitvector" - vector
type objects whose elements may be either 1 or 0. This data type
corresponds to the Common Lisp type SIMPLE-BIT-VECTOR.

The following functions are provided for creating and accessing
bitvectors:

    consbitvector(<integer:N>) -> <bitvector>
        Constructs a bit vector from the top N items on the stack

    destbitvector(<bitvector>)
        Stacks the elements and length of <bitvector>

    initbitvector(<integer:N>) -> <bitvector>
        Creates a <bitvector> of length N, whose elements are all 0

    isbitvector(<item>) -> <boolean>
        -true- if <item> is a bitvector, -false- otherwise

    subscrbitvector(<integer:I>, <bitvector:B>) -> <1 | 0>
        <1 | 0> -> subscrbitvector(<integer:I>, <bitvector:B>)
        Returns/updates the I'th bit in B

    fast_subscrbitvector(<integer:I>, <bitvector:B>) -> <1 | 0>
        <1 | 0> -> fast_subscrbitvector(<integer:I>, <bitvector:B>)
        Fast, non-checking version of -subscrbitvector-

    bitvector_key -> <key>
        Constant: the key of bitvector type objects


-- Examples ------------------------------------------------------------

    lib bitvectors;  ;;; Make the package available

    vars bv = consbitvector(1, 0, 1, 0, 1, 5);

    bv =>
    ** <bitvector 10101>

    destbitvector(bv) =>
    ** 1 0 1 0 1 5

    explode(bv) =>

    fill(0,0,0,0,1, bv) =>
    ** <bitvector 00001>

    bv =>
    ** <bitvector 00001>

    isbitvector(bv) =>
    ** <true>

    1 -> subscrbitvector(2, bv);
    bv =>
    ** <bitvector 01001>

    datakey(bv) == bitvector_key =>
    ** <true>

    ;;; create a bitvector of length 100 with 1 in ith position only
    ;;; if 13 divides i.
    vars i, newbv;
    cons_with consbitvector
        {%
            for i from 1 to 100 do
                if i mod 13 == 0 then 1 else 0 endif
            endfor
         %} -> newbv;

    newbv =>
    ** <bitvector 0000000000001000000000000100000000000010000000000001000
        000000000100000000000010000000000001000000000>

Bitvectors are indexable by number
    newbv(39) =>
    ** 1


-- See also ------------------------------------------------------------

HELP * VECTORS
HELP * VECTORCLASS
 REF * VECTORS
 REF * DATA
 REF * VMCODE/sysFIELD

--- C.all/help/bitvectors
--- Copyright University of Sussex 1990. All rights reserved. ----------