1<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
2<!-- %% -->
3<!-- %A  blist.msk                  GAP documentation             Martin Schönert -->
4<!-- %% -->
5<!-- %A  @(#)<M>Id: blist.msk,v 1.9 2002/04/15 10:02:27 sal Exp </M> -->
6<!-- %% -->
7<!-- %Y  (C) 1998 School Math and Comp. Sci., University of St Andrews, Scotland -->
8<!-- %Y  Copyright (C) 2002 The GAP Group -->
9<!-- %% -->
10<Chapter Label="Boolean Lists">
11<Heading>Boolean Lists</Heading>
12
13This chapter describes boolean lists.
14A <E>boolean list</E> is a list that has no holes and contains only
15the boolean values <K>true</K> and <K>false</K>
16(see Chapter&nbsp;<Ref Chap="Booleans"/>).
17In function names we call boolean lists <E>blists</E> for brevity.
18
19
20<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
21<Section Label="sect:IsBlist">
22<Heading>IsBlist (Filter)</Heading>
23
24<#Include Label="IsBlist">
25
26</Section>
27
28
29<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
30<Section Label="Boolean Lists Representing Subsets">
31<Heading>Boolean Lists Representing Subsets</Heading>
32
33<#Include Label="BlistList">
34<#Include Label="ListBlist">
35<#Include Label="SizeBlist">
36<#Include Label="IsSubsetBlist">
37
38</Section>
39
40
41<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
42<Section Label="Set Operations via Boolean Lists">
43<Heading>Set Operations via Boolean Lists</Heading>
44
45<#Include Label="UnionBlist">
46<#Include Label="IntersectionBlist">
47<#Include Label="DifferenceBlist">
48
49</Section>
50
51
52<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
53<Section Label="Function that Modify Boolean Lists">
54<Heading>Function that Modify Boolean Lists</Heading>
55
56<#Include Label="UniteBlist">
57<#Include Label="UniteBlistList">
58<#Include Label="IntersectBlist">
59<#Include Label="SubtractBlist">
60<#Include Label="FlipBlist">
61<#Include Label="SetAllBlist">
62<#Include Label="ClearAllBlist">
63</Section>
64
65
66<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
67<Section Label="More about Boolean Lists">
68<Heading>More about Boolean Lists</Heading>
69
70We defined a boolean list as a list that has no holes and contains only
71<K>true</K> and <K>false</K>.
72There is a special internal representation for boolean lists that needs
73only 1 bit for each entry.
74This bit is set if the entry is <K>true</K> and reset if the entry is
75<K>false</K>.
76This representation is of course much more compact than the ordinary
77representation of lists, which needs 32 or 64 bits per entry.
78<P/>
79<!-- %T Add a note about internal representation of plain lists (preferably in -->
80<!-- %T the chapter <Q>Lists</Q>), -->
81<!-- %T in order to allow a user to estimate the space needed for -->
82<!-- %T computations with lists; -->
83<!-- %T then add cross-references from and to the other available list -->
84<!-- %T representations! -->
85<P/>
86Not every boolean list is represented in this compact representation. It
87would be too much work to test every time a list is changed, whether this
88list has become a boolean list.  This section tells you under which
89circumstances a   boolean list is represented  in  the compact
90representation, so you can write your functions in such a way that you make
91best use of the compact representation.
92<P/>
93If a dense list containing only <K>true</K> and <K>false</K> is read, it
94is stored in the compact representation. Furthermore,
95the results of <Ref Func="BlistList"/>,
96<Ref Func="UnionBlist" Label="for a list"/>,
97<Ref Func="IntersectionBlist" Label="for a list"/>
98and <Ref Func="DifferenceBlist"/> are known
99to be boolean lists by construction, and thus
100are represented in the compact representation upon creation.
101<P/>
102If an argument of <Ref Func="IsSubsetBlist"/>,
103<Ref Func="ListBlist"/>, <Ref Func="UnionBlist" Label="for a list"/>,
104<Ref Func="IntersectionBlist" Label="for a list"/>,
105<Ref Func="DifferenceBlist"/>,
106<Ref Func="UniteBlist"/>, <Ref Func="IntersectBlist"/> and
107<Ref Func="SubtractBlist"/> is a list represented in the ordinary
108representation, it is
109tested to see if it is in fact a boolean list.
110If it is not, an error is signalled. If it is,  the
111representation of the list  is changed to  the compact representation.
112<P/>
113If you change a  boolean list that is  represented in  the compact
114representation by assignment (see <Ref Sect="List Assignment"/>) or
115<Ref Oper="Add"/>
116in such a way that the list remains a boolean list  it will remain
117represented in the compact representation.  Note that changing a list
118that is not represented in the compact representation, whether it is a
119boolean list or not, in such a way that the resulting list becomes a
120boolean list, will never change the representation of the list.
121
122<#Include Label="IsBlistRep">
123
124</Section>
125</Chapter>
126
127
128