Welcome To Our Shell

Mister Spy & Souheyl Bypass Shell

  
  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().
  
    Example  
    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.
  
    Example  
    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
  
    Example  
    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.
  
    Example  
    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.
  
    Example  
    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.
  
    Example  
    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.
  
    Example  
    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.
  
    Example  
    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).
  
    Example  
    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.
  
    Example  
    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.
  
    Example  
    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 ).
  
    Example  
    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.
  
    Example  
    r1 := rec( a := 1 );
    r2 := rec( a := 1 );
  
  
  Also in the following example, no records in the list l are identical.
  
    Example  
    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.
  
    Example  
    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.
  
    Example  
    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.
  
    Example  
    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.
  
    Example  
    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.
  
    Example  
    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.
  
    Example  
    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.
  
    Example  
    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.
  
    Example  
    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.
  
    Example  
    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).