<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<!-- %% -->
<!-- %A  record.xml                  GAP documentation            Martin Schönert -->
<!-- %A                                                           Alexander Hulpke -->
<!-- %% -->
<!-- %% -->
<!-- %Y  (C) 1998 School Math and Comp. Sci., University of St Andrews, Scotland -->
<!-- %Y  Copyright (C) 2002 The GAP Group -->
<!-- %% -->
<Chapter Label="Records">
<Heading>Records</Heading>

<Index Subkey="records">type</Index>

<E>Records</E> are next to lists the most important way to collect objects
together. A record is a collection of <E>components</E>. Each component has
a unique <E>name</E>, which is an identifier that distinguishes this
component, and a <E>value</E>, which is an object of arbitrary type. We often
abbreviate <E>value of a component</E> to <E>element</E>. We also say that a
record <E>contains</E> its elements. You can access and change the elements
of a record using its name.
<P/>
Record literals are written by writing down the components in order between
<Q><C>rec(</C></Q> and <Q><C>)</C></Q>, and separating them by commas
<Q><C>,</C></Q>.
Each component consists of the name,
the assignment operator <Q><C>:=</C></Q>, and the value.
The <E>empty record</E>, i.e., the record with no components, is written as
<C>rec()</C>.
<P/>
<Example><![CDATA[
gap> rec( a := 1, b := "2" ); # a record with two components
rec( a := 1, b := "2" )
gap> rec( a := 1, b := rec( c := 2 ) ); # record may contain records
rec( a := 1, b := rec( c := 2 ) )
]]></Example>
<P/>
We may use the <Ref Oper="Display"/> function to illustrate the hierarchy of
the record components.
<P/>
<Example><![CDATA[
gap> Display( last );
rec(
  a := 1,
  b := rec(
      c := 2 ) )
]]></Example>
<P/>
Records usually contain elements of various types, i.e., they are usually
not homogeneous like lists.


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="sect:IsRecord">
<Heading>IsRecord and RecNames</Heading>

<#Include Label="IsRecord">
<#Include Label="RecNames">

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Accessing Record Elements">
<Heading>Accessing Record Elements</Heading>

<Index Subkey="record elements">accessing</Index>
<Index Subkey="component access">record</Index>
<C><A>r</A>.<A>name</A></C>
<P/>
The above construct evaluates to the value of the record component with
the name <A>name</A> in the record <A>r</A>. Note that the <A>name</A> is not
evaluated, i.e. it is taken literal.
<P/>
<Example><![CDATA[
gap> r := rec( a := 1, b := 2 );;
gap> r.a;
1
gap> r.b;
2
]]></Example>
<P/>
<Index Subkey="component variable">record</Index>
<C><A>r</A>.(<A>name</A>)</C>
<P/>
This construct is similar to the above construct. The difference is that
the second operand <A>name</A> is evaluated. It must evaluate to a string or
an integer otherwise an error is signalled. The construct then evaluates
to the element of the record <A>r</A> whose name is, as a string, equal to
<A>name</A>.
<P/>
<Example><![CDATA[
gap> old := rec( a := 1, b := 2 );;
gap> new := rec();
rec(  )
gap> for i in RecNames( old ) do
>  new.(i) := old.(i);
> od;
gap> Display( new );
rec(
  a := 1,
  b := 2 )
]]></Example>

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Record Assignment">
<Heading>Record Assignment</Heading>

<Index Subkey="to a record">assignment</Index>
<Index Subkey="component assignment">record</Index>
<C><A>r</A>.<A>name</A> := <A>obj</A></C>
<P/>
The record assignment assigns the object <A>obj</A>,
which may be an object of arbitrary type,
to the record component with the name <A>name</A>,
which must be an identifier, of the record <A>r</A>.
That means that accessing the element with name <A>name</A> of the record
<A>r</A> will return <A>obj</A> after this assignment.
If the record <A>r</A> has no component with the name <A>name</A>,
the record is automatically extended to make room for the new component.
<P/>
<Example><![CDATA[
gap> r := rec( a := 1, b := 2 );;
gap> r.a := 10;;
gap> Display( r );
rec(
  a := 10,
  b := 2 )
gap> r.c := 3;;
gap> Display( r );
rec(
  a := 10,
  b := 2,
  c := 3 )
]]></Example>
<P/>
Note that assigning to a record changes the record.
<P/>
The function <Ref Oper="IsBound" Label="for a record component"/>
can be used to test if a record has a component with a certain name,
the function <Ref Oper="Unbind" Label="unbind a record component"/>
can be used to remove a component with a certain name again.
<P/>
<Example><![CDATA[
gap> IsBound(r.a);
true
gap> IsBound(r.d);
false
gap> Unbind(r.b);
gap> Display( r );
rec(
  a := 10,
  c := 3 )
]]></Example>
<P/>
<Index Subkey="component variable assignment">record</Index>
<C><A>r</A>.(<A>name</A>) := <A>obj</A></C>
<P/>
This construct is similar to the above construct. The difference is that
the second operand <A>name</A> is evaluated. It must evaluate to a string or
an integer otherwise an error is signalled. The construct then assigns
<A>obj</A> to the record component of the record <A>r</A> whose name is,
as a string, equal to <A>name</A>.

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Identical Records">
<Heading>Identical Records</Heading>

With the record assignment (see <Ref Sect="Record Assignment"/>)
it is possible to change a record.
This section describes the semantic consequences of this fact which are
essentially the same as for lists (see&nbsp;<Ref Sect="Identical Lists"/>).
<P/>
<Log><![CDATA[
r := rec( a := 1 );
r := rec( a := 1, b := 2 );
]]></Log>
<P/>
The second assignment does not change the first record, instead it
assigns a new record to the variable <C>r</C>. On the other hand, in the
following example the record is changed by the second assignment.
<P/>
<Log><![CDATA[
r := rec( a := 1 );
r.b := 2;
]]></Log>
<P/>
To understand the difference first think of a variable as a name for an
object. The important point is that a record can have several names at
the same time.
An assignment <C><A>var</A> := <A>r</A></C> means in this interpretation
that <A>var</A> is a name for the object <A>r</A>.
At the end of the following example <C>r2</C> still has the value
<C>rec( a := 1 )</C> as this record has not been changed and nothing else
has been assigned to <C>r2</C>.
<P/>
<Log><![CDATA[
r1 := rec( a := 1 );
r2 := r1;
r1 := rec( a := 1, b := 2 );
]]></Log>
<P/>
But after the following example the record for which <C>r2</C> is a name has
been changed and thus the value of <C>r2</C> is now
<C>rec( a := 1, b := 2 )</C>.
<P/>
<Log><![CDATA[
r1 := rec( a := 1 );
r2 := r1;
r1.b := 2;
]]></Log>
<P/>
We shall say that two records are <E>identical</E> if changing one of them by
a record assignment also changes the other one. This is slightly
incorrect, because if <E>two</E> records are identical, there are actually
only two names for <E>one</E> record. However, the correct usage would be
very awkward and would only add to the confusion.  Note that two
identical records must be equal, because there is only one records with
two different names. Thus identity is an equivalence relation that is a
refinement of equality.
<P/>
Let us now consider under which circumstances two records are identical.
<P/>
If you enter a record literal then the record denoted by this literal is
a new record that is not identical to any other record.
Thus in the following example <C>r1</C> and <C>r2</C> are not identical,
though they are equal of course.
<P/>
<Log><![CDATA[
r1 := rec( a := 1 );
r2 := rec( a := 1 );
]]></Log>
<P/>
Also in the following example, no records in the list <C>l</C> are identical.
<P/>
<Log><![CDATA[
l := [];
for i in [1..10] do
  l[i] := rec( a := 1 );
od;
]]></Log>
<P/>
If you assign a record to a variable no new record is created. Thus the
record value of the variable on the left hand side and the record on the
right hand side of the assignment are identical. So in the following
example <C>r1</C> and <C>r2</C> are identical records.
<P/>
<Log><![CDATA[
r1 := rec( a := 1 );
r2 := r1;
]]></Log>
<P/>
If you pass a record as argument, the old record and the argument of the
function are identical. Also if you return a record from a function, the
old record and the value of the function call are identical. So in the
following example <C>r1</C> and <C>r2</C> are identical records.
<P/>
<Log><![CDATA[
r1 := rec( a := 1 );
f := function ( r ) return r; end;
r2 := f( r1 );
]]></Log>
<P/>
The functions <Ref Func="StructuralCopy"/> and <Ref Oper="ShallowCopy"/>
accept a record and return a new record that is equal to the
old record but that is <E>not</E> identical to the old record.
The difference between <Ref Func="StructuralCopy"/> and
<Ref Oper="ShallowCopy"/> is that in the case of
<Ref Oper="ShallowCopy"/> the corresponding components of the new and the
old records will be identical,
whereas in the case of <Ref Func="StructuralCopy"/> they will only be equal.
So in the following example <C>r1</C> and <C>r2</C> are not identical records.
<P/>
<Log><![CDATA[
r1 := rec( a := 1 );
r2 := ShallowCopy( r1 );
]]></Log>
<P/>
If you change a record it keeps its identity. Thus if two records are
identical and you change one of them, you also change the other, and they
are still identical afterwards. On the other hand, two records that are
not identical will never become identical if you change one of them. So
in the following example both <C>r1</C> and <C>r2</C> are changed,
and are still identical.
<P/>
<Log><![CDATA[
r1 := rec( a := 1 );
r2 := r1;
r1.b := 2;
]]></Log>
<P/>
</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Comparisons of Records">
<Heading>Comparisons of Records</Heading>

<Index Subkey="of records">equality</Index>
<Index Subkey="of records">inequality</Index>
<C><A>rec1</A> = <A>rec2</A></C>
<P/>
<C><A>rec1</A> &lt;> <A>rec2</A></C>
<P/>
Two records are considered equal, if for each component of one
record the other record has a component of the same name with an equal
value and vice versa.
<P/>
<Example><![CDATA[
gap> rec( a := 1, b := 2 ) = rec( b := 2, a := 1 );
true
gap> rec( a := 1, b := 2 ) = rec( a := 2, b := 1 );
false
gap> rec( a := 1 ) = rec( a := 1, b := 2 );
false
gap> rec( a := 1 ) = 1;
false
]]></Example>
<P/>
<Index Subkey="of records">ordering</Index>
<C><A>rec1</A> &lt; <A>rec2</A></C>
<P/>
<C><A>rec1</A> &lt;= <A>rec2</A></C>
<P/>
To compare records we imagine that the components of both records are
sorted according to their names (the sorting depends on the &GAP; session,
more precisely the order in which component names were first used).
Then the records are compared lexicographically with unbound elements
considered smaller than anything else.
Precisely one record <A>rec1</A> is considered less than another record
<A>rec2</A> if <A>rec2</A> has a component with name <A>name2</A> and either
<A>rec1</A> has no component with this name or
<C><A>rec1</A>.<A>name2</A> &lt; <A>rec2</A>.<A>name2</A></C>
and for each component of <A>rec1</A> with name
<C><A>name1</A> &lt; <A>name2</A></C> <A>rec2</A> has a
component with this name and
<C><A>rec1</A>.<A>name1</A> = <A>rec2</A>.<A>name1</A></C>.
<P/>
<Example><![CDATA[
gap> rec( axy := 1, bxy := 2 ) < rec( bxy := 2, axy := 1 ); # are equal
false
gap> rec( axy := 1 ) < rec( axy := 1, bxy := 2 ); # unbound is < 2
true
gap> # in new session the .axy components are compared first
gap> rec( axy := 1, bxy := 2 ) < rec( axy := 2, bxy := 0 ); # 1 < 2
true
gap> rec( axy := 1 ) < rec( axy := 0, bxy := 2 ); # 0 < 1
false
gap> rec( bxy := 1 ) < rec( bxy := 0, axy := 2 ); # unbound is < 2
true
]]></Example>

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="IsBound and Unbind for Records">
<Heading>IsBound and Unbind for Records</Heading>

<ManSection>
<Oper Name="IsBound" Arg='r.name' Label="for a record component"/>

<Description>
<Ref Oper="IsBound" Label="for a record component"/> returns <K>true</K>
if the record <A>r</A> has a component with the name <A>name</A>
(which must be an identifier) and <K>false</K> otherwise.
<A>r</A> must evaluate to a record, otherwise an error is signalled.
<P/>
<Example><![CDATA[
gap> r := rec( a := 1, b := 2 );;
gap> IsBound( r.a );
true
gap> IsBound( r.c );
false
]]></Example>
</Description>
</ManSection>


<ManSection>
<Oper Name="Unbind" Arg='r.name' Label="unbind a record component"/>

<Description>
<Ref Oper="Unbind" Label="unbind a record component"/> deletes the component
with the name <A>name</A> in the record <A>r</A>. That is, after
execution of <Ref Oper="Unbind" Label="unbind a record component"/>,
<A>r</A> no longer has a record component with this name.
Note that it is not an error to unbind a nonexisting record component.
<A>r</A> must evaluate to a record, otherwise an error is signalled.
<P/>
<Example><![CDATA[
gap> r := rec( a := 1, b := 2 );;
gap> Unbind( r.a ); r;
rec( b := 2 )
gap> Unbind( r.c ); r;
rec( b := 2 )
]]></Example>
<P/>
Note that <Ref Oper="IsBound" Label="for a record component"/> and
<Ref Oper="Unbind" Label="unbind a record component"/> are special
in that they do not evaluate their argument,
otherwise <Ref Oper="IsBound" Label="for a record component"/>
would always signal an error when it is supposed to return <K>false</K>
and there would be no way to tell
<Ref Oper="Unbind" Label="unbind a record component"/>
which component to remove.
</Description>
</ManSection>

</Section>


<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<Section Label="Record Access Operations">
<Heading>Record Access Operations</Heading>

Internally, record accesses are done using the operations listed in this
section. For the records implemented in the kernel, kernel methods are
provided for all these operations but otherwise it is possible to install
methods for these operations for any object. This
permits objects to simulate record behavior.
<P/>
To save memory, records do not store a list of all component names, but only
numbers identifying the components. There numbers are called <E>RNams</E>.
&GAP; keeps a global list of all RNams that are used and provides
the functions <Ref Func="NameRNam"/> and
<Ref Func="RNamObj" Label="for a string"/>
to translate RNams to strings that give the component names and vice versa.

<ManSection>
<Func Name="NameRNam" Arg='nr'/>

<Description>
returns a string representing the component name corresponding to the RNam
<A>nr</A>.
</Description>
</ManSection>


<ManSection>
<Func Name="RNamObj" Arg='str' Label="for a string"/>
<Func Name="RNamObj" Arg='int' Label="for a positive integer"/>

<Description>
returns a number (the RNam) corresponding to the string <A>str</A>. It is also
possible to pass a positive integer <A>int</A> in which case the decimal expansion of
<A>int</A> is used as a string.
<P/>
<Log><![CDATA[
gap> NameRNam(798);
"BravaisSupergroups"
gap> RNamObj("blubberflutsch");
2075
gap> NameRNam(last);
"blubberflutsch"
]]></Log>
<P/>
The correspondence between strings and RNams is not predetermined ab initio,
but RNams are assigned to component names dynamically on a
<Q>first come, first serve</Q> basis.
Therefore, depending on the version of the library you are using and on the
assignments done so far, the <E>same</E> component name may be represented
by <E>different</E> RNams in different &GAP; sessions.
</Description>
</ManSection>


<ManSection>
<Oper Name="\." Arg='obj, rnam'/>
<Oper Name="IsBound\." Arg='obj, rnam'/>
<Oper Name="\.\:\=" Arg='obj, rnam, val'/>
<Oper Name="Unbind\." Arg='obj, rnam'/>

<Description>
<Index Subkey="operation">record component</Index>
<Index Subkey="operation">record boundness test</Index>
<Index Subkey="operation">record assignment</Index>
<Index Subkey="operation">record unbind</Index>
These operations are called for record accesses to arbitrary objects.
If applicable methods are installed, they are called when the
object is accessed as a record.
<P/>
For records, the operations implement component access,
test for element boundness,
component assignment and removal of the component represented by the RNam
<A>rnam</A>.
<P/>
The component identifier <A>rnam</A> is always required to be in
<Ref Filt="IsPosInt"/>.
<P/>
<Example><![CDATA[
gap> r:= rec( a:= 1 );;
gap> IsBound\.( r, RNamObj( "a" ) );
true
gap> \.( r, RNamObj( "a" ) );
1
gap> IsBound\.( r, RNamObj( "b" ) );
false
gap> \.\:\=( r, RNamObj( "b" ), 2 );
gap> r;
rec( a := 1, b := 2 )
gap> Unbind\.( r, RNamObj( "b" ) );
gap> r;
rec( a := 1 )
gap> G:= SymmetricGroup( 4 );;
gap> G.1;
(1,2,3,4)
gap> \.( G, RNamObj( 1 ) );
(1,2,3,4)
gap> meth:= ApplicableMethod( \., [ G, 4711 ] );;
gap> meth( G, RNamObj( 1 ) );
(1,2,3,4)
]]></Example>
</Description>
</ManSection>

</Section>
</Chapter>