astKeyMapastKeyMap - Create a KeyMap

Description:
This function creates a new empty KeyMapKeyMap and optionally initialises its attributes. Entries can then be added to the KeyMap using the astMapPut0$<$X$>$astMapPut0X and astMapPut1$<$X$>$astMapPut1X functions.

The KeyMap class is used to store a set of values with associated keys which identify the values. The keys are strings. These may be case sensitive or insensitive as selected by the KeyCaseKeyCase attribute, and trailing spaces are ignored. The value associated with a key can be integer (signed 4 and 2 byte, or unsigned 1 byte), floating point (single or double precision), void pointer, character string or AST ObjectObject pointer. Each value can be a scalar or a one-dimensional vector. A KeyMap is conceptually similar to a MappingMapping in that a KeyMap transforms an input into an output - the input is the key, and the output is the value associated with the key. However, this is only a conceptual similarity, and it should be noted that the KeyMap class inherits from the Object class rather than the Mapping class. The methods of the Mapping class cannot be used with a KeyMap.

Synopsis:
AstKeyMap $*$astKeyMap( const char $*$options, ... )
Parameters:
options
Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new KeyMap. The syntax used is identical to that for the astSetastSet function and may include "printf" format specifiers identified by "%" symbols in the normal way.
...
If the "options" string contains "%" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C "printf" function).
Returned Value:
astKeyMap()
A pointer to the new KeyMap.
Notes:
  • A null Object pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason.
Status Handling
The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: "int $*$status".