s48-refman/library/mask.texi

@node Boxed bitwise-integer masks
@section Boxed bitwise-integer masks

@stindex mask-types
@stindex masks
Scheme48 provides a facility for generalized boxed bitwise-integer
masks.  Masks represent sets of elements.  An element is any arbitrary
object that represents an index into a bit mask; mask types are
parameterized by an isomorphism between elements and their integer
indices.  Usual abstract set operations are available on masks.  The
mask facility is divided into two parts: the @code{mask-types}
structure, which provides the operations on the generalized mask type
descriptors; and the @code{masks} structure, for the operations on
masks themselves.

@subsection Mask types

@deffn procedure make-mask-type name elt? index->elt elt->index size @returns{} mask-type
@deffnx procedure mask-type? object @returns{} boolean
@deffnx procedure mask? object @returns{} boolean
@code{Make-mask-type} constructs a mask type with the given name.
Elements of this mask type must satisfy the predicate @var{elt?}.
@var{Integer->elt} is a unary procedure that maps bit mask indices to
possible set elements; @var{elt->integer} maps possible set elements to
bit mask indices.  @var{Size} is the number of possible elements of
masks of the new type, @ie{} the number of bits needed to represent the
internal bit mask.  @code{Mask?} is the disjoint type predicate for
mask objects.
@end deffn

@deffn procedure mask-type mask @returns{} mask-type
@deffnx procedure mask-has-type? mask type @returns{} boolean
@code{Mask-type} returns @var{mask}'s type.  @code{Mask-has-type?}
returns @code{#t} if @var{mask}'s type is the mask type @var{type} or
@code{#f} if not.
@end deffn

The @code{mask-types} structure, not the @code{masks} structure,
exports @code{mask?} and @code{mask-has-type?}: it is expected that
programmers who implement mask types will define type predicates for
masks of their type based on @code{mask?} and @code{mask-has-type?},
along with constructors @etc{} for their masks.

@deffn procedure integer->mask type integer @returns{} mask
@deffnx procedure list->mask type elts @returns{} mask
@code{Integer->mask} returns a mask of type @var{type} that contains
all the possible elements @var{e} of the type @var{type} such that
the bit at @var{e}'s index is set.  @code{List->mask} returns a mask
whose type is @var{type} containing all of the elements in the list
@var{elts}.
@end deffn

@subsection Masks

@deffn procedure mask->integer mask @returns{} integer
@deffnx procedure mask->list mask @returns{} element-list
@code{Mask->integer} returns the integer bit set that @var{mask} uses
to represent the element set.  @code{Mask->list} returns a list of all
the elements that @var{mask} contains.
@end deffn

@deffn procedure mask-member? mask elt @returns{} boolean
@deffnx procedure mask-set mask elt @dots{} @returns{} mask
@deffnx procedure mask-clear mask elt @dots{} @returns{} mask
@code{Mask-member?} returns true if @var{elt} is a member of the mask
@var{mask}, or @code{#f} if not.  @code{Mask-set} returns a mask with
all the elements in @var{mask} as well as each @var{elt} @dots{}.
@code{Mask-clear} returns a mask with all the elements in @var{mask}
but with none of @var{elt} @dots{}.
@end deffn

@deffn procedure mask-union mask@sub{1} mask@sub{2} @dots{} @returns{} mask
@deffnx procedure mask-intersection mask@sub{1} mask@sub{2} @dots{} @returns{} mask
@deffnx procedure mask-subtract mask@suba{a} mask@suba{b} @returns{} mask
@deffnx procedure mask-negate mask @returns{} mask
Set operations on masks.  @code{Mask-union} returns a mask containing
every element that is a member of any one of its arguments.
@code{Mask-intersection} returns a mask containing every element that
is a member of every one of its arguments.  @code{Mask-subtract}
returns a mask of every element that is in @var{mask@suba{a}} but not
also in @var{mask@suba{b}}.  @code{Mask-negate} returns a mask whose
members are every possible element of @var{mask}'s type that is not in
@var{mask}.
@end deffn