matrixobj: deal with mutability questions (gap-system#5254)

* deal with mutability questions

- changed the mutability definition for vector and matrix objects:
  - The `ConstructingFilter` value indicates whether mutable variants
    are possible at all, as follows:
    If the filter implies `IsCopyable` then one can create mutable variants,
    otherwise not.
  - In the definitions of `NewVector`, `ZeroVector`, `NewMatrix`, `ZeroMatrix`,
    `IdentityMatrix`, promise (fully) mutable results if and only if the
    filter in question implies `IsCopyable`.
  - In the definitions of `Vector` and `Matrix`, promise mutable results
    if and only if the filter in question implies `IsCopyable` and the
    vector/matrix that defines the entries is mutable.

- changed the currently available `ConstructingFilter` values such that
  they imply `IsCopyable`.
  (I assume that these filters can be found as follows.)
  ```
  flags:= List( [ IsVectorObj, IsMatrixObj ], FLAG1_FILTER );;
  Filtered( FILTERS, x -> IsRepresentation( x ) and Intersection( flags, TRUES_FLAGS( WITH_IMPS_FLAGS( FLAGS_FILTER( x ) ) ) ) <> [] );
  ```

- extended the definition of `Vector( v, w )` such that also the case of
  `w` in `IsPlistRep` is supported,
  and added a method for both arguments in `IsList and IsCyclotomicCollection`
  (to be used for example for objects in `IsAlgebraicElement`).

* document available representations ...

... of vector and matrix objects, and mention that they admit
mutable variants

Details:

- moved the manual section "Basic operations for row/column reductions"
  above the section "Implementing New Vector and Matrix Objects Types",
  in order to collect the stuff about implementations at the end of the
  chapter

- added new manual sections for the documentation of
  `IsGF2VectorRep`, `Is8BitVectorRep`, `IsZmodnZVectorRep`,
  `IsGF2MatrixRep`, `Is8BitMatrixRep`, `IsZmodnZMatrixRep`

- moved the documentation of `IsPlistVectorRep` and
  `IsPlistMatrixRep` to the new sections

- changed some formulations such that `IsPlistMatrixRep` appears
  just as one instance of `IsRowListMatrix`

* omit details about the implementation ...

... from the documentation of representations of matrix and vector objects.

(This affects documentation added in a previous commit of this
pull request as well as documentation that has been available
already before.)

doc/ref/makedocreldata.g

@@ -109,11 +109,13 @@ GAPInfo.ManualDataRef:= rec(
     "../../lib/magma.gd",
     "../../lib/mapphomo.gd",
     "../../lib/mapping.gd",
+    "../../lib/mat8bit.gd",
     "../../lib/matblock.gd",
     "../../lib/matint.gd",
     "../../lib/matobj.gi",
     "../../lib/matobj1.gd",
     "../../lib/matobj2.gd",
+    "../../lib/matobjnz.gd",
     "../../lib/matobjplist.gd",
     "../../lib/matrix.gd",
     "../../lib/meataxe.gi",
@@ -205,6 +207,7 @@ GAPInfo.ManualDataRef:= rec(
     "../../lib/upoly.gd",
     "../../lib/userpref.g",
     "../../lib/variable.g",
+    "../../lib/vec8bit.gd",
     "../../lib/vecmat.gd",
     "../../lib/vspc.gd",
     "../../lib/vspchom.gd",

doc/ref/matobj.xml

@@ -167,9 +167,11 @@ that can on the one hand benefit from ⪆'s method selection,
 as is explained in
 Section <Ref Sect="Concepts and Rules for Vector and Matrix Objects"/>,
 and do on the other hands support access to &GAP; objects that represent
-their rows (which are suitable vector objects),
-such that the operations described in this section are supported
-for these matrix objects.
+their rows (which are suitable vector objects).
+Matrix objects whose
+<Ref Filt="ConstructingFilter" Label="for a matrix object"/> value implies
+<Ref Filt="IsRowListMatrix"/> support the operations described in this
+section.
 
 <P/>
 
@@ -190,8 +192,6 @@ 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="RowListMatObj_[]">
 <#Include Label="RowListMatObj_[]_ASS">
 <#Include Label="RowListMatObj_{}">
@@ -207,10 +207,38 @@ All rows of a matrix must have the same length and the same base domain.
 </Section>
 
 
+<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
+<Section Label="Basic operations for row/column reductions">
+<Heading>Basic operations for row/column reductions</Heading>
+
+<#Include Label="MultMatrixRow">
+<#Include Label="MultMatrixRowRight">
+<#Include Label="MultMatrixColumn">
+<#Include Label="MultMatrixColumnLeft">
+<#Include Label="AddMatrixRows">
+<#Include Label="AddMatrixRowsRight">
+<#Include Label="AddMatrixColumns">
+<#Include Label="AddMatrixColumnsLeft">
+<#Include Label="SwapMatrixRows">
+<#Include Label="SwapMatrixColumns">
+
+</Section>
+
+
 <!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
 <Section Label="Implementing New Vector and Matrix Objects Types">
 <Heading>Implementing New Vector and Matrix Objects Types</Heading>
 
+The first step in the design of a new type of vector or matrix objects
+is to create a new filter that serves as the
+<Ref Attr="ConstructingFilter" Label="for a vector object"/>
+of the new objects,
+see the sections <Ref Sect="Available Representations of Vector Objects"/>
+and <Ref Sect="Available Representations of Matrix Objects"/>
+for an overview of such filters that are already available.
+
+<P/>
+
 Here we list those operations for vector and matrix objects
 for which no default methods can be installed.
 When one implements a new type of vector or matrix objects
@@ -222,6 +250,7 @@ The installations of default methods can be found in the file
 <F>lib/matobj.gi</F> of the &GAP; distribution.
 There one can check for which operations it makes sense to overload them
 for the new type of vector or matrix objects.
+
 <P/>
 
 <E>Vector objects</E>
@@ -316,19 +345,30 @@ that do not delegate to <Ref Constr="NewVector"/> and
 </Section>
 
 <!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
-<Section Label="Basic operations for row/column reductions">
-<Heading>Basic operations for row/column reductions</Heading>
+<Section Label="Available Representations of Vector Objects">
+<Heading>Available Representations of Vector Objects</Heading>
 
-<#Include Label="MultMatrixRow">
-<#Include Label="MultMatrixRowRight">
-<#Include Label="MultMatrixColumn">
-<#Include Label="MultMatrixColumnLeft">
-<#Include Label="AddMatrixRows">
-<#Include Label="AddMatrixRowsRight">
-<#Include Label="AddMatrixColumns">
-<#Include Label="AddMatrixColumnsLeft">
-<#Include Label="SwapMatrixRows">
-<#Include Label="SwapMatrixColumns">
+The following filters define vector objects for which the the functionality
+described in this chapter is supported.
+
+<#Include Label="IsGF2VectorRep">
+<#Include Label="Is8BitVectorRep">
+<#Include Label="IsPlistVectorRep">
+<#Include Label="IsZmodnZVectorRep">
+
+</Section>
+
+<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
+<Section Label="Available Representations of Matrix Objects">
+<Heading>Available Representations of Matrix Objects</Heading>
+
+The following filters define matrix objects for which the the functionality
+described in this chapter is supported.
+
+<#Include Label="IsGF2MatrixRep">
+<#Include Label="Is8BitMatrixRep">
+<#Include Label="IsPlistMatrixRep">
+<#Include Label="IsZmodnZMatrixRep">
 
 </Section>
 

lib/list.gd

@@ -55,7 +55,7 @@ BIND_GLOBAL( "ListsFamily", NewFamily( "ListsFamily", IsList ) );
 ##
 ##  <#GAPDoc Label="IsPlistRep">
 ##  <ManSection>
-##  <Filt Name="IsPlistRep" Arg='obj' Type='representation'/>
+##  <Filt Name="IsPlistRep" Arg='obj' Type='Representation'/>
 ##
 ##  <Description>
 ##  &GAP; lists created by entering comma separated values in square brackets

lib/mat8bit.gd

@@ -16,8 +16,37 @@
 ##
 #R  Is8BitMatrixRep( <obj> ) . . . compressed vector over GFQ (3 <= q <= 256)
 ##
+##  <#GAPDoc Label="Is8BitMatrixRep">
+##  <ManSection>
+##  <Filt Name="Is8BitMatrixRep" Arg='obj' Type='Representation'/>
+##
+##  <Description>
+##  An object <A>obj</A> in <Ref Filt="Is8BitMatrixRep"/> describes
+##  a matrix object (see <Ref Filt="IsMatrixObj"/>) that behaves like the
+##  list of its rows (see <Ref Filt="IsRowListMatrix"/>).
+##  The base domain of <A>obj</A> is a field that contains all matrix
+##  entries (but not necessarily the smallest such field),
+##  it must be a finite field with <M>q</M> elements,
+##  for <M>3 \leq q \leq 256</M>.
+##  <P/>
+##  <Ref Filt="Is8BitMatrixRep"/> implies <Ref Filt="IsCopyable"/>,
+##  thus matrix objects in this representation can be mutable.
+##  </Description>
+##  </ManSection>
+##  <#/GAPDoc>
+##
+##  <A>obj</A> is internally represented as a positional object
+##  (see <Ref Filt="IsPositionalObjectRep"/>).
+##  If the number of rows is <M>n</M> then this object stores <M>n+1</M>
+##  entries,
+##  <M>n</M> at position <M>1</M> and the <M>i</M>-th row at position
+##  <M>i+1</M>.
+##  The base domain is not stored explicitly in <A>obj</A>
+##  but is determined by the common base domain of the rows of the matrix.
+##
 DeclareRepresentation( "Is8BitMatrixRep",
         IsPositionalObjectRep and IsRowListMatrix
+    and IsCopyable
     and IsNoImmediateMethodsObject
     and HasNumberRows and HasNumberColumns
     and HasBaseDomain and HasOneOfBaseDomain and HasZeroOfBaseDomain);

lib/matobj.gi

@@ -241,6 +241,14 @@ function(l)
   return NewVector(DefaultVectorRepForBaseDomain(dom), dom, l);
 end);
 
+# The following method is used for example
+# in code dealing with elements of 'AlgebraicExtension's.
+# (Note that we want to return a vector with the same mutability status
+# as the given vector, and we need not copy it if it is mutable.)
+InstallOtherMethod( Vector,
+    [ IsList and IsCyclotomicCollection, IsList and IsCyclotomicCollection ],
+    { v, example } -> v );
+
 
 #############################################################################
 ##

lib/matobj1.gd

@@ -33,7 +33,7 @@ DeclareCategory( "IsVecOrMatObj", IsCopyable );
 ##
 ##  <#GAPDoc Label="IsVectorObj">
 ##  <ManSection>
-##  <Filt Name="IsVectorObj" Arg='obj' Type="category"/>
+##  <Filt Name="IsVectorObj" Arg='obj' Type="Category"/>
 ##
 ##  <Description>
 ##  The idea behind <E>vector objects</E> is that one wants to deal with
@@ -98,7 +98,7 @@ DeclareCategory( "IsVectorObj", IsVector and IsVecOrMatObj );
 ##
 ##  <#GAPDoc Label="IsMatrixOrMatrixObj">
 ##  <ManSection>
-##  <Filt Name="IsMatrixOrMatrixObj" Arg='obj' Type="category"/>
+##  <Filt Name="IsMatrixOrMatrixObj" Arg='obj' Type="Category"/>
 ##
 ##  <Description>
 ##  Several functions are defined for objects in <Ref Filt="IsMatrix"/> and
@@ -153,7 +153,7 @@ InstallTrueMethod( IsMatrixOrMatrixObj, IsMatrix );
 ##
 ##  <#GAPDoc Label="IsMatrixObj">
 ##  <ManSection>
-##  <Filt Name="IsMatrixObj" Arg='obj' Type="category"/>
+##  <Filt Name="IsMatrixObj" Arg='obj' Type="Category"/>
 ##
 ##  <Description>
 ##  The idea behind <E>matrix objects</E> is that one wants to deal with
@@ -239,7 +239,7 @@ DeclareCategory( "IsMatrixObj", IsMatrixOrMatrixObj );
 ##
 ##  <#GAPDoc Label="IsRowListMatrix">
 ##  <ManSection>
-##  <Filt Name="IsRowListMatrix" Arg='obj' Type="category"/>
+##  <Filt Name="IsRowListMatrix" Arg='obj' Type="Category"/>
 ##
 ##  <Description>
 ##  A <E>row list matrix object</E> is a matrix object