.ds Vv 1.2.14
.TH VistaIOdictionary 3 "24 April 1993" "VistaIO Version \*(Vv"
.SH NAME
VistaIOdictionary \- representation of a keyword/value mapping
.SH SYNPOSIS
.nf
.ft B
VistaIODictEntry \fIdictionary\fP[] = {
.RS
{ "\fIkeyword\fP", \fIinteger_value\fP },
{ "\fIkeyword\fP", 0, \fIstring_value\fP },
\fR...\fP
{ NULL }
.RE
};
.fi
.SH DESCRIPTION
This manual page documents a data structure, called a \fIdictionary\fP, 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.
.SS "Data Structure"
.nf
.ft B
.ta 25n
typedef struct {
.RS
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 */
.RE
} VistaIODictEntry;
.DT
.fi
.PP
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.
.PP
A dictionary is an array of \fBVistaIODictEntry\fP structures. The last entry in 
the array has a \fIkeyword\fP field of 
.SB 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 \fIivalue\fP field (in which case \fIsvalue\fP must be 
.SB NULL\c
) or as a string pointed to by the \fIsvalue\fP field (in which case the 
\fIivalue\fP 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.
.PP
Other fields of the \fBVistaIODictEntry\fP are only used internally by the 
\fBVistaIOLookupDictValue\fP 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 (\fIsvalue\fP is not
.SB NULL\c
) then \fIicached\fP and \fIfcached\fP indicate whether or not equivalent
integer and floating-point values are also cached in \fIivalue\fP and
\fIfvalue\fP. When creating a dictionary, initialize \fIicached\fP and
\fIfcached\fP to zero; this need not be done explicitly if the dictionary
is initialized statically as shown under ``EXAMPLES''.
.SS 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.
.HP 10n
.na
.nh
.B VistaIODictEntry *VistaIOLookupDictKeyword (VistaIODictEntry *\fIdict\fP, 
.B VistaIOStringConst\ \fIkeyword\fP)
.ad
.hy
.IP "" 0.5i
\fBVistaIOLookupDictEntry\fP searches the dictionary \fIdict\fP for an entry
whose keyword is \fIkeyword\fP. It returns a pointer to the entry, if
found, or
.SB NULL
otherwise.
.PP
.HP 10n
.na
.nh
.B VistaIODictEntry *VistaIOLookupDictValue (VistaIODictEntry *\fIdict\fP, 
.B VistaIORepnKind\ \fIrepn\fP, \fItype\ value\fP)
.ad
.hy
.IP "" 0.5i
\fBVistaIOLookupDictValue\fP searches the dictionary \fIdict\fP for an entry
whose value is \fIvalue\fP. The value to be searched for can be specified
in any of several representations; that chosen is indicated by \fIrepn\fP.
Then \fItype\fP is one of \fBVistaIOBit\fP, \fBVistaIOUByte\fP, \fBVistaIOSByte\fP,
\fBVistaIOShort\fP, \fBVistaIOLong\fP, \fBVistaIOFloat\fP, \fBVistaIODouble\fP, \fBVistaIOBoolean\fP, or
\fBVistaIOString\fP, depending on \fIrepn\fP.  \fBVistaIOLookupDictValue\fB returns a
pointer to the entry, if found, or
.SB NULL
otherwise.
.SS "Built-in Dictionaries"
The following dictionaries are already included in the library:
.IP \fBVistaIOBooleanDict\fP 15n
maps between the keywords \fBfalse\fP, \fBtrue\fP, \fBno\fP, \fByes\fP,
\fBoff\fP, and \fBon\fP and the values
.SB FALSE
and
.SB TRUE\c
.
.IP \fBVistaIONumericRepnDict\fP
maps between the keywords \fBbit\fP, \fBubyte\fP, \fBsbyte\fP, \fBshort\fP,
\fBlong\fP, \fBfloat\fB, and \fBdouble\fP and the values \fBVistaIOBitRepn\fP through \fBVistaIODoubleRepn\fP.
.SH EXAMPLES
This dictionary describes a mapping between keywords and integers:
.PP
.nf
.ft B
.RS
VistaIODictEntry VistaIOBooleanDict[] = {
.RS
{ "false", FALSE }, { "true", TRUE },
{ "no", FALSE }, { "yes", TRUE },
{ "off", FALSE }, { "on", TRUE },
{ NULL }
.RE	
};
.RE
.fi
.PP
This dictionary describes a mapping between keywords and floating point
numbers:
.PP
.nf
.ft B
.RS
VistaIODictEntry ConstantDict[] = {
.RS
{ "zero", 0 }, { "one", 1 },
{ "pi", 0, "3.14159" }, { "e", 0, "2.7182818" },
{ NULL }
.RE
};
.RE
.fi
.PP
This dictionary describes a mapping between keywords and strings:
.PP
.nf
.ft B
.RS
VistaIODictEntry TitleDict[] = {
.RS
{ "Clinton", 0, "President of the U.S.A." },
{ "Major", 0, "Prime Minister of Great Britain" },
{ "Mulroney", 0, "Prime Minister of Canada" }, 
{ NULL }
.RE
};
.RE
.fi
.SH AUTHOR
Art Pope <pope@cs.ubc.ca>

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