Skip to main content

DICTIONARY

attr := DICTIONARY( dataset, structure );

DICTIONARY( structure )

attrThe name of the DICTIONARY for later use in other definitions.
datasetThe name of a DATASET or recordset from which to derive the DICTIONARY. This may be defined inline (similar to an inline DATASET).
structureThe RECORD structure (often defined inline) specifying the layout of the fields. The first field(s) are key fields, optionally followed the "results in" operator (=>) and additional payload fields. This is similar to the payload version of an INDEX. The payload may specify individual fields or may use the name of the dataset to payload all the non-key fields.

A DICTIONARY allows you to efficiently check whether a particular data value is in a list (using the IN operator), or to simply map data. It is similar to a LOOKUP JOIN that can be used in any context.

DICTIONARY Definition

The DICTIONARY declaration defines a set of unique records derived from the dataset parameter and indexed by the first field(s) named in the structure parameter. The DICTIONARY will contain one record for each unique value(s) in the key field(s). You can access an individual record by appending square brackets ( [ ] ) to the attr name of the DICTIONARY, which contain the key field value(s) that identify the specific record to access.

DICTIONARY as a Value Type

The second form of DICTIONARY is a value type with the structure parameter specifying the RECORD structure of the data. This data type usage allows you to specify a DICTIONARY as a child dataset, similar to the way DATASET may be used to define a child dataset. This may also be used to pass a DICTIONARY as a parameter.

Example:

ColorCodes := DATASET([{'Black' ,0 },
                       {'Brown' ,1 },
                       {'Red'   ,2 },
                       {'Orange',3 },
                       {'Yellow',4 },
                       {'Green' ,5 },
                       {'Blue'  ,6 },
                       {'Violet',7 },
                       {'Grey'  ,8 },
                       {'White' ,9 }], {STRING color,UNSIGNED1 code});

ColorCodesDCT := DICTIONARY(ColorCodes,{Color,Code});    //multi-field key
ColorCodeDCT  := DICTIONARY(ColorCodes,{Color => Code}); //payload field
CodeColorDCT  := DICTIONARY(ColorCodes,{Code => Color});

//mapping examples
MapCode2Color(UNSIGNED1 code) := CodeColorDCT[code].color;
MapColor2Code(STRING color)   := ColorCodeDCT[color].code;

OUTPUT(MapColor2Code('Red'));     //2
OUTPUT(MapCode2Color(4));         //'Yellow'

//Search term examples
OUTPUT('Green' IN ColorCodeDCT);  //true
OUTPUT(6 IN CodeColorDCT);        //true
OUTPUT(ROW({'Red',2},RECORDOF(ColorCodes)) IN ColorCodesDCT); //multi-field key, true 

//multi-field payload examples
rec := RECORD
  STRING10  color;
  UNSIGNED1 code; 
  STRING10  name;
END;
Ds := DATASET([{'Black' ,0 , 'Fred'},
               {'Brown' ,1 , 'Seth'},
               {'Red'   ,2 , 'Sue'},
               {'White' ,3 , 'Jo'}], rec);

DsDCT := DICTIONARY(DS,{color => DS});

OUTPUT('Red' IN DsDCT); //true
DsDCT['Red'].code;      //2
DsDCT['Red'].name;      //Sue

//inline DCT examples
InlineDCT := DICTIONARY([{'Black' => 0 , 'Fred'},
                         {'Brown' => 1 , 'Sam'},
                         {'Red'   => 2 , 'Sue'},
                         {'White' => 3 , 'Jo'} ], 
                        {STRING10 color => UNSIGNED1 code,STRING10 name});

OUTPUT('Red' IN InlineDCT); //true
InlineDCT['Red'].code;      //2
InlineDCT['Red'].name;      //Sue
InlineDCT['Red'];           //Red   2   Sue

//Form 2 examples -- parameter passing
MyDCTfunc(DICTIONARY({STRING10 color => UNSIGNED1 code,STRING10 name}) DCT,
          STRING10 key) := DCT[key].name;
MyDCTfunc(InlineDCT,'White');  //Jo
MyDCTfunc(DsDCT,'Brown');      //Seth

See Also: DATASET, RECORD Structure, INDEX, IN Operator