AST_UNFORMAT

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 precision) 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 AST_FORMAT.

Invocation

RESULT = AST_UNFORMAT( THIS, AXIS, STRING, VALUE, STATUS )

Arguments

THIS = INTEGER (Given)
Pointer to the Frame.
AXIS = INTEGER (Given)
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 = CHARACTER ( ) (Given)
A 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 = DOUBLE PRECISION (Returned)
The coordinate value read.
STATUS = INTEGER (Given and Returned)
The global status.

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

AST_UNFORMAT = INTEGER
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 AST_FORMAT which contain less than three fields will be correctly interpreted if read back using AST_UNFORMAT, 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.