astMapGet0
X
astMapGet0X
-
Get a scalar value from a KeyMap
- Description:
- This is a set of functions for retrieving a scalar value from a KeyMapKeyMap.
You should replace
X
in the generic function name
astMapGet0
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).
- Synopsis:
- int astMapGet0
X
( AstKeyMap
this, const char
key,
X
type
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.
-
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.
For pointer types ("A" and "C"), the buffer should be a suitable
pointer, and the address of this pointer should be supplied as the
"value" parameter.
- Returned Value:
-
astMapGet0
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 buffer
will be returned unchanged.
- If the stored value is a vector value, then the first value in
the vector will be returned.
- A string pointer returned by astMapGet0C is guaranteed to remain valid
and the string to which it points will not be over-written for a
total of 50 successive invocations of this function. After this,
the memory containing the string may be re-used, so a copy of
the string should be made if it is needed for longer than this.
- If the returned value is an AST ObjectObject pointer, the Object's reference
count is incremented by this call. Any subsequent changes made to
the Object using the returned pointer will be reflected in any
any other active pointers for the Object. The returned pointer
should be annulled using
astAnnulastAnnul
when it is no longer needed.
-
Data Type Codes
- To select the appropriate
function, you should replace
X
in the generic function name astMapGet0
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:
- F: float
- D: double
- 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. word)
For example, astMapGet0D would be used to get a "double" value,
while astMapGet0I would be used to get an "int", etc.