#### Description:

This function gets a named value from a KeyMap as a single string. For scalar values it is equivalent to astMapGet0C. If the value is a vector, the returned string is a comma-separated list of the vector elements, enclosed in parentheses.

#### Synopsis

int astMapGetC( AstKeyMap ∗this, const char ∗key, 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.

##### value

Address at which to return a pointer to the required string value. If the requested key is not found, or if it is found but has an undefined value (see astMapPutU), then the contents of the supplied pointer are unchanged on exit.

#### Returned Value

##### astMapGetC()

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.

- The string pointer returned by astMapGetC 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. The calling code should never attempt to free the returned pointer (for instance, using astFree).

Copyright (C) 2021 East Asian Observatory