astMapGet1 <X >

Get a vector value from a KeyMap

Description:

This is a set of functions for retrieving a vector value from a KeyMap. You should replace <X > in the generic function name astMapGet1 <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 astMapGet1C function has an extra parameter " l" which specifies the maximum length of each string to be stored in the " value" buffer (see the " astMapGet1C" section below).

Synopsis

int astMapGet1 <X >( AstKeyMap this, const char key, int mxval, int nval, <X >type value ) int astMapGet1C( AstKeyMap this, const char key, int l, int mxval, int nval, const 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 KeyCase attribute is currently set to zero.
mxval
The number of elements in the " value" array.
nval
The address of an integer in which to put the number of elements stored in the " value" array. Any unused elements of the array are left unchanged.
value
A pointer to an array in which to return the requested values. If the requested key is not found, or if it is found but has an undefined value (see astMapPutU), then the contents of the buffer on entry to this function will be unchanged on exit.

Returned Value

astMapGet1 <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:

astMapGet1C

The " value" buffer supplied to the astMapGet1C function should be a pointer to a character array with " mxvall" elements, where " l" is the maximum length of a string to be returned. The value of " l" should be supplied as an extra parameter following " key" when invoking astMapGet1C, 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 astMapGet1 <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:

For example, astMapGet1D would be used to get " double" values, while astMapGet1I would be used to get " int" values, etc. For D or I, the supplied " value" parameter should be a pointer to an array of doubles or ints, with " mxval" elements. For C, the supplied " value" parameter should be a pointer to a character string with " mxvall" elements. For A, the supplied " value" parameter should be a pointer to an array of AstObject pointers.