Bitfields feature. Includes tests and documentation.

Bitfields provide a fast (by GAP standards) and tidy way of viewing an immediate integer
as a set of bitfields. Handy mainly for compact data structures.

doc/ref/integers.xml

@@ -174,5 +174,19 @@ random integers and random choices from lists.
 <#Include Label="RandomSource">
 
 </Section>
+<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
+<Section Label="Bitfields">
+  <Heading>Bitfields</Heading>
+Bitfields are a low-level feature intended to support efficient 
+subdivision of immediate integers into bitfields of various widths.
+This is typically useful in implementing space-efficient and/or
+cache-efficient data structures. This feature should be used with care
+because (<E>inter alia</E>) it has different limitations on 32-bit and 64-bit
+architectures.
+
+<#Include Label="MakeBitfields">
+
+</Section>
+
 </Chapter>
 

doc/ref/makedocreldata.g

@@ -28,6 +28,7 @@ GAPInfo.ManualDataRef:= rec(
     "../../lib/attr.gd",
     "../../lib/basis.gd",
     "../../lib/basismut.gd",
+    "../../lib/bitfields.gd",
     "../../lib/boolean.g",
     "../../lib/clas.gd",
     "../../lib/cmdledit.g",

lib/bitfields.gd

@@ -0,0 +1,78 @@
+#############################################################################
+##
+#W  bitfields.gd                  GAP library                   Steve Linton
+##
+##
+#Y  Copyright (C) 2017 The GAP Group
+##
+##  This file declares the operations for bitfields
+##
+
+
+
+#############################################################################
+##
+#F  MakeBitfields(<width>[, <width>[, <width>...]]])
+##  <#GAPDoc Label="MakeBitfields">
+##  <ManSection>
+##  <Func Name="MakeBitfields" Arg='width....'/>
+##
+##  <Description>
+##
+##  This function sets up the machinery for a set of bitfields of the given
+##  widths. All bitfield values are treated as unsigned. 
+##  The total of the widths must not exceed 60 bits on 64-bit architecture
+##  or 28 bits on a 32-bit architecture and the number of widths must not exceed
+##  10 on a 64-bit architecture or 6 on a 32-bit architecture. Also for performance 
+##  reasons some checks that one might wish to do are ommitted. In particular, 
+##  the builder and setter functions do not check if the value[s] passed to them are 
+##  negative or too large (unless &GAP; is specially compiled for debugging).
+##  Behaviour when such arguments are passed is undefined.
+##
+##  You can tell which type of architecture you are running on by acccessing 
+##  <C>GAPInfo.BytesPerVariable</C> which is 8 on 64-bits and 4 on 32. 
+##
+##  The return value  when <M>n</M> widths are given is a record whose fields are 
+##  <List>
+##  <Mark><C>widths</C></Mark> <Item>a copy of the arguments, for convenience,</Item>
+##  <Mark><C>builder</C></Mark> <Item> a function of <M>n</M> arguments that
+##  returns an immediate integer into which they are all packed. The first field
+##  occupies the least significant bits, etc.</Item>
+##  <Mark><C>getters</C></Mark> <Item> a list of <M>n</M> functions of one argument each of which extracts 
+##                 one of the fields from an immediate integer</Item>
+##  <Mark><C>setters</C></Mark> <Item> a list of <M>n</M> functions each taking
+##  two arguments: a packed value and a new value for one of its fields and
+##  returning a new packed value. The
+##  <M>i</M>th function returned the new packed value in which the <M>i</M>th
+##  field has been replaced by the new value.
+##   Note that this does NOT modify the original packed value.</Item>
+##  </List>
+##  <Example><![CDATA[
+##  gap> bf := MakeBitfields(1,2,3);
+##  rec( builder := function( val1, val2, val3 ) ... end, 
+##     getters := [ function( data ) ... end, function( data ) ... end, 
+##          function( data ) ... end ], 
+##     setters := [ function( data, val ) ... end, function( data, val ) ... end, 
+##          function( data, val ) ... end ], 
+##     widths := [ 1, 2, 3 ] )
+##  gap> x := bf.builder(0,3,5);
+##  46
+##  gap> bf.getters[3](x);
+##  5
+##  gap> y := bf.setters[1](x,1);
+##  47  
+##  gap> x;
+##  46
+##  ]]></Example>
+##  </Description>
+##  </ManSection>
+##  <#/GAPDoc>
+##
+
+DeclareGlobalFunction( "MakeBitfields" ); 
+
+
+#############################################################################
+##
+#E
+

lib/bitfields.gi

@@ -0,0 +1 @@
+InstallGlobalFunction(MakeBitfields, MAKE_BITFIELDS);

lib/read3.g

@@ -12,6 +12,7 @@ ReadLib( "extrset.gd"  );
 ReadLib( "extuset.gd"  );
 
 ReadLib( "dict.gd"     );
+ReadLib( "bitfields.gd" );
 
 ReadLib( "mapping.gd"  );
 ReadLib( "mapphomo.gd" );

lib/read5.g

@@ -149,6 +149,7 @@ ReadLib( "grppcatr.gi" );
 ReadLib( "grppcnrm.gi" );
 
 # files dealing with trees and hash tables
+ReadLib( "bitfields.gi" );
 ReadLib( "dict.gi"  );
 ReadLib( "dicthf.gi"  );