astMapGetElem$<$X$>$astMapGetElemX - Get a single element of a vector value from a KeyMap

Description:
This is a set of functions for retrieving a single element of a vector value from a KeyMapKeyMap. You should replace $<$X$>$ in the generic function name astMapGetElem$<$X$>$ by an appropriate 1-character type code (see the "Data Type Codes" section below for the code appropriate to each supported data type). The stored value is converted to the data type indiced by $<$X$>$ before being returned (an error is reported if it is not possible to convert the stored value to the requested data type). Note, the astMapGetElemC function has an extra parameter "l" which specifies the maximum length of the string to be stored in the "value" buffer (see the "astMapGetElemC" section below).
Synopsis:
int astMapGetElem$<$X$>$( AstKeyMap $*$this, const char $*$key, int elem, $<$X$>$type $*$value ) int astMapGetElemC( AstKeyMap $*$this, const char $*$key, int l, int elem, char $*$value )
Parameters:
this
Pointer to the KeyMap.
key
The character string identifying the value to be retrieved. Trailing spaces are ignored. The supplied string is converted to upper case before use if the KeyCaseKeyCase attribute is currently set to zero.
elem
The index of the required vector element, starting at zero. An error will be reported if the value is outside the range of the vector.
value
A pointer to a buffer in which to return the requested value. If the requested key is not found, or if it is found but has an undefined value (see astMapPutUastMapPutU), then the contents of the buffer on entry to this function will be unchanged on exit.
Returned Value:
astMapGetElem$<$X$>$()
A non-zero value is returned if the requested key name was found, and does not have an undefined value (see astMapPutU). Zero is returned otherwise.
Notes:
  • No error is reported if the requested key cannot be found in the given KeyMap, or if it has an undefined value, but a zero value will be returned as the function value.
astMapGetElemC
The "value" buffer supplied to the astMapGetElemC function should be a pointer to a character array with "l" elements, where "l" is the maximum length of the string to be returned. The value of "l" should be supplied as an extra parameter following "key" when invoking astMapGetElemC, and should include space for a terminating null character.
Data Type Codes
To select the appropriate function, you should replace $<$X$>$ in the generic function name astMapGetElem$<$X$>$ with a 1-character data type code, so as to match the data type $<$X$>$type of the data you are processing, as follows:
  • D: double

  • F: float

  • I: int

  • C: "const" pointer to null terminated character string

  • A: Pointer to AstObject

  • P: Generic "void $*$" pointer

  • S: short int

  • B: Unsigned byte (i.e. char)

For example, astMapGetElemD would be used to get a "double" value, while astMapGetElemI would be used to get an "int" value, etc. For D or I, the supplied "value" parameter should be a pointer to a double or int. For C, the supplied "value" parameter should be a pointer to a character string with "l" elements. For A, the supplied "value" parameter should be a pointer to an AstObject pointer.