next up previous 264
Next: astUnitMap - Create a UnitMap
Up: AST Function Descriptions
Previous: astUkern1 - 1-dimensional sub-pixel interpolation kernel


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.
Class 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:
  • 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.
Frame Input Format
The input format accepted for a basic Frame axis is as follows:
  • 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$>$
SkyFrame Input Format
The input format accepted for a SkyFrame axis is as follows:
  • 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.


next up previous 264
Next: astUnitMap - Create a UnitMap
Up: AST Function Descriptions
Previous: astUkern1 - 1-dimensional sub-pixel interpolation kernel

AST A Library for Handling World Coordinate Systems in Astronomy
Starlink User Note 211
R.F. Warren-Smith & D.S. Berry
25th February 2013
E-mail:starlink@jiscmail.ac.uk

Copyright (C) 2014 Science \& Technology Facilities Council