VistaIOdictionary(3)

🎀 NAME 🎀

VistaIOdictionary — a representation of a keyword/value mapping 💖

hey bestie, you've landed on VistaIOdictionary(3), straight out of the Library Functions Manual. it's giving "glorified lookup table" but honestly? iconic. ✨

---

🦋 SYNPOSIS 🦋

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

(and yes, the heading above really is spelled SYNPOSIS, that's just how this page rolls, we love her anyway 💀)

---

✨ DESCRIPTION ✨

okay so this whole page is about one data structure, and it's called a dictionary. its entire job is describing a mapping between keywords and values. no cap.

the Vista library uses dictionaries to interpret the keywords that show up in command line options and in data files. and because the library is a considerate queen, there are library routines available for locating dictionary entries by keyword and by value. so you can search either direction, whatever slays for you. 💅

---

🧚 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;

so the dictionary data structure is designed to let any string or numeric value be associated with a keyword, and it's also designed to let you use statically-initialized dictionaries. lowkey genius.

a dictionary is an array of VistaIODictEntry structures. the last entry in the array has a keyword field of NULL, while every entry before it holds both a keyword and a value. 🫶

when the dictionary is initialized, each value can be represented either as:

• an integer in the ivalue field — and in that case svalue must be NULL
• a string pointed to by the svalue field — and in that case the ivalue field is irrelevant

a floating point number gets incorporated as a string value containing the number in printable form. the EXAMPLES section, below, shows typical code for establishing dictionaries. 👑

the other fields of the VistaIODictEntry are only used internally by the VistaIOLookupDictValue routine, which provides one form of access to dictionaries. those fields are there to cache the results of having converted a string value into an integer or a floating-point number. so: when an entry contains a string value (svalue is not NULL), then icached and fcached tell you whether or not equivalent integer and floating-point values are also cached in ivalue and fvalue.

⚠️ when you're creating a dictionary, initialize icached and fcached to zero. you don't have to do this explicitly if the dictionary is initialized statically the way it's 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, first entry to last, and return the first matching entry they bump into. first come, first served, periodt. ⭐

• 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 you're hunting for can be specified in any of several representations — whichever one you picked is indicated by repn. and 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 👑

these dictionaries are already included in the library. free real estate, bestie:

• 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> 🌟

---

and that's the whole page, bestie, you ate it 🍓 this one shipped as VistaIO Version 1.2.14, dated 24 April 1993, and it lives at VistaIOdictionary(3). go forth and look up some keywords. 💅✨🎀