#### Description:

This attribute specifies the format to be used when displaying coordinate values associated with a particular Frame axis (i.e. to convert values from binary to character form). It is interpreted by the astFormat function and determines the formatting which it applies.

If no Format value is set for a Frame axis, a default value is supplied instead. This is based on the value of the Digits, or Digits(axis), attribute and is chosen so that it displays the requested number of digits of precision.

Type:

  String.

#### Applicability

##### Frame

The Frame class interprets this attribute as a format specification string to be passed to the C `"` printf`"` function (e.g. `"` %1.7G`"` ) in order to format a single coordinate value (supplied as a double precision number).

When supplying a value for this attribute, beware that the `"` %`"` character may be interpreted directly as a format specification by some printf-like functions (such as astSet). You may need to double it (i.e. use `"` %%`"` ) to avoid this.

##### SkyFrame

The SkyFrame class re-defines the syntax and default value of the Format string to allow the formatting of sexagesimal values as appropriate for the particular celestial coordinate system being represented. The syntax of SkyFrame Format strings is described (below) in the `"` SkyFrame Formats`"` section.

##### FrameSet

The Format attribute of a FrameSet axis is the same as that of its current Frame (as specified by the Current attribute). Note that the syntax of the Format string is also determined by the current Frame.

##### TimeFrame

The TimeFrame class extends the syntax of the Format string to allow the formatting of TimeFrame axis values as Gregorian calendar dates and times. The syntax of TimeFrame Format strings is described (below) in the `"` TimeFrame Formats`"` section.

#### Notes:

- When specifying this attribute by name, it should be subscripted with the number of the Frame axis to which it applies.

#### SkyFrame Formats

The Format string supplied for a SkyFrame should contain zero or more of the following characters. These may occur in any order, but the following is recommended for clarity:

- `"` +`"` : Indicates that a plus sign should be prefixed to positive values. By default, no plus sign is used.

- `"` z`"` : Indicates that leading zeros should be prefixed to the value so that the first field is of constant width, as would be required in a fixed-width table (leading zeros are always prefixed to any fields that follow). By default, no leading zeros are added.

- `"` i`"` : Use the standard ISO field separator (a colon) between fields. This is the default behaviour.

- `"` b`"` : Use a blank to separate fields.

- `"` l`"` : Use a letter (`"` h`"` /`"` d`"` , `"` m`"` or `"` s`"` as appropriate) to separate fields.

- `"` g`"` : Use a letter and symbols to separate fields (`"` h`"` /`"` d`"` , `"` m`"` or `"` s`"` , etc, as appropriate), but include escape sequences in the formatted value so that the Plot class will draw the separators as small super-scripts. The default escape sequences are optimised for the pgplot graphics package, but new escape sequences may be specified using function astSetSkyDelim.

- `"` d`"` : Include a degrees field. Expressing the angle purely in degrees is also the default if none of `"` h`"` , `"` m`"` , `"` s`"` or `"` t`"` are given.

- `"` h`"` : Express the angle as a time and include an hours field (where 24 hours correspond to 360 degrees). Expressing the angle purely in hours is also the default if `"` t`"` is given without either `"` m`"` or `"` s`"` .

- `"` m`"` : Include a minutes field. By default this is not included.

- `"` s`"` : Include a seconds field. By default this is not included. This request is ignored if `"` d`"` or `"` h`"` is given, unless a minutes field is also included.

- `"` t`"` : Express the angle as a time (where 24 hours correspond to 360 degrees). This option is ignored if either `"` d`"` or `"` h`"` is given and is intended for use where the value is to be expressed purely in minutes and/or seconds of time (with no hours field). If `"` t`"` is given without `"` d`"` , `"` h`"` , `"` m`"` or `"` s`"` being present, then it is equivalent to `"` h`"` .

- `"` .`"` : Indicates that decimal places are to be given for the final field in the formatted string (whichever field this is). The `"` .`"` should be followed immediately by an unsigned integer which gives the number of decimal places required, or by an asterisk. If an asterisk is supplied, a default number of decimal places is used which is based on the value of the Digits attribute.

All of the above format specifiers are case-insensitive. If several characters make conflicting requests (e.g. if both `"` i`"` and `"` b`"` appear), then the character occurring last takes precedence, except that `"` d`"` and `"` h`"` always override `"` t`"` .

If the format string starts with a percentage sign (%), then the whole format string is assumed to conform to the syntax defined by the Frame class, and the axis values is formated as a decimal radians value.

#### TimeFrame Formats

The Format string supplied for a TimeFrame should either use the syntax defined by the base Frame class (i.e. a C `"` printf`"` format string), or the extended `"` iso`"` syntax described below (the default value is inherited from the Frame class):

- C `"` printf`"` syntax: If the Format string is a C `"` printf`"` format description such as `"` %1.7G`"` , the TimeFrame axis value will be formatted without change as a floating point value using this format. The formatted string will thus represent an offset from the zero point specified by the TimeFrame`’` s TimeOrigin attribute, measured in units given by the TimeFrame`’` s Unit attribute.

- `"` iso`"` syntax: This is used to format a TimeFrame axis value as a Gregorian date followed by an optional time of day. If the Format value commences with the string `"` iso`"` then the TimeFrame axis value will be converted to an absolute MJD, including the addition of the current TimeOrigin value, and then formatted as a Gregorian date using the format `"` yyyy-mm-dd`"` . Optionally, the Format value may include an integer precision following the `"` iso`"` specification (e.g. `"` iso.2`"` ), in which case the time of day will be appended to the formatted date (if no time of day is included, the date field is rounded to the nearest day). The integer value in the Format string indicates the number of decimal places to use in the seconds field. For instance, a Format value of `"` iso.0`"` produces a time of day of the form `"` hh:mm:ss`"` , and a Format value of `"` iso.2`"` produces a time of day of the form `"` hh:mm:ss.ss`"` . The date and time fields will be separated by a space unless `’` T`’` is appended to the end of string, in which case the letter T (upper case) will be used as the separator. The value of the Digits attribute is ignored when using this `"` iso`"` format.

Copyright (C) 2021 East Asian Observatory