Return the combination of a double value and its printing format.

Arguments:

DoubleFormat format

The printing format to use when printing the double value.

Double value

The value to be printed with the specified format.

Return value:

The combination of the specified format and floating point value, ready to be passed as an argument of the print command.

Example:

The following example displays the current local sidereal time, first in decimal hours, then in sexagesimal hours, minutes and seconds. Since the $time() function returns a Double value, containing the number of hours into the sidereal day, the first example, that doesn't specify a printing format, prints the decimal number of hours to the full precision of the returned floating point number. To make this more humanly readable, the second print statement uses the $format_double() function to tell the print statement to display the returned number of hours in sexagesimal hours, minutes and seconds.

 tcs> print "The local sidereal time is: ", $time(lst), " hours."
 The local sidereal time is 0.909007023428316 hours.
 tcs> print "The local sidereal time is: ", $format_double("08s", $time(lst))
 The local sidereal time is 00:54:32.

The "08s" sexagesimal format specifier, tells the print command to pad the left side of the hours field with zeroes to make the complete number take up the specified minimum field width of 8 characters. Without this, the hour field in the example would have been displayed as a single zero, like 0:54:32.

Formats

Please see the documentation of the DoubleFormat datatype for the legal formatting options.

Context

By default the print and log commands print Double values as floating point numbers with full machine precision (usually 15 digits). In most cases much fewer digits are actually needed, and in others sexagesimal notation is more useful. The $format_double() function was thus written to allow the user to specify how each floating point value is displayed. In general this function is only useful as the argument of the print and log commands, although its return value can be stored in a variable for printing at another time.