lookup()

Function

Looks up data in a string array.

Syntax

string lookup(string array[], string key, int field_index[, char separator]);
string lookup(string array[], string key, string field_name[, char separator]);

Returns

lookup returns the value of the field identified by field_index or field_name.
If the field doesn't exist, or no string matching key is found, an empty string is returned.

An array that can be used with lookup() consists of strings of text, each string representing one data record.

Each data record contains an arbitrary number of fields, which are separated by the character separator (default is '\t', the tabulator). The first field in a record is used as the key and is numbered 0.

All records must have unique key fields and none of the key fields may be empty - otherwise it is undefined which record will be found.

If the first string in the array contains a "Header" record (i.e. a record where each field describes its contents), using lookup with a field_name string automatically determines the index of that field. This allows using the lookup function without exactly knowing which field index contains the desired data.
It is up to the user to make sure that the first record actually contains header information.

If the key parameter in the call to lookup() is an empty string, the first string of the array will be used. This allows a program to determine whether there is a header record with the required field names.

If a field contains the separator character, that field must be enclosed in double quotes (as in "abc;def", assuming the semicolon (';') is used as separator). The same applies if the field contains double quotes ("), in which case the double quotes inside the field have to be doubled (as in "abc;""def"";ghi", which would be abc;"def";ghi).
It is best to use the default "tab" separator, which doesn't have these problems (no field can contain a tabulator).

Here's an example data file (';' has been used as separator for better readability):

Name;Manufacturer;Code;Price
7400;Intel;I-01-234-97;$0.10
68HC12;Motorola;M68HC1201234;$3.50

Example

string OrderCodes[];
if (fileread(OrderCodes, "ordercodes") > 0) {
   if (lookup(OrderCodes, "", "Code", ';')) {
      schematic(SCH) {
        SCH.parts(P) {
          string OrderCode;
          // both following statements do exactly the same:
          OrderCode = lookup(OrderCodes, P.device.name, "Code", ';');
          OrderCode = lookup(OrderCodes, P.device.name, 2, ';');
          }
        }
      }
   else
      dlgMessageBox("Missing 'Code' field in file 'ordercodes');
   }