Procedure

     DPFMT ( Format a double precision number )

     SUBROUTINE DPFMT ( X, PICTUR, STR )

Abstract

     Create a formatted string that represents a double precision
     number, using a format picture.

Required_Reading

     None.

Keywords

     ALPHANUMERIC
     CONVERSION
     UTILITY

Declarations

     IMPLICIT NONE

     DOUBLE PRECISION      X
     CHARACTER*(*)         PICTUR
     CHARACTER*(*)         STR

Brief_I/O

     VARIABLE  I/O  DESCRIPTION
     --------  ---  --------------------------------------------------
     X          I   a double precision number.
     PICTUR     I   a string describing the appearance of the output
     STR        O   a string representing X as prescribed by PICTUR

Detailed_Input

     X        is any double precision number.

     PICTUR   is a string used to describe the format of the
              output string. There are four special characters
              recognized by DPFMT --- a leading + or -, a leading
              zero ( '0' ) or a zero that follows a leading + or -,
              and the first decimal point of the string.

              All other non-blank characters are regarded as
              equivalent. The picture ends at the first blank
              character. The effects associated with the various
              characters in a picture are spelled out in the
              description of the output STRING.

              The following pictures are treated as errors.

              ' ', '+', '-', '.', '+.', '-.'

Detailed_Output

     STRING   is a string representing X that matches the input
              picture. The format of STRING is governed by PICTUR.
              It will represent X rounded to the level of precision
              specified by PICTUR.

              If the first character of the picture is a minus sign,
              the first character in the output string will be
              a blank if the number is non-negative, a minus sign
              if the number is negative.

              If the first character of the picture is a plus sign,
              the first character of the output string will be a
              plus if the number is positive, a blank if the number
              is zero, and a minus sign if the number is negative.

              If the first character of the string is NOT a sign
              (plus or minus) the first character of the output
              string will be a minus sign if the number is negative
              and will be the first character of the integer part
              of the number otherwise.

              The integer portion of STRING will contain the same
              number of characters as appear before the decimal
              point (or last character if there is no decimal
              point) but after a leading + or -.

              If the picture begins with any of the following

                 '+0', '-0', or '0'

              it is said to have a leading zero. If a picture has
              a leading zero and the integer portion is not large
              enough to fill up the integer space specified by
              PICTUR, STRING will be zero padded from the sign (if
              one is required) up to the first character of the
              integer part of the number.

              If picture does NOT have a leading zero and the
              integer portion is not large enough to fill up the
              space specified by PICTUR, STRING will be blank
              padded on the left between the sign (if one is
              required) and the first character of the integer part
              of the number.

              If a decimal point ( '.' ) is present in PICTUR it
              will be present following the integer portion of
              STRING. Moreover, the decimal portion of STRING will
              contain the same number of digits as there are
              non-blank characters following the decimal point in
              PICTUR. However, only the first 14 digits starting
              with the first non-zero digit are meaningful.

              If the format specified by PICTUR does not provide
              enough room for the integer portion of X, the routine
              determines whether or not the number of characters
              present in the picture is sufficient to create a
              representation for X using scientific notation. If
              so, the output is displayed using scientific notation
              (leading signs, if they are present in PICTUR, will
              also appear in STRING).   If the format specified by
              PICTUR is too short to accommodate scientific
              notation, the output string is filled with '*' to the
              same length as the length of PICTUR. Leading signs
              are not preserved in this overflow case.

              STRING may overwrite PICTUR.

Parameters

     None.

Exceptions

     1)  If PICTUR begins with a blank, the error SPICE(NOPICTURE) is
         signaled.

     2)  If PICTUR consists only of '+', '-', '.', '+.' or '-.' are
         regarded as invalid (there's no significant component to the
         picture.) therefore, the error SPICE(BADPICTURE) is signaled.

     3)  If the length of STR is less than the length of the first
         non-blank portion of PICTUR, the error SPICE(OUTPUTTOOSHORT)
         is signaled.

Files

     None.

Particulars

     This routine provides a mechanism for producing numeric strings
     formatted according to a user supplied picture. We expect that
     the string produced by this routine will be used to assist in
     the construction of a string that can be read by people.

     Note that the process of converting a double precision number
     to a string, in not precisely invertible even if the string
     contains all of the significant figures allowed by this
     routine. You should not anticipate that the string produced
     by this routine can be "read" into a double precision number
     to reproduce the double precision number X. To the level of
     accuracy implied by the string representation, they will be
     the same. But, they are unlikely to have the same internal
     binary representation.

Examples

     Suppose that X has the binary representation of PI. Then the
     table below illustrates the strings that would be produced
     by a variety of different pictures.

     PICTUR         |    STRING
     -------------------------------
     '0x.xxx'       |  '03.142'
     'xx.xxx'       |  ' 3.142'
     '+xxx.yyyy'    |  '+  3.1416'
     '-.yyyy'       |  '******'
     'xxxxxxxx'     |  '       3'
     '00xx'         |  '0003'
     '-00.0000000'  |  ' 03.1415927'
     '00'           |  '03'
     'x.'           |  '3.'
     '.mynumber'    |  '3.142E+00'
     'my dog spot'  |  ' 3'
     'my.dog spot'  |  ' 3.142'
     '+my.dog,spot' |  '+ 3.14159265'



     Suppose that X has the binary representation of 2/3. Then the
     table below illustrates the strings that would be produced
     by a variety of different pictures.

     PICTUR         |    STRING
     -------------------------------
     '+x.xxx'       |  '+0.667'
     '+xx.xxx'      |  '+ 0.667'
     'xxx.yyyy'     |  '  0.6667'
     '.yyyy'        |  '.6667'
     'xxxxxxxx'     |  '       1'
     '00xx'         |  '0001'
     '-0.0000000'   |  ' 0.6666667'
     '00'           |  '01'
     'x.'           |  '1.'
     'mynumber'     |  '       1'
     'my dog spot'  |  ' 1'
     'my.dog spot'  |  ' 0.667'
     'my.dog,spot'  |  ' 0.66666667'

     Suppose that X has the binary representation of -8/9. Then the
     table below illustrates the strings that would be produced
     by a variety of different pictures.


     PICTUR         |    STRING
     -------------------------------
     '+x.xxx'       |  '-0.889'
     '-00.xxxx'     |  '-00.8889'
     'xxx.xxx'      |  ' -0.889'
     '000.000'      |  '-00.889'

Restrictions

     None.

Literature_References

     None.

Author_and_Institution

     N.J. Bachman       (JPL)
     J. Diaz del Rio    (ODC Space)
     B.V. Semenov       (JPL)
     W.L. Taber         (JPL)
     E.D. Wright        (JPL)

Version

    SPICELIB Version 1.0.3, 27-OCT-2021 (JDR) (EDW) (NJB)

        Edited the header to comply with NAIF standard.

    SPICELIB Version 1.0.2, 31-JAN-2008 (BVS)

        Removed non-standard end-of-declarations marker
        'C%&END_DECLARATIONS' from comments.

    SPICELIB Version 1.0.1, 22-JUN-1998 (WLT)

        A number of typographical and grammatical errors
        were corrected in the header.

    SPICELIB Version 1.0.0, 17-SEP-1996 (WLT)