GAP (Utils) - Chapter 8: Records

Goto Chapter: Top 1 2 3 4 5 6 7 8 9 10 11 12 13 Bib Ind
[Top of Book] [Contents] [Previous Chapter] [Next Chapter]

[MathJax on]

8 Records
8.1 Functions for records
8.1-1 AssignGlobals
8.2 Option records for functions
8.2-1 OptionRecordWithDefaults

### 8 Records

#### 8.1 Functions for records

##### 8.1-1 AssignGlobals

`‣ AssignGlobals`( rec ) | ( function )

This function has been transferred from package RCWA.

It assigns the record components of rec to global variables with the same names.

    gap> r := rec( a := 1, b := 2, c := 3 );;
    gap> AssignGlobals( r );
    The following global variables have been assigned:
    [ "a", "b", "c" ]
    gap> [a,b,c];
    [ 1, 2, 3 ]

#### 8.2 Option records for functions

##### 8.2-1 OptionRecordWithDefaults

`‣ OptionRecordWithDefaults`( defaults, useroptions ) | ( function )

This functions has been transferred by Chris Jefferson from other packages. It simplifies the handling of records which are intended to be used for expressing configuration options. defaults represents the "default record", and useroptions lets the user give new values for values in defaults.

The function returns a record with the same component names as defaults and which has the same values as defaults, except for those component names in useroptions, where the values in useroptions are used instead. An error is given if useroptions contains any component names not in defaults. If useroptions is an empty list it is treated as an empty record, and if useroptions is a list of length 1 containing a record, this record is used as useroptions.

    gap> defaults := rec( a := 1, b := 2, c := 3 );;
    gap> OptionRecordWithDefaults( defaults, rec( a := 6) );
    rec( a := 6, b := 2, c := 3 )
    gap> OptionRecordWithDefaults( defaults, rec( b := 7, c := 8 ) );
    rec( a := 1, b := 7, c := 8 )
    gap> OptionRecordWithDefaults( defaults, [ ] );
    rec( a := 1, b := 2, c := 3 )
    gap> OptionRecordWithDefaults( defaults, [ rec( c := 8 ) ] );
    rec( a := 1, b := 2, c := 8 )
    gap> OptionRecordWithDefaults( defaults, rec( d := 9 ) );
    Error, Unknown option: d
    gap> OptionRecordWithDefaults( defaults, [ rec( b := 7 ), rec( c := 8 ) ] );
    Error, Too many arguments for function
    gap> OptionRecordWithDefaults( defaults, [6,7,8] );
    Error, Too many arguments for function

This function is designed to support functions with optional arguments given as a variable record, of the form `function(x,y,options...)`.

In the following, very contrived, example function, `PrintDimensions`, the defaults are given by the variable `order` which takes values `h`, `w` and `d` having default values 1, 2 and 3. If there is a second argument, then `OptionRecordWithDefaults( order, arg[2] );` is used to change the values. These three values then determine the order in which the three dimensions are printed using a `SortParallel` command.

    gap> PrintDimensions := function( arg )
    >    local nargs, dim, order, V, L, len, K, i;
    >    nargs := Length( arg );
    >    dim := [ arg[1]!.height, arg[1]!.width, arg[1]!.depth ];
    >    order := rec( h := 1, w := 2, d := 3 );
    >    V := [ "height", "width", "depth" ];
    >    if ( nargs > 1 ) and IsRecord( arg[2] ) then
    >        order := OptionRecordWithDefaults( order, arg[2] );
    >    fi;
    >    L := [ order!.h, order!.w, order!.d ];
    >    len := Length( L );
    >    K := [ 1..len ];
    >    SortParallel( L, K );
    >    Print( "dimensions: " );
    >    Print( V[K[1]], " = ", dim[K[1]], ", " );
    >    Print( V[K[2]], " = ", dim[K[2]], ", " );
    >    Print( V[K[3]], " = ", dim[K[3]], "\n" );
    > end;;

In the example below the first call to `PrintDimensions` has just one parameter, `mydim`, so the default order is used. In the second call, alternate values for `h`, `w` and `d` are given, causing the width to be printed first, and then the depth and height.

    gap> mydim := rec( height := 45, width := 31, depth := 17 );
    rec( depth := 17, height := 45, width := 31 )
    gap> PrintDimensions( mydim );
    dimensions: height = 45, width = 31, depth = 17
    gap> PrintDimensions( mydim, rec( h:=3, w:=1, d:=2 ) );
    dimensions: width = 31, depth = 17, height = 45

[Top of Book] [Contents] [Previous Chapter] [Next Chapter]
Goto Chapter: Top 1 2 3 4 5 6 7 8 9 10 11 12 13 Bib Ind

generated by GAPDoc2HTML