Next: astMapGetElemX - Get a single element of a vector value from a KeyMap
Up: AST Function Descriptions
Previous: astMapGet0X - Get a scalar value from a KeyMap
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:
- No error is reported if the requested key cannot be found in the
given KeyMap, but a
zero
value will be returned as the function value. The supplied array
will be returned unchanged.
- If the stored value is a scalar value, then the value will be
returned in the first element of the supplied array, and
"nval"
will be returned set to 1.
-
astMapGet1C
- The "value" buffer supplied to the astMapGet1C function should be a
pointer to a character array with "mxval
l" 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:
- 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, 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 "mxval
l" elements.
For A, the supplied "value" parameter should be a pointer to an
array of AstObject pointers.
Next: astMapGetElemX - Get a single element of a vector value from a KeyMap
Up: AST Function Descriptions
Previous: astMapGet0X - Get a scalar value from a KeyMap
AST A Library for Handling World Coordinate Systems in Astronomy
Starlink User Note 211
R.F. Warren-Smith & D.S. Berry
24th May 2011
E-mail:ussc@star.rl.ac.uk
Copyright (C) 2009 Science \& Technology Facilities Council