---
name: "VistaIOdictionary"
section: "3"
platform: "linux"
package: "libvistaio-dev"
version: "1.2.19-3+b2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/VistaIOdictionary"
---

# VistaIOdictionary(3)

representation of a keyword/value mapping

## NAME

VistaIOdictionary - representation of a keyword/value mapping

## SYNPOSIS

```
VistaIODictEntry dictionary[] = {
{ "keyword", integer_value },
{ "keyword", 0, string_value },
...
{ NULL }
};
```

## DESCRIPTION

**This manual page documents a data structure, called a** *dictionary***, for**  **describing a mapping between keywords and values. Dictionaries are used by**  **the Vista library to interpret keywords present in command line options and**  **in data files. Library routines are available for locating dictionary**  **entries by keyword and by value.**

### Data Structure

```
typedef struct {
VistaIOStringConst keyword;	/* keyword string */
VistaIOLong ivalue;	/* value, if an integer */
VistaIOStringConst svalue;	/* value, if a string */
VistaIOBoolean icached;	/* whether integer value cached */
VistaIOBoolean fcached;	/* whether float value cached */
VistaIODouble fvalue;	/* cached floating-point value */
} VistaIODictEntry;
```

**The dictionary data structure is designed to permit any string or numeric**  **value to be associated with a keyword, and to permit the use of**  **statically-initialized dictionaries.**

**A dictionary is an array of VistaIODictEntry structures. The last entry in**  **the array has a** *keyword* **field of**  **NULL** **while each preceding entry contains both a keyword and a value. When the**  **dictionary is initialized each value can be represented either as an**  **integer in the** *ivalue* **field (in which case** *svalue* **must be**  **NULL** **) or as a string pointed to by the** *svalue* **field (in which case the**  *ivalue* **field is irrelevant). A floating point number is incorporated**  **as a string value containing the number in printable form. The \`\`EXAMPLES''**  **section, below, shows typical code for establishing dictionaries.**

**Other fields of the VistaIODictEntry are only used internally by the**  **VistaIOLookupDictValue routine, which provides one form of access to**  **dictionaries. The fields are used to cache the results of having converted**  **a string value to an integer or a floating-point number. When an entry**  **contains a string value (***svalue* **is not** **NULL** **) then** *icached* **and** *fcached* **indicate whether or not equivalent** **integer and floating-point values are also cached in** *ivalue* **and** *fvalue***. When creating a dictionary, initialize** *icached* **and** *fcached* **to zero; this need not be done explicitly if the dictionary** **is initialized statically as shown under \`\`EXAMPLES''.**

### Routines

**With the following routines a dictionary entry can be located either by** **keyword or by value. Both routines search a dictionary sequentially from** **first entry to last, returning the first matching entry encountered.**

**VistaIODictEntry \*VistaIOLookupDictKeyword (VistaIODictEntry \**dict*,** **VistaIOStringConst *keyword*)**

-

  **VistaIOLookupDictEntry searches the dictionary** *dict* **for an entry** **whose keyword is** *keyword***. It returns a pointer to the entry, if** **found, or** **NULL** **otherwise.**

**VistaIODictEntry \*VistaIOLookupDictValue (VistaIODictEntry \**dict*,** **VistaIORepnKind *repn*, *type value*)**

-

  **VistaIOLookupDictValue searches the dictionary** *dict* **for an entry** **whose value is** *value***. The value to be searched for can be specified** **in any of several representations; that chosen is indicated by** *repn***.** **Then** *type* **is one of VistaIOBit, VistaIOUByte, VistaIOSByte,** **VistaIOShort, VistaIOLong, VistaIOFloat, VistaIODouble, VistaIOBoolean, or** **VistaIOString, depending on** *repn***.  VistaIOLookupDictValue returns a** **pointer to the entry, if found, or** **NULL** **otherwise.**

### Built-in Dictionaries

**The following dictionaries are already included in the library:**

- **VistaIOBooleanDict**

  **maps between the keywords false, true, no, yes,** **off, and on and the values** **FALSE** **and** **TRUE**

- **VistaIONumericRepnDict**

  **maps between the keywords bit, ubyte, sbyte, short,** **long, float, and double and the values VistaIOBitRepn through VistaIODoubleRepn.**

## EXAMPLES

**This dictionary describes a mapping between keywords and integers:**

```
VistaIODictEntry VistaIOBooleanDict[] = {
{ "false", FALSE }, { "true", TRUE },
{ "no", FALSE }, { "yes", TRUE },
{ "off", FALSE }, { "on", TRUE },
{ NULL }
};
```

**This dictionary describes a mapping between keywords and floating point** **numbers:**

```
VistaIODictEntry ConstantDict[] = {
{ "zero", 0 }, { "one", 1 },
{ "pi", 0, "3.14159" }, { "e", 0, "2.7182818" },
{ NULL }
};
```

**This dictionary describes a mapping between keywords and strings:**

```
VistaIODictEntry TitleDict[] = {
{ "Clinton", 0, "President of the U.S.A." },
{ "Major", 0, "Prime Minister of Great Britain" },
{ "Mulroney", 0, "Prime Minister of Canada" },
{ NULL }
};
```

## AUTHOR

**Art Pope \<pope@cs.ubc.ca\>**

**Adaption to vistaio: Gert Wollny \<gw.fossdev@gmail.com\>**