Overhaul IsPlistMatrixRep and IsPlistVectorRep

doc/ref/matobj.xml

@@ -173,10 +173,10 @@ for these matrix objects.
 
 <P/>
 
-One implementation of such matrices is given by the
+Two implementation of such matrices is given by the
 <Ref Attr="ConstructingFilter" Label="for a matrix object"/> value
-<Ref Filt="IsPlistMatrixRep"/>,
-and any row of these matrices is a vector object in
+<Ref Filt="IsRowPlistMatrixRep"/>,
+and any row of these matrices can be accessed as a vector object in
 <Ref Filt="IsPlistVectorRep"/>.
 Note that these objects do <E>not</E> lie in <Ref Filt="IsList"/>
 (and in particular not in <Ref Filt="IsPlistRep"/>),
@@ -190,8 +190,9 @@ in the last position,
 that is, the vector and matrix objects insist on being dense.
 All rows of a matrix must have the same length and the same base domain.
 
-<#Include Label="IsPlistVectorRep">
-<#Include Label="IsPlistMatrixRep">
+<#Include Label="IsRowPlistMatrixRep">
+<#Include Label="IsPlistVectorRep">  <!-- TODO: this does not really belong here; where else? -->
+<#Include Label="IsPlistMatrixRep">  <!-- TODO: this does not really belong here; where else? -->
 <#Include Label="RowListMatObj_[]">
 <#Include Label="RowListMatObj_[]_ASS">
 <#Include Label="RowListMatObj_{}">

lib/matobj2.gd

@@ -93,7 +93,7 @@
 ##  (see <Ref Attr="BaseDomain" Label="for a vector object"/>)
 ##  and their dimensions.
 ##  The basic condition is that the entries of vector and matrix objects
-##  must either lie in the base domain or naturally embed in the sense that
+##  must either lie in the base domain or naturally map into it in the sense that
 ##  addition and multiplication automatically work with elements of the
 ##  base domain;
 ##  for example, a matrix object over a polynomial ring may also contain

lib/matobjplist.gd

@@ -29,7 +29,7 @@
 ##  in a row list matrix
 ##  (see Section <Ref Subsect="Operations for Row List Matrix Objects"/>).
 ##  It is internally represented as a positional object
-##  (see <Ref Filt="IsPositionalObjectRep"/> that stores 2 entries:
+##  (see <Ref Filt="IsPositionalObjectRep"/> that stores two entries:
 ##  <Enum>
 ##  <Item>
 ##    its base domain
@@ -59,33 +59,48 @@ DeclareRepresentation( "IsPlistVectorRep",
 ##
 ##  <Description>
 ##  An object <A>obj</A> in <Ref Filt="IsPlistMatrixRep"/> describes
+##  a matrix object (see <Ref Filt="IsMatrixObj"/>) that internal stores its
+##  entries as a classic GAP matrix, that is as a plain list (see
+##  <Ref Filt="IsPlistRep"/>) of plain lists. Therefore any such GAP matrix
+##  can be represented as a <Ref Filt="IsPlistMatrixRep"/>, making this
+##  representation very versatile, and a good place to start if one wants to
+##  adapt code which previously produced such classic GAP matrices to instead
+##  produce matrix objects.
+##  </Description>
+##  </ManSection>
+##  <#/GAPDoc>
+##
+##  Implementation note: a matrix in IsPlistMatrixRep is internally
+##  represented as a positional object that stores four entries:
+##  - its base domain
+#   - the number of rows
+##  - the number of columns
+##  - a plain list of its rows, each also a plain list
+DeclareRepresentation( "IsPlistMatrixRep",
+        IsListMatrix and IsPositionalObjectRep
+    and IsNoImmediateMethodsObject
+    and HasNumberRows and HasNumberColumns
+    and HasBaseDomain and HasOneOfBaseDomain and HasZeroOfBaseDomain,
+    [] );
+
+
+#############################################################################
+##
+##  <#GAPDoc Label="IsRowPlistMatrixRep">
+##  <ManSection>
+##  <Filt Name="IsRowPlistMatrixRep" Arg='obj' Type="representation"/>
+##
+##  <Description>
+##  An object <A>obj</A> in <Ref Filt="IsRowPlistMatrixRep"/> describes
 ##  a matrix object (see <Ref Filt="IsMatrixObj"/>) that behaves similar to
 ##  a list of its rows, in the sense defined in
 ##  Section <Ref Sect="Operations for Row List Matrix Objects"/>.
-##  It is internally represented as a positional object
-##  (see <Ref Filt="IsPositionalObjectRep"/> that stores 4 entries:
-##  <Enum>
-##  <Item>
-##    its base domain
-##    (see <Ref Attr="BaseDomain" Label="for a matrix object"/>),
-##  </Item>
-##  <Item>
-##    an empty vector in the representation of each row, 
-##  </Item>
-##  <Item>
-##    the number of columns
-##    (see <Ref Attr="NumberColumns" Label="for a matrix object"/>), and
-##  </Item>
-##  <Item>
-##    a plain list (see <Ref Filt="IsPlistRep"/> of its rows,
-##    each of them being an object in <Ref Filt="IsPlistVectorRep"/>.
-##  </Item>
-##  </Enum>
+##  Its rows can be accessed as objects in <Ref Filt="IsPlistVectorRep"/>,
 ##  </Description>
 ##  </ManSection>
 ##  <#/GAPDoc>
 ##
-DeclareRepresentation( "IsPlistMatrixRep",
+DeclareRepresentation( "IsRowPlistMatrixRep",
         IsRowListMatrix and IsPositionalObjectRep
     and IsNoImmediateMethodsObject
     and HasNumberRows and HasNumberColumns
@@ -94,24 +109,16 @@ DeclareRepresentation( "IsPlistMatrixRep",
 
 
 # Some constants for matrix access:
-BindGlobal( "BDPOS", 1 );
-BindGlobal( "EMPOS", 2 );
-BindGlobal( "RLPOS", 3 );
-BindGlobal( "ROWSPOS", 4 );
+# TODO rename these so that one can quickly see that they belong to IsPlist*Rep
+BindConstant( "BDPOS", 1 );
+BindConstant( "NUM_ROWS_POS", 2 );
+BindConstant( "NUM_COLS_POS", 3 );
+BindConstant( "ROWSPOS", 4 );
 
 # For vector access:
-#BindGlobal( "BDPOS", 1 );   # see above
-BindGlobal( "ELSPOS", 2 );
+#BindConstant( "BDPOS", 1 );   # see above
+BindConstant( "ELSPOS", 2 );
 
 # Two filters to speed up some methods:
 DeclareFilter( "IsIntVector" );
 DeclareFilter( "IsFFEVector" );
-
-############################################################################
-# Constructors:
-############################################################################
-
-#T Should this be documented?
-#T It seems to be just an auxiliary function for the documented constructors.
-DeclareGlobalFunction( "MakePlistVectorType" );
-