next up previous 264
Next: astMapPut1X - Add a vector value to a KeyMap
Up: AST Function Descriptions
Previous: astMapLength - Get the vector length of an entry in a KeyMap


astMapPut0$<$X$>$ - Add a scalar value to a KeyMap

Description:
This is a set of functions for adding scalar values to a KeyMap. You should use a function which matches the data type of the data you wish to add to the KeyMap by replacing $<$X$>$ in the generic function name astMapPut0$<$X$>$ by an appropriate 1-character type code (see the "Data Type Codes" section below for the code appropriate to each supported data type).
Synopsis:
void astMapPut0$<$X$>$( AstKeyMap $*$this, const char $*$key, $<$X$>$type value, const char $*$comment );
Parameters:
this
Pointer to the KeyMap in which to store the supplied value.
key
A character string to be stored with the value, which can later be used to identify the value. Trailing spaces are ignored. The supplied string is converted to upper case before use if the KeyCase attribute is currently set to zero.
value
The value to be stored. The data type of this value should match the 1-character type code appended to the function name (e.g. if you are using astMapPut0A, the type of this value should be "pointer to AstObject").
comment
A pointer to a null-terminated comment string to be stored with the value. A NULL pointer may be supplied, in which case no comment is stored.
Notes:
  • If the supplied key is already in use in the KeyMap, the new value will replace the old value.

  • If the stored value is an AST Object 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, including any obtained later using astMapget0A. The reference count for the Object will be decremented when the KeyMap is destroyed, or the entry is removed or over-written with a different pointer.
Data Type Codes
To select the appropriate function, you should replace $<$X$>$ in the generic function name astMapPut0$<$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. unsigned char)

For example, astMapPut0D would be used to store a "double" value, while astMapPut0I would be used to store an "int", etc.

Note that KeyMaps containing generic "void $*$" pointers cannot be written out using astShow or astWrite. An error will be reported if this is attempted.



next up previous 264
Next: astMapPut1X - Add a vector value to a KeyMap
Up: AST Function Descriptions
Previous: astMapLength - Get the vector length of an entry in a KeyMap

AST A Library for Handling World Coordinate Systems in Astronomy
Starlink User Note 211
R.F. Warren-Smith & D.S. Berry
25th February 2013
E-mail:starlink@jiscmail.ac.uk

Copyright (C) 2014 Science \& Technology Facilities Council