blist.xml

<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<!-- %% -->
<!-- %A  blist.msk                  GAP documentation             Martin Schönert -->
<!-- %% -->
<!-- %A  @(#)<M>Id: blist.msk,v 1.9 2002/04/15 10:02:27 sal Exp </M> -->
<!-- %% -->
<!-- %Y  (C) 1998 School Math and Comp. Sci., University of St Andrews, Scotland -->
<!-- %Y  Copyright (C) 2002 The GAP Group -->
<!-- %% -->
<Chapter Label="Boolean Lists">
<Heading>Boolean Lists</Heading>

This chapter describes boolean lists.
A <E>boolean list</E> is a list that has no holes and contains only
the boolean values <K>true</K> and <K>false</K>
(see Chapter&nbsp;<Ref Chap="Booleans"/>).
In function names we call boolean lists <E>blists</E> for brevity.


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="sect:IsBlist">
<Heading>IsBlist (Filter)</Heading>

<#Include Label="IsBlist">

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Boolean Lists Representing Subsets">
<Heading>Boolean Lists Representing Subsets</Heading>

<#Include Label="BlistList">
<#Include Label="ListBlist">
<#Include Label="SizeBlist">
<#Include Label="IsSubsetBlist">

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Set Operations via Boolean Lists">
<Heading>Set Operations via Boolean Lists</Heading>

<#Include Label="UnionBlist">
<#Include Label="IntersectionBlist">
<#Include Label="DifferenceBlist">

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Function that Modify Boolean Lists">
<Heading>Function that Modify Boolean Lists</Heading>

<#Include Label="UniteBlist">
<#Include Label="UniteBlistList">
<#Include Label="IntersectBlist">
<#Include Label="SubtractBlist">

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="More about Boolean Lists">
<Heading>More about Boolean Lists</Heading>

We defined a boolean list as a list that has no holes and contains only
<K>true</K> and <K>false</K>.
There is a special internal representation for boolean lists that needs
only 1 bit for each entry.
This bit is set if the entry is <K>true</K> and reset if the entry is
<K>false</K>.
This representation is of course much more compact than the ordinary
representation of lists, which needs 32 or 64 bits per entry.
<P/>
<!-- %T Add a note about internal representation of plain lists (preferably in -->
<!-- %T the chapter <Q>Lists</Q>), -->
<!-- %T in order to allow a user to estimate the space needed for -->
<!-- %T computations with lists; -->
<!-- %T then add cross-references from and to the other available list -->
<!-- %T representations! -->
<P/>
Not every boolean list is represented in this compact representation. It
would be too much work to test every time a list is changed, whether this
list has become a boolean list.  This section tells you under which
circumstances a   boolean list is represented  in  the compact
representation, so you can write your functions in such a way that you make
best use of the compact representation.
<P/>
If a dense list containing only <K>true</K> and <K>false</K> is read, it
is stored in the compact representation. Furthermore,
the results of <Ref Func="BlistList"/>,
<Ref Func="UnionBlist" Label="for a list"/>,
<Ref Func="IntersectionBlist" Label="for a list"/>
and <Ref Func="DifferenceBlist"/> are known
to be boolean lists by construction, and thus
are represented in the compact representation upon creation.
<P/>
If an argument of <Ref Func="IsSubsetBlist"/>,
<Ref Func="ListBlist"/>, <Ref Func="UnionBlist" Label="for a list"/>,
<Ref Func="IntersectionBlist" Label="for a list"/>,
<Ref Func="DifferenceBlist"/>,
<Ref Func="UniteBlist"/>, <Ref Func="IntersectBlist"/> and
<Ref Func="SubtractBlist"/> is a list represented in the ordinary
representation, it is
tested to see if it is in fact a boolean list.
If it is not, an error is signalled. If it is,  the
representation of the list  is changed to  the compact representation.
<P/>
If you change a  boolean list that is  represented in  the compact
representation by assignment (see <Ref Sect="List Assignment"/>) or
<Ref Func="Add"/>
in such a way that the list remains a boolean list  it will remain
represented in the compact representation.  Note that changing a list
that is not represented in the compact representation, whether it is a
boolean list or not, in such a way that the resulting list becomes a
boolean list, will never change the representation of the list.

<#Include Label="IsBlistRep">

</Section>
</Chapter>