##
Reading Formatted Celestial Coordinates

The process of converting formatted celestial coordinates, such as might be produced by the astFormatastFormat function (§8.6), into numerical (double) coordinate values is performed by using astUnformatastUnformat (§7.8) and passing it a pointer to a SkyFrameSkyFrame. The use of a SkyFrame means that the range of input formats accepted is appropriate to positions on the sky expressed as angles and/or times, while the returned value is in radians.

The following describes the forms of celestial coordinate which are supported:

- You may supply an optional sign, followed by between one and three fields representing either degrees, arc-minutes, arc-seconds or hours, minutes, seconds (e.g. “87#8712 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 “87#8713 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. “87#87 2: 04 : 7.1”).

- The following field identification characters may be used as separators to replace 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)
  > ' | – | arc-minutes
  > " | – | arc-seconds

  Either lower or upper case may be used. Fields must be given in order of decreasing significance (e.g. “87#8711D 3' 14.4"” or “22h14m11.2s”).

- The presence of certain field identification characters indicates whether the value is to be interpreted as an angle or a time (with 24 hours corresponding to 360 degrees), as follows:

  > d | – | angle
  > ' | – | angle
  > " | – | angle
  > h | – | time

  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, then 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 (§8.6) 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. “87#8705m13s” is equivalent to “87#87: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. For example:

  > 10d | – | degrees
  > 10d12 | – | degrees and arc-minutes
  > 11:14" | – | arc-minutes and arc-seconds
  > 9h13s | – | hours and seconds of time
  > :45:33 | – | minutes and seconds (of arc or time)
  > :55: | – | minutes (of arc or time)
  > ::13 | – | seconds (of arc or time)
  > 87#876::2.5 | – | degrees/hours and seconds (of arc or time)
  > 07m14 | – | minutes and seconds (of arc or time)
  > 87#878:14' | – | degrees and arc-minutes
  > 87#87h3:14 | – | minutes and seconds of time
  > h:2.1 | – | seconds of time

- 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. However, it also affects other forms of input. For example, if the Format(axis)Format(axis) string were set to “mst.1” (producing two fields representing minutes and seconds of time), then formatted input would be interpreted by astUnformat as follows:

> 12 13 | – | minutes and seconds
> 12 | – | minutes
> :13 | – | seconds
> 87#8718: | – | minutes
> 12.8 | – | minutes
> 1 2 3 | – | hours, minutes and seconds
> 4' | – | arc-minutes
> 60::" | – | degrees
> 87#8723:" | – | arc-minutes
> 87#8733h | – | hours

(in the last four cases, explicit field identification has been given which overrides the implicit identification).

Alternatively, if the Format(axis) string were set to “s.3” (producing only an arc-seconds field), then formatted input would be interpreted by astUnformat as follows:

> 12.8 | – | arc-seconds
> 12 13 | – | arc-minutes and arc-seconds
> :12 | – | arc-seconds
> 13: | – | arc-minutes
> 1 2 3 | – | degrees, arc-minutes and arc-seconds

In general, if you are preparing formatted input data containing celestial coordinates and wish to omit certain fields, then you are advised to identify clearly those that you do provide by using the appropriate field identification characters and/or extra colon separators. This prevents you depending on the implicit field identification described above which, in turn, depends on an appropriate Format(axis) string having been set.

When writing software, it is also a good idea to set the Format(axis) string so that data input will be as simple as possible for the user. Unless some special effect is desired, this normally means that it should contain “d” or “h” to ensure that the first field entered by the user will be interpreted as degrees or hours, unless otherwise identified. This is the normal behaviour unless an explicit Format(axis) value has been set to override the default.