Read a formatted coordinate value for a Frame axis astUnformat
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.
"
Frame Input Format"
section below for details of the input formats
accepted by a basic Frame. "
SkyFrame Input Format"
section
below for details of the formats accepted. 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"
pointer 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 astFormat are correctly interpreted by astUnformat.
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
astFormat 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 astFormat
would produce.
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:
-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.