document basic representations of objects (IsInternalRep, IsDataObjectRep, IsComponentObjectRep, IsPositionalObjectRep, IsAttributeStoringRep, IsPlistRep)

doc/ref/create.xml

@@ -81,7 +81,7 @@ Chapter&nbsp;<Ref Chap="An Example -- Residue Class Rings"/>.
 <Heading>Component Objects</Heading>
 
 A <E>component object</E> is an object in the representation
-<C>IsComponentObjectRep</C> or a subrepresentation of it.
+<Ref Filt="IsComponentObjectRep"/> or a subrepresentation of it.
 Such an object <A>cobj</A> is built from subobjects that can be accessed via
 <C><A>cobj</A>!.<A>name</A></C>, similar to components of a record.
 Also analogously to records, values can be assigned to components of
@@ -124,7 +124,7 @@ IsIntegersIteratorCompRep := NewRepresentation( "IsIntegersIteratorRep",
 <P/>
 The above command creates a new representation (see&nbsp;<Ref Func="NewRepresentation"/>)
 <C>IsIntegersIteratorCompRep</C>,
-as a subrepresentation of <C>IsComponentObjectRep</C>,
+as a subrepresentation of <Ref Filt="IsComponentObjectRep"/>,
 and with one admissible component <C>counter</C>.
 So no other components than <C>counter</C> will be needed.
 <P/>
@@ -189,7 +189,7 @@ InstallMethod( NextIterator,
 <Heading>Positional Objects</Heading>
 
 A <E>positional object</E> is an object in the representation
-<C>IsPositionalObjectRep</C> or a subrepresentation of it.
+<Ref Filt="IsPositionalObjectRep"/> or a subrepresentation of it.
 Such an object <A>pobj</A> is built from subobjects that can be accessed via
 <C><A>pobj</A>![<A>pos</A>]</C>, similar to positions in a list.
 Also analogously to lists, values can be assigned to positions of
@@ -226,7 +226,7 @@ IsIntegersIteratorPosRep := NewRepresentation( "IsIntegersIteratorRep",
 <P/>
 The above command creates a new representation (see&nbsp;<Ref Func="NewRepresentation"/>)
 <C>IsIntegersIteratorPosRep</C>,
-as a subrepresentation of <C>IsComponentObjectRep</C>,
+as a subrepresentation of <Ref Filt="IsPositionalObjectRep"/>,
 and with only the first position being admissible for storing data.
 <P/>
 <Log><![CDATA[
@@ -681,7 +681,7 @@ or less natural behaviour.
 <P/>
 If a list in the filter <Ref Filt="IsGeneralizedRowVector"/>
 (<Ref Filt="IsMultiplicativeGeneralizedRowVector"/>)
-lies in <C>IsAttributeStoringRep</C>,
+lies in <Ref Filt="IsAttributeStoringRep"/>,
 the values of additive (multiplicative) nesting depth is stored in
 the list and need not be calculated for each arithmetic operation.
 One can then store the value(s) already upon creation of the lists,

doc/ref/intrfc.xml

@@ -339,11 +339,10 @@ function(G)
 end);
 ]]></Log>
 <P/>
-<Index Key="IsAttributeStoringRep"><C>IsAttributeStoringRep</C></Index>
 The function installed <E>must</E> always return a value (or call
 <Ref Func="TryNextMethod"/>).
-If the object is in the representation
-<C>IsAttributeStoringRep</C> this return value once computed will be automatically
+If the object is in the representation <Ref Filt="IsAttributeStoringRep"/>
+this return value once computed will be automatically
 stored and retrieved if the attribute is called a second time. We don't have
 to call setter or tester ourselves. (This storage happens by &GAP;
 internally calling the attribute setter with the return value of the
@@ -360,8 +359,6 @@ when the attribute was declared.)
 
 <Index Key="NewRepresentation" Subkey="example"><C>NewRepresentation</C></Index>
 <Index Key="DeclareRepresentation" Subkey="example"><C>DeclareRepresentation</C></Index>
-<Index Key="IsComponentObjectRep"><C>IsComponentObjectRep</C></Index>
-<Index Key="IsAttributeStoringRep"><C>IsAttributeStoringRep</C></Index>
 Next, we look at the implementation of a new representation of existing
 objects. In most cases we want to implement this representation only for
 efficiency reasons while keeping all the existing functionality.
@@ -371,8 +368,9 @@ to implement permutation groups defined by relations.
 <P/>
 Next, we have to decide a few basics about the representation. All existing
 permutation groups in the library are attribute storing and we probably want
-to keep this for our new objects. Thus the representation must be a
-subrepresentation of <C>IsComponentObjectRep and IsAttributeStoringRep</C>.
+to keep this for our new objects.
+Thus the representation must be a subrepresentation of
+<Ref Filt="IsComponentObjectRep"/> and <Ref Filt="IsAttributeStoringRep"/>.
 Furthermore we want each object to be a permutation group and we can imply
 this directly in the representation.
 <P/>

doc/ref/lists.xml

@@ -30,8 +30,10 @@ and more about lists as <E>arithmetic objects</E> can be found in the chapters
 Lists are used to implement ranges (see&nbsp;<Ref Sect="Ranges"/>),
 sets (see&nbsp;<Ref Sect="Sorted Lists and Sets"/>),<Index>Sets</Index>
 strings (see&nbsp;<Ref Chap="Strings and Characters"/>),
-row vectors (see&nbsp;<Ref Chap="Row Vectors"/>),
-and matrices (see&nbsp;<Ref Chap="Matrices"/>);
+row vectors and matrices
+(see&nbsp;<Ref Chap="Row Vectors"/> and <Ref Chap="Matrices"/>,
+but note that &GAP; supports also linear algebra for objects which are
+<E>not</E> lists, see <Ref Chap="Vector and Matrix Objects"/>);
 boolean lists (see&nbsp;<Ref Chap="Boolean Lists"/>) are a further
 special kind of lists.
 <P/>
@@ -1849,6 +1851,29 @@ see&nbsp;<Ref Sect="Example -- Constructing Enumerators"/>.
 
 <#Include Label="IsQuickPositionList">
 
+</Section>
+
+
+<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
+<Section Label="Plain Lists">
+<Heading>Plain Lists</Heading>
+
+Plain lists are the default kind of lists in &GAP;,
+in the sense that &GAP; stores the list entries and does not know how to do
+better (as opposed to ranges or strings, which are also lists).
+Often it is not necessary to know how a given list is represented
+internally, the operations defined for lists apply to all lists.
+
+<P/>
+
+Typical situations where the representation matters are when one wants to
+make sure that the given list is <E>not</E> a plain list and thus will be
+handled more efficiently,
+for example when one installs a method for a particular operation,
+where an argument is required to be a list in a particular representation.
+
+<#Include Label="IsPlistRep">
+
 </Section>
 </Chapter>
 

doc/ref/types.xml

@@ -413,51 +413,8 @@ densely; all dense polynomials form a representation. An object which
 claims to lie in a certain representation is accepting the requirement
 that certain fields in the data structure be present and have
 specified meanings.
-<P/>
-&GAP; distinguishes four essentially different ways to represent
-objects.  First there are the representations <C>IsInternalRep</C> for
-internal objects such as integers and permutations, and
-<C>IsDataObjectRep</C> for other objects that are created and whose data
-are accessible only by kernel functions. The data structures
-underlying such objects cannot be manipulated at the &GAP; level.
-<P/>
-All other objects are either in the representation
-<C>IsComponentObjectRep</C> or in the representation
-<C>IsPositionalObjectRep</C>,
-see&nbsp;<Ref Sect="Component Objects"/>
-and&nbsp;<Ref Sect="Positional Objects"/>.
-<P/>
-An object can belong to several representations in the sense that it
-lies in several subrepresentations of <C>IsComponentObjectRep</C> or of
-<C>IsPositionalObjectRep</C>.  The representations to which an object
-belongs should form a chain and either two representations are disjoint
-or one is contained in the other.  So the subrepresentations of
-<C>IsComponentObjectRep</C> and <C>IsPositionalObjectRep</C> each form
-trees. In the language of Object Oriented Programming, we support only
-single inheritance for representations.
-<P/>
-These trees are typically rather shallow, since for one representation
-to be contained in another implies that all the components of the data
-structure implied by the containing representation, are present in,
-and have the same meaning in, the smaller representation (whose data
-structure presumably contains some additional components).
-<P/>
-Objects may change their representation, for example a mutable list
-of characters can be converted into a string.
-<P/>
-All representations in the library are created during initialization,
-in particular they are not created dynamically at runtime.
-<P/>
-Examples of subrepresentations of <C>IsPositionalObjectRep</C> are
-<C>IsModulusRep</C>, which is used for residue classes in the ring of
-integers, and <C>IsDenseCoeffVectorRep</C>, which is used for elements of
-algebras that are defined by structure constants.
-<P/>
-An important subrepresentation of <C>IsComponentObjectRep</C> is
-<C>IsAttributeStoringRep</C>, which is used for many domains and some other
-objects.  It provides automatic storing of all attribute values (see
-below).
 
+<#Include Label="BasicRepresentations">
 <#Include Label="IsRepresentation">
 <#Include Label="RepresentationsOfObject">
 <#Include Label="NewRepresentation">
@@ -485,25 +442,11 @@ except if the attribute had been specially constructed as
 <Q>mutable attribute</Q>.
 <P/>
 It depends on the representation of an object (see&nbsp;<Ref Sect="Representation"/>)
-which attribute values it stores.  An immutable object in the representation
-<C>IsAttributeStoringRep</C> stores <E>all</E> attribute values once they are
-computed.  Moreover, for an object in this representation, subsequent
-calls to an attribute will return the <E>same</E> object; this is achieved
-via a special method for each attribute setter that stores the
-attribute value in an object in <C>IsAttributeStoringRep</C>, and a special
-method for the attribute itself that fetches the stored attribute
-value.  (These methods are called the <Q>system setter</Q> and the
-<Q>system getter</Q> of the attribute, respectively.)<Index>system
-getter</Index><Index>system setter</Index>
-<P/>
-Mutable objects in <C>IsAttributeStoringRep</C> are allowed, but
-attribute values are not automatically stored in them. Such objects
-are useful because values can be stored by explicitly calling the
-relevant setter, and because they may later be made immutable using
-<Ref Func="MakeImmutable"/>, at which point they will start storing
-all attribute values.
-<P/>
-Note also that it is impossible to get rid of a stored attribute
+which attribute values it stores.
+An immutable object in the representation <Ref Filt="IsAttributeStoringRep"/>
+stores <E>all</E> attribute values once they are computed.
+<P/>
+Note that it is impossible to get rid of a stored attribute
 value because the system may have drawn conclusions from the old
 attribute value, and just removing the value might leave the data
 structures in an inconsistent state. If necessary, a new object can be
@@ -537,6 +480,7 @@ and <Ref Attr="DerivedSubgroup"/> is an attribute for groups.
 <#Include Label="KnownAttributesOfObject">
 <#Include Label="NewAttribute">
 <#Include Label="DeclareAttribute">
+<#Include Label="IsAttributeStoringRep">
 
 </Section>
 
@@ -639,7 +583,7 @@ brk>
 
 <Description>
 If the value of the attribute <A>attr</A> is already stored for <A>obj</A>,
-<C>AttributeValueNotSet</C> simply returns this value.
+<Ref Func="AttributeValueNotSet"/> simply returns this value.
 Otherwise the value of <C><A>attr</A>( <A>obj</A> )</C> is computed and returned
 <E>without storing it</E> in <A>obj</A>.
 This can be useful when <Q>large</Q> attribute values (such as element lists)

doc/ref/xtndxmpl.xml

@@ -995,7 +995,7 @@ To be more precise,
 elements of finite fields in ⪆ lie in the category
 <Ref Filt="IsFFE"/>,
 and there is already a representation,
-<C>IsInternalRep</C>, of these elements
+<Ref Filt="IsInternalRep"/>, of these elements
 via discrete logarithms.
 The aim of this section is to make <C>IsMyModulusRep</C> an alternative
 representation of elements in finite prime fields.
@@ -1238,7 +1238,8 @@ We have to be careful, however, with the methods for
 <Ref Oper="InverseOp"/>,
 <Ref Oper="\/"/>, and <Ref Oper="\^"/>.
 These methods and the missing methods for arithmetic operations with
-one argument in <C>IsMyModulusRep</C> and the other in <C>IsInternalRep</C>
+one argument in <C>IsMyModulusRep</C> and the other in
+<Ref Filt="IsInternalRep"/>
 are given below.
 <P/>
 <Log><![CDATA[

doc/tut/lists.xml

@@ -1024,7 +1024,10 @@ some known fields in &GAP; are described in Chapters&nbsp;<Ref Chap="Rational Nu
 <Ref Chap="Abelian Number Fields" BookName="ref"/>,
 and&nbsp;<Ref Chap="Finite Fields" BookName="ref"/>.
 Row vectors and matrices are described in more detail in Chapters&nbsp;<Ref Chap="Row Vectors" BookName="ref"/>
-and&nbsp;<Ref Chap="Matrices" BookName="ref"/>.
+and&nbsp;<Ref Chap="Matrices" BookName="ref"/>;
+note that &GAP; supports also linear algebra for objects which are
+<E>not</E> lists,
+see Chapter <Ref Chap="Vector and Matrix Objects" BookName="ref"/>.
 Vector spaces are described in Chapter&nbsp;<Ref Chap="Vector Spaces" BookName="ref"/>,
 further matrix related structures are described in Chapters&nbsp;<Ref Chap="Matrix Groups" BookName="ref"/>,
 <Ref Chap="Algebras" BookName="ref"/>,

lib/list.gd

@@ -53,12 +53,33 @@ BIND_GLOBAL( "ListsFamily", NewFamily( "ListsFamily", IsList ) );
 ##
 #R  IsPlistRep  . . . . . . . . . . . . . . . . representation of plain lists
 ##
+##  <#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
+##  are usually represented internally as so-called <E>plain lists</E>.
+##  Other representations of lists are <Ref Filt="IsBlistRep"/>,
+##  <Ref Filt="IsRangeRep"/>, <Ref Filt="IsStringRep"/>,
+##  or the ones that are chosen for implementing enumerators,
+##  see Section <Ref Sect="Enumerators"/>.
+##  <P/>
+##  <Example><![CDATA[
+##  gap> IsPlistRep( [ 1, 2, 3 ] );
+##  true
+##  gap> IsPlistRep( "abc" );
+##  false
+##  gap> IsPlistRep( [ 1 .. 5 ] );
+##  false
+##  gap> IsPlistRep( BlistList( [ 1 .. 5 ], [ 1 ] ) );
+##  false
+##  gap> IsPlistRep( 0 );
+##  false
+##  ]]></Example>
 ##  </Description>
 ##  </ManSection>
+##  <#/GAPDoc>
 ##
 DeclareRepresentationKernel( "IsPlistRep",
     IsInternalRep, [], IS_OBJECT, IS_PLIST_REP );
@@ -358,8 +379,8 @@ DeclareSynonym( "AsSSortedListList", AS_LIST_SORTED_LIST );
 ##  <Attr Name="AsPlist" Arg='l'/>
 ##
 ##  <Description>
-##  <C>AsPlist</C> returns a list in the representation <C>IsPlistRep</C>
-##  that is equal to the list <A>l</A>.
+##  <Ref Attr="AsPlist"/> returns a list in the representation
+##  <Ref Filt="IsPlistRep"/> that is equal to the list <A>l</A>.
 ##  It is used before calling kernel functions to sort plists.
 ##  </Description>
 ##  </ManSection>

lib/object.gd

@@ -639,7 +639,7 @@ DeclareOperation( "IsInternallyConsistent", [ IsObject ] );
 ##  For example, if a matrix is in the two fiters <C>IsOrdinaryMatrix</C> and
 ##  <C>IsLieMatrix</C> then apparently something went wrong.
 ##  Since we can install these immediate methods only for attributes
-##  (and not for the operation <C>IsInternallyConsistent</C>),
+##  (and not for the operation <Ref Oper="IsInternallyConsistent"/>),
 ##  we need such an attribute.
 ##  </Description>
 ##  </ManSection>

lib/string.g

@@ -141,7 +141,7 @@ DeclareRepresentationKernel( "IsStringRep",
 ##  <Ref Func="ConvertToStringRep"/> changes the representation to
 ##  <Ref Filt="IsStringRep"/>.
 ##  This is useful in particular for converting the empty list <C>[]</C>,
-##  which usually is in <C>IsPlistRep</C>,
+##  which usually is in <Ref Filt="IsPlistRep"/>,
 ##  to <Ref Filt="IsStringRep"/>.
 ##  If <A>obj</A> is not a string then <Ref Func="ConvertToStringRep"/>
 ##  signals an error.