astUnformat

Read a formatted coordinate value for a Frame axis

Description:

This function reads a formatted coordinate value (given as a character string) for a Frame axis and returns the equivalent numerical (double) value. It also returns the number of characters read from the string.

The principle use of this function is in decoding user-supplied input which contains formatted coordinate values. Free-format input is supported as far as possible. If input is ambiguous, it is interpreted with reference to the Frame s attributes (in particular, the Format string associated with the Frame s axis). This function is, in essence, the inverse of astFormat.

Synopsis

int astUnformat( AstFrame this, int axis, const char string, double value )

Parameters:

this
Pointer to the Frame.
axis
The number of the Frame axis for which a coordinate value is to be read (axis numbering starts at 1 for the first axis).
string
Pointer to a null-terminated character string containing the formatted coordinate value. This string may contain additional information following the value to be read, in which case reading stops at the first character which cannot be interpreted as part of the value. Any white space before or after the value is discarded.
value
Pointer to a double in which the coordinate value read will be returned.

Applicability

Frame
This function applies to all Frames. See the " Frame Input Format" section below for details of the input formats accepted by a basic Frame.
SkyFrame
The SkyFrame class re-defines the input format to be suitable for representing angles and times, with the resulting coordinate value returned in radians. See the " SkyFrame Input Format" section below for details of the formats accepted.
FrameSet
The input formats accepted by a FrameSet are determined by its current Frame (as specified by the Current attribute).

Returned Value

astUnformat()
The number of characters read from the string in order to obtain the coordinate value. This will include any white space which occurs before or after the value.

Notes:

Frame Input Format

The input format accepted for a basic Frame axis is as follows:

Examples of acceptable Frame input formats include:

SkyFrame Input Format

The input format accepted for a SkyFrame axis is as follows:

This final convention is intended to ensure that values formatted by astFormat which contain less than three fields will be correctly interpreted if read back using astUnformat, even if they do not contain field identification characters.

Examples of acceptable SkyFrame input formats (with interpretation in parentheses) include:

Where alternative interpretations are shown, the choice of angle or time depends on the associated Format(axis) attribute.