Index of Functions: A  B  C  D  E  F  G  H  I  J  K  L  M  N  O  P  Q  R  S  T  U  V  W  X 
Index Page
cspice_dp2hx

Table of contents
Abstract
I/O
Parameters
Examples
Particulars
Exceptions
Files
Restrictions
Required_Reading
Literature_References
Author_and_Institution
Version
Index_Entries


Abstract


   CSPICE_DP2HX converts a double precision number to an equivalent
   character string using a base 16 "scientific notation."

I/O


   Given:

      number   the scalar double precision number to convert to a character
               string representation.

               help, number
                  DOUBLE = Scalar

   the call:

      cspice_dp2hx, number, hxstr

   returns:

      hxstr    scalar string produced by this routine that represents
               `number' in a base 16 "scientific notation," e.g.:

                  672.0 = '2A^3' = ( 2/16 + 10/( 16^2 ) ) * 16^3

               and

                  -11.0 = '-B^1' = - ( 11/16 ) * 16^1.

               help, hxstr
                  STRING = Scalar

               The following table describes the character set used to
               represent the hexadecimal digits and their corresponding
               values.

                  Character    Value         Character    Value
                  ---------    ------        ---------    ------
                    '0'         0.0D0          '8'         8.0D0
                    '1'         1.0D0          '9'         9.0D0
                    '2'         2.0D0          'A'        10.0D0
                    '3'         3.0D0          'B'        11.0D0
                    '4'         4.0D0          'C'        12.0D0
                    '5'         5.0D0          'D'        13.0D0
                    '6'         6.0D0          'E'        14.0D0
                    '7'         7.0D0          'F'        15.0D0

               The caret, or hat, character, '^', is used to
               distinguish the exponent.

               The plus sign, '+', and the minus sign, '-', are used,
               and they have their usual meanings.

               In order to obtain the entire character string produced
               by this routine, the output character string should be
               at least `n' characters long, where


                           # of bits per double precision mantissa + 3
                  n = 3 + ---------------------------------------------
                                                4

                           # of bits per double precision exponent + 3
                        + ---------------------------------------------
                                                4

               There should be one character position for the sign of
               the mantissa, one for the sign of the exponent, one for
               the exponentiation character, and one for each
               hexadecimal digit that could be produced from a mantissa
               and an exponent.

               The following table contains minimum output string
               lengths necessary to obtain the complete character
               string produced by this routine for some typical
               implementations of double precision numbers.

                  Double precision number
                  Size Mantissa Exponent   Minimum output string
                  bits   bits     bits     length
                  ---- -------- --------   ----------------------
                  64   48       15         3 + 12 + 4 = 19
                  64   55+1     8          3 + 14 + 2 = 19 (VAX)
                  64   52       11         3 + 13 + 3 = 19 (IEEE)

               The base 16 "scientific notation" character string
               produced by this routine will be left justified and
               consist of a contiguous sequence of characters with one
               of the following formats:

                  (1)   h h h h  ... h ^H H  ... H
                         1 2 3 4      n  1 2      m

                  (2)   -h h h h  ... h ^H H  ... H
                          1 2 3 4      n  1 2      m

                  (3)   h h h h  ... h ^-H H  ... H
                         1 2 3 4      n   1 2      m

                  (4)   -h h h h  ... h ^-H H  ... H
                          1 2 3 4      n   1 2      m

               where

                  h   and  H   denote hexadecimal digits
                   i        j

                  '^'          denotes exponentiation ( base 16 )

               and

                  '+' and '-'  have their usual interpretations.

Parameters


   STRLEN      is the maximum number of characters permitted in the
               output string. The value of STRLEN is 255.

Examples


   Any numerical results shown for this example may differ between
   platforms as the results depend on the SPICE kernels used as input
   and the machine specific arithmetic implementation.

   1) Convert a set of double precision numbers to their equivalent
      character string using a base 16 "scientific notation."


      Example code begins here.


      PRO dp2hx_ex1

         number = [  2.0e-9,       1.0,     -1.0,  1024.0,  $
                    -1024.0,  521707.0,     27.0,     0.0 ]

         ;;
         ;; Loop over the `number' array, call cspice_dp2hx for each
         ;; element of `number'.
         ;;
         print, 'number       string           '
         print, '-----------  -----------------'

         for i=0, 7 do begin

            cspice_dp2hx, number[i], strval
            print, format='(E11.4,2A)', number[i], '  ', strval

         endfor

      END


      When this program was executed on a Mac/Intel/IDL8.x/64-bit
      platform, the output was:


      number       string
      -----------  -----------------
       2.0000E-09  89705F^-7
       1.0000E+00  1^1
      -1.0000E+00  -1^1
       1.0240E+03  4^3
      -1.0240E+03  -4^3
       5.2171E+05  7F5EB^5
       2.7000E+01  1B^2
       0.0000E+00  0^0


      Note: the hat or caret, '^', signals an exponent.

Particulars


   This routine converts a double precision number into an equivalent
   character string using a base 16 "scientific notation." This
   representation allows the full precision of a number to be placed
   in a format that is suitable for porting or archival storage.

   This routine is one of a pair of routines which are used to
   perform conversions between double precision numbers and
   an equivalent base 16 "scientific notation" character string
   representation:

      cspice_dp2hx  -- Convert a double precision number into a base 16
                       "scientific notation" character string.

      cspice_hx2dp  -- Convert a base 16 "scientific notation"
                       character string into a double precision number.

Exceptions


   1)  If the input argument `number' is undefined, an error is
       signaled by the IDL error handling system.

   2)  If the input argument `number' is not of the expected type, or
       it does not have the expected dimensions and size, an error is
       signaled by the Icy interface.

   3)  If the output argument `hxstr' is not a named variable, an
       error is signaled by the Icy interface.

Files


   None.

Restrictions


   1)  The maximum number of characters permitted in the output
       string is specified by the parameter STRLEN.

Required_Reading


   ICY.REQ

Literature_References


   None.

Author_and_Institution


   J. Diaz del Rio     (ODC Space)
   E.D. Wright         (JPL)

Version


   -Icy Version 1.1.0, 10-AUG-2021 (JDR)

       Changed the output argument name "string" to "hxstr" for
       consistency with other routines.

       Edited the -Examples section to comply with NAIF standard. Added
       the complete code that produces the existing solution.

       Added -Parameters, -Exceptions, -Files, -Restrictions,
       -Literature_References and -Author_and_Institution sections.

       Removed reference to the routine's corresponding CSPICE header from
       -Abstract section.

       Added arguments' type and size information in the -I/O section.

   -Icy Version 1.0.0, 29-APR-2009 (EDW)

Index_Entries


   convert d.p. to signed normalized hexadecimal string
   convert d.p. number to encoded d.p. number
   convert d.p. to base 16 scientific notation



Fri Dec 31 18:43:03 2021