Goto Chapter: Top 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 Bib Ind
[Top of Book] [Contents] [Previous Chapter] [Next Chapter]

[MathJax off]

29 Records
29.1 IsRecord and RecNames
29.1-1 IsRecord
29.1-2 RecNames
29.2 Accessing Record Elements
29.3 Record Assignment
29.4 Identical Records
29.5 Comparisons of Records
29.6 IsBound and Unbind for Records
29.6-1 IsBound
29.6-2 Unbind
29.7 Record Access Operations
29.7-1 NameRNam
29.7-2 RNamObj
29.7-3 \.

### 29 Records

Records are next to lists the most important way to collect objects together. A record is a collection of components. Each component has a unique name, which is an identifier that distinguishes this component, and a value, which is an object of arbitrary type. We often abbreviate value of a component to element. We also say that a record contains its elements. You can access and change the elements of a record using its name.

Record literals are written by writing down the components in order between "`rec(`" and "`)`", and separating them by commas "`,`". Each component consists of the name, the assignment operator "`:=`", and the value. The empty record, i.e., the record with no components, is written as `rec()`.

    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 ) )

We may use the `Display` (6.3-6) function to illustrate the hierarchy of the record components.

    gap> Display( last );
    rec(
      a := 1,
      b := rec(
          c := 2 ) )

Records usually contain elements of various types, i.e., they are usually not homogeneous like lists.

#### 29.1 IsRecord and RecNames

##### 29.1-1 IsRecord

`‣ IsRecord`( obj ) | ( category )

`‣ IsRecordCollection`( obj ) | ( category )

`‣ IsRecordCollColl`( obj ) | ( category )

    gap> IsRecord( rec( a := 1, b := 2 ) );
    true
    gap> IsRecord( IsRecord );
    false

##### 29.1-2 RecNames

`‣ RecNames`( record ) | ( attribute )

returns a list of strings corresponding to the names of the record components of the record record.

    gap> r := rec( a := 1, b := 2 );;
    gap> Set(RecNames( r )); # 'Set' because ordering depends on GAP session
    [ "a", "b" ]

Note that you cannot use the string result in the ordinary way to access or change a record component. You can use the `record.(name)` construct for that, see 29.2 and 29.3.

#### 29.2 Accessing Record Elements

`r.name`

The above construct evaluates to the value of the record component with the name name in the record r. Note that the name is not evaluated, i.e. it is taken literal.

    gap> r := rec( a := 1, b := 2 );;
    gap> r.a;
    1
    gap> r.b;
    2

`r.(name)`

This construct is similar to the above construct. The difference is that the second operand name 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 r whose name is, as a string, equal to name.

    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 )

#### 29.3 Record Assignment

`r.name := obj`

The record assignment assigns the object obj, which may be an object of arbitrary type, to the record component with the name name, which must be an identifier, of the record r. That means that accessing the element with name name of the record r will return obj after this assignment. If the record r has no component with the name name, the record is automatically extended to make room for the new component.

    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 )

Note that assigning to a record changes the record.

The function `IsBound` (29.6-1) can be used to test if a record has a component with a certain name, the function `Unbind` (29.6-2) can be used to remove a component with a certain name again.

    gap> IsBound(r.a);
    true
    gap> IsBound(r.d);
    false
    gap> Unbind(r.b);
    gap> Display( r );
    rec(
      a := 10,
      c := 3 )

`r.(name) := obj`

This construct is similar to the above construct. The difference is that the second operand name is evaluated. It must evaluate to a string or an integer otherwise an error is signalled. The construct then assigns obj to the record component of the record r whose name is, as a string, equal to name.

#### 29.4 Identical Records

With the record assignment (see 29.3) 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 21.6).

    r := rec( a := 1 );
    r := rec( a := 1, b := 2 );

The second assignment does not change the first record, instead it assigns a new record to the variable `r`. On the other hand, in the following example the record is changed by the second assignment.

    r := rec( a := 1 );
    r.b := 2;

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 `var := r` means in this interpretation that var is a name for the object r. At the end of the following example `r2` still has the value `rec( a := 1 )` as this record has not been changed and nothing else has been assigned to `r2`.

    r1 := rec( a := 1 );
    r2 := r1;
    r1 := rec( a := 1, b := 2 );

But after the following example the record for which `r2` is a name has been changed and thus the value of `r2` is now `rec( a := 1, b := 2 )`.

    r1 := rec( a := 1 );
    r2 := r1;
    r1.b := 2;

We shall say that two records are identical if changing one of them by a record assignment also changes the other one. This is slightly incorrect, because if two records are identical, there are actually only two names for one 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.

Let us now consider under which circumstances two records are identical.

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 `r1` and `r2` are not identical, though they are equal of course.

    r1 := rec( a := 1 );
    r2 := rec( a := 1 );

Also in the following example, no records in the list `l` are identical.

    l := [];
    for i in [1..10] do
      l[i] := rec( a := 1 );
    od;

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 `r1` and `r2` are identical records.

    r1 := rec( a := 1 );
    r2 := r1;

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 `r1` and `r2` are identical records.

    r1 := rec( a := 1 );
    f := function ( r ) return r; end;
    r2 := f( r1 );

The functions `StructuralCopy` (12.7-2) and `ShallowCopy` (12.7-1) accept a record and return a new record that is equal to the old record but that is not identical to the old record. The difference between `StructuralCopy` (12.7-2) and `ShallowCopy` (12.7-1) is that in the case of `ShallowCopy` (12.7-1) the corresponding components of the new and the old records will be identical, whereas in the case of `StructuralCopy` (12.7-2) they will only be equal. So in the following example `r1` and `r2` are not identical records.

    r1 := rec( a := 1 );
    r2 := ShallowCopy( r1 );

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 `r1` and `r2` are changed, and are still identical.

    r1 := rec( a := 1 );
    r2 := r1;
    r1.b := 2;

#### 29.5 Comparisons of Records

`rec1 = rec2`

`rec1 <> rec2`

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.

    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

`rec1 < rec2`

`rec1 <= rec2`

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 rec1 is considered less than another record rec2 if rec2 has a component with name name2 and either rec1 has no component with this name or `rec1.name2 < rec2.name2` and for each component of rec1 with name `name1 < name2` rec2 has a component with this name and `rec1.name1 = rec2.name1`.

    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

#### 29.6 IsBound and Unbind for Records

##### 29.6-1 IsBound

`‣ IsBound`( r.name ) | ( operation )

`IsBound` returns `true` if the record r has a component with the name name (which must be an identifier) and `false` otherwise. r must evaluate to a record, otherwise an error is signalled.

    gap> r := rec( a := 1, b := 2 );;
    gap> IsBound( r.a );
    true
    gap> IsBound( r.c );
    false

##### 29.6-2 Unbind

`‣ Unbind`( r.name ) | ( operation )

`Unbind` deletes the component with the name name in the record r. That is, after execution of `Unbind`, r no longer has a record component with this name. Note that it is not an error to unbind a nonexisting record component. r must evaluate to a record, otherwise an error is signalled.

    gap> r := rec( a := 1, b := 2 );;
    gap> Unbind( r.a ); r;
    rec( b := 2 )
    gap> Unbind( r.c ); r;
    rec( b := 2 )

Note that `IsBound` (29.6-1) and `Unbind` are special in that they do not evaluate their argument, otherwise `IsBound` (29.6-1) would always signal an error when it is supposed to return `false` and there would be no way to tell `Unbind` which component to remove.

#### 29.7 Record Access Operations

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.

To save memory, records do not store a list of all component names, but only numbers identifying the components. There numbers are called RNams. GAP keeps a global list of all RNams that are used and provides functions to translate RNams to strings that give the component names and vice versa.

##### 29.7-1 NameRNam

`‣ NameRNam`( nr ) | ( function )

returns a string representing the component name corresponding to the RNam nr.

##### 29.7-2 RNamObj

`‣ RNamObj`( str ) | ( function )

`‣ RNamObj`( int ) | ( function )

returns a number (the RNam) corresponding to the string str. It is also possible to pass a positive integer int in which case the decimal expansion of int is used as a string.

    gap> NameRNam(798);
    "BravaisSupergroups"
    gap> RNamObj("blubberflutsch");
    2075
    gap> NameRNam(last);
    "blubberflutsch"

The correspondence between strings and RNams is not predetermined ab initio, but RNams are assigned to component names dynamically on a "first come, first serve" basis. Therefore, depending on the version of the library you are using and on the assignments done so far, the same component name may be represented by different RNams in different GAP sessions.

##### 29.7-3 \.

`‣ \.`( obj, rnam ) | ( operation )

`‣ IsBound\.`( obj, rnam ) | ( operation )

`‣ \.\:\=`( obj, rnam, val ) | ( operation )

`‣ Unbind\.`( obj, rnam ) | ( operation )

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.

For records, the operations implement component access, test for element boundness, component assignment and removal of the component represented by the RNam rnam.

The component identifier rnam is always required to be in `IsPosInt` (14.2-2).

[Top of Book] [Contents] [Previous Chapter] [Next Chapter]
Goto Chapter: Top 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 Bib Ind

generated by GAPDoc2HTML