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.

THIS = INTEGER (Given)

AXIS = INTEGER (Given)

STRING = CHARACTER $\ast$ ( $\ast$ ) (Given)

VALUE = DOUBLE PRECISION (Returned)

STATUS = INTEGER (Given and Returned)

Frame

SkyFrame

FrameSet

AST_UNFORMAT = INTEGER

• A function value of zero (and no coordinate value) will be returned, without error, if the string supplied does not contain a suitably formatted value.

• Beware that it is possible for a formatting error part-way through an input string to terminate input before it has been completely read, but to yield a coordinate value that appears valid. For example, if a user types " 1.5R6" instead of " 1.5E6" , the " R" will terminate input, giving an incorrect coordinate value of 1.5. It is therefore most important to check the return value of this function to ensure that the correct number of characters have been read.

• An error will result if a value is read which appears to have the correct format, but which cannot be converted into a valid coordinate value (for instance, because the value of one or more of its fields is invalid).

• The string "$<$bad$>$" is recognised as a special case and will yield the coordinate value AST__BAD without error. The test for this string is case-insensitive and also permits embedded white space.

• A function result of zero will be returned and no coordinate value will be returned via the VALUE argument if this function is invoked with the AST error status set, or if it should fail for any reason.

• An optional sign, followed by:

• A sequence of one or more digits possibly containing a decimal point, followed by:

• An optional exponent field.

• The exponent field, if present, consists of " E" or " e" followed by a possibly signed integer.

Examples of acceptable Frame input formats include:

• 99

• 1.25

• -1.6

• 1E8

• -.99e-17

• $<$bad$>$

• An optional sign, followed by between one and three fields representing either degrees, arc-minutes, arc-seconds or hours, minutes, seconds (e.g. " -12 42 03" ).

• Each field should consist of a sequence of one or more digits, which may include leading zeros. At most one field may contain a decimal point, in which case it is taken to be the final field (e.g. decimal degrees might be given as " 124.707" , while degrees and decimal arc-minutes might be given as " -13 33.8" ).

• The first field given may take any value, allowing angles and times outside the conventional ranges to be represented. However, subsequent fields must have values of less than 60 (e.g. " 720 45 31" is valid, whereas " 11 45 61" is not).

• Fields may be separated by white space or by " :" (colon), but the choice of separator must be used consistently throughout the value. Additional white space may be present around fields and separators (e.g. " - 2: 04 : 7.1" ).

• The following field identification characters may be used as separators to replace either of those above (or may be appended to the final field), in order to identify the field to which they are appended: " d" —degrees; " h" —hours; " m" —minutes of arc or time; " s" —seconds of arc or time; "’" (single quote)—minutes of arc; """ (double quote)—seconds of arc. Either lower or upper case may be used. Fields must be given in order of decreasing significance (e.g. " -11D 3’ 14.4"" or " 22h14m11.2s" ).

• The presence of any of the field identification characters " d" , "’" (single quote) or """ (double quote) indicates that the value is to be interpreted as an angle. Conversely, the presence of " h" indicates that it is to be interpreted as a time (with 24 hours corresponding to 360 degrees). Incompatible angle/time identification characters may not be mixed (e.g. " 10h14’ 3"" is not valid). The remaining field identification characters and separators do not specify a preference for an angle or a time and may be used with either.

• If no preference for an angle or a time is expressed anywhere within the value, it is interpreted as an angle if the Format attribute string associated with the SkyFrame axis generates an angle and as a time otherwise. This ensures that values produced by AST_FORMAT are correctly interpreted by AST_UNFORMAT.

• Fields may be omitted, in which case they default to zero. The remaining fields may be identified by using appropriate field identification characters (see above) and/or by adding extra colon separators (e.g. " -05m13s" is equivalent to " -:05:13" ). If a field is not identified explicitly, it is assumed that adjacent fields have been given, after taking account of any extra separator characters (e.g. " 14:25.4s" specifies minutes and seconds, while " 14::25.4s" specifies degrees and seconds).

• If fields are omitted in such a way that the remaining ones cannot be identified uniquely (e.g. " 01:02" ), then the first field (either given explicitly or implied by an extra leading colon separator) is taken to be the most significant field that AST_FORMAT would produce when formatting a value (using the Format attribute associated with the SkyFrame axis). By default, this means that the first field will normally be interpreted as degrees or hours. However, if this does not result in consistent field identification, then the last field (either given explicitly or implied by an extra trailing colon separator) is taken to to be the least significant field that AST_FORMAT would produce.

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:

• -14d 13m 22.2s (-14d 13’ 22.2" )

• $+$ 12:34:56.7 (12d 34’ 56.7" or 12h 34m 56.7s)

• 001 : 02 : 03.4 (1d 02’ 03.4" or 1h 02m 03.4s)

• 22h 30 (22h 30m 00s)

• 136::10" (136d 00’ 10" or 136h 00m 10s)

• -14M 27S (-0d 14’ 27" or -0h 14m 27s)

• -:14: (-0d 14’ 00" or -0h 14m 00s)

• -::4.1 (-0d 00’ 04.1" or -0h 00m 04.1s)

• .9" (0d 00’ 00.9" )

• d12m (0d 12’ 00" )

• H 12:22.3s (0h 12m 22.3s)

• $<$bad$>$ (AST__BAD)

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