BITSETS(3X)

NAME
bitsets - bit vector represented sets definitions

SYNOPSIS
#include bitsets.f83

bitsets

DESCRIPTION
Allows definition and manipulation of bit vector represented sets. A set may contain maximum of 32 items as it is maintained as a stack item. All set operations are performed as logic functions; "and", "or", etc. This gives rapid manipulation of small sets. Most set operations require only one logic operation.

: .bitset ( bitset -- ) immediate
    Used in the following form:
    <bitset> .bitset <bitset-type-name>
    to display the bitset values in the following normal set notation:
    { <entries> }
    The bitset type is required to map the items back to their corresponding entries. It maintains the list of items defined in the universe set.

: >item ( item -- entry) immediate
    Used in the following form:
    <item> >item <bitset-type-name> ( item -- entry)
    to map an item value back to the corresponding entry given the bitset type name. The bitset type maintains the list of items defined in the universe set.

: ?empty-bitset ( bitset -- bool) macro
    Returns "true" if the bitset is an empty set else "false".

: ?map-bitset ( bitset block[ item -- bool] -- )
    Conditional iterator on a bitset. The block is called for each item in the set while the block returns "false". Should the block return "true" the iterator is terminated.

: ?member-bitset ( item bitset -- bool) macro
    Returns "true" if the item is a member of the bitset else "false".

: append-bitset ( item bitset1 -- bitset2) macro
    Returns the result of appending the item to the bitset.

: bitset.end ( -- )
    Used in the following form:
    bitset.type <bitset-type-name> ( -- )
    { item <bitset-item-name> ( -- item) }
    bitset.end
    to terminate a bitset type definition. The bitset should not contain more than 32 items as a set value is represented by a 32-bit integer number (on stack).

: bitset.type ( -- )
    Used in the following form:
    bitset.type <bitset-type-name> ( -- )
    { item <bitset-item-name> ( -- item) }
    bitset.end
    to initiate the definition of a bitset type. The bitset may contain at most 32 items as a set value is represented as a 32-bit integer on stack and in memory. The bitset type may be used in the following form:
    <bitset-type-name> <bitset-variable-name> ( -- addr)
    to create a bitset variable (and which acts as a normal "variable").

vocabulary bitsets ( -- )
    The bitset extension vocabulary. Include into the vocabulary search structure, "context", to allow access to this library.

: difference-bitset ( bitset1 bitset2 -- bitset3) macro
    Returns the resulting "bitset3" after removing "bitset2" from "bitset1".

constant empty-bitset ( -- bitset)
    Returns the empty bitset. For a bit vector representation of sets the empty set the value is zero.

: intersection-bitset ( bitset1 bitset2 -- bitset3) macro
    Returns the intersection, "bitset3", between the sets "bitset2" and "bitset1".

: item ( -- )
    Used in the following form:
    bitset.type <bitset-type-name> ( -- )
    { item <bitset-item-name> ( -- item) }
    bitset.end
    to create a bitset item. When the item is used it will return the item value on the parameter stack. A bitset may contain at most 32 items as each item corresponds to an unique bit in a 32-bit integer stack element.

: map-bitset ( bitset block[ item -- ] -- )
    Bitset iterator function. The code block is called on each item in the bitset. The code block may be created with the extension library "blocks". The block will receive the item as parameter.

: remove-bitset ( item bitset1 -- bitset2) macro
    Returns the resulting bitset after removing the item from the bitset.

: size-bitset ( bitset -- num)
    Returns the size of the bitset, i.e., the number of items in the set.

: union-bitset ( bitset1 bitset2 -- bitset3) macro
    Returns the union, "bitset3", between the sets "bitset2" and "bitset1".

: { ( -- ) immediate
    Used in the following form:
    { <items> } ( -- bitset)
    to start the definition of a bitset. The brackets should only contain item entries.

: } ( -- bitset)
    Used in the following form:
    { <items> } ( -- bitset)
    to end a bitset definition. The brackets should only contain item entries.

INTERNALS
Private definitions in the bitsets vocabulary;

: (.bitset) ( bitset bitset.type -- ) private
    Performs the run-time action of displaying the bitset given the mapping set of entries. Compiled by the word ".bitset".

: (>item) ( item bitset.type -- entry) private
    Performs the run-time action of locating an item entry given its bitset value. Returns the "entry" pointer or "nil" if not found. Compiled by the word ">item".

SEE ALSO
tile(1), forth(3X), macros(3X), blocks(3X).

NOTE
The function list is sorted in ASCII order. The type and mode of the entry is indicated together with the parameter stack effect.

COPYING
Copyright (C) 1990 Mikael R.K. Patel

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU General Public License" may be included in a translation approved by the author instead of in the original English.

AUTHOR
Mikael R.K. Patel
Computer Aided Design Laboratory (CADLAB)
Department of Computer and Information Science
Linkoping University
S-581 83 LINKOPING
SWEDEN
Email: mip@ida.liu.se