Table of contents
CSPICE_HX2DP converts a string representing a double precision number in
a base 16 "scientific notation" into its equivalent double precision
number.
Given:
string a character string containing a base 16 "scientific notation"
representation of a double precision number which is to be
converted to a double precision number.
help, string
STRING = Scalar
Examples of such a string are:
'2A^3' = ( 2/16 + 10/( 16^2 ) ) * 16^3 = 672.0D0
and
'-B^1' = - ( 11/16 ) * 16^1 = -11.0D0
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','a' 10.0D0
'3' 3.0D0 'B','b' 11.0D0
'4' 4.0D0 'C','c' 12.0D0
'5' 5.0D0 'D','d' 13.0D0
'6' 6.0D0 'E','e' 14.0D0
'7' 7.0D0 'F','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.
A base 16 "scientific notation" character string which
is to be parsed by this routine should consist of a sign,
'+' or '-' (the plus sign is optional for nonnegative
numbers), followed immediately by a contiguous sequence
of hexadecimal digits, the exponent character, and a
signed hexadecimal exponent. The exponent is required,
but the sign is optional for a nonnegative exponent.
A number in base 16 "scientific notation" consists 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
(5) +h h h h ... h ^+H H ... H
1 2 3 4 n 1 2 m
(6) -h h h h ... h ^+H H ... H
1 2 3 4 n 1 2 m
(7) h h h h ... h ^-H H ... H
1 2 3 4 n 1 2 m
(8) +h h h h ... h ^-H H ... H
1 2 3 4 n 1 2 m
(9) -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;
and
+ and - have their usual interpretations.
`string' may have leading and trailing blanks, but blanks
embedded within the significant portion of the input
string are not allowed.
the call:
cspice_hx2dp, string, number, error, errmsg
returns:
number the double precision value to be returned.
help, number
DOUBLE = Scalar
The value of this argument is not changed if an error occurs
while parsing the input string.
error a logical flag which indicates whether an error occurred while
attempting to parse `number' from the input character string
`string'.
help, error
BOOLEAN = Scalar
`error' will have the value True if an error occurs. It will
have the value False otherwise.
errmsg a descriptive error message if an error occurs while attempting
to parse the number `number' from the hexadecimal character
string `string', blank otherwise.
help, errmsg
STRING = Scalar
MAXMAN is the maximum number of digits in a hexadecimal
mantissa. The value of MAXMAN is 31.
The current value of MAXMAN is more than sufficient for
most double precision implementations, providing almost
twice as many digits as can actually be produced. This
value may be changed when a greater precision is known
to exist among all of the supported platforms.
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 character strings containing a base 16
"scientific notation" representation of a double precision
number, to their double precision values.
Example code begins here.
PRO hx2dp_ex1
;;
;; Assign an array of strings representing, in base 16
;; "scientific notation", double precision numbers.
;; Not all of them are valid representations.
;;
number = [ '89705F4136B4A6^-7', '12357898765X34', $
'1^1', '-1^1', $
'4^3', '-4^3', $
'7F5EB^5', '7F5eb^5', $
'1B^2', '+1B^2', $
'+1B^+2', '0^0', $
' ', '-ab238z^2', $
'234ABC', '234ABC^']
;;
;; Loop over the `number' array, call cspice_hx2dp for each
;; element of `number'.
;;
print, format='(A)', 'string number'
print, format='(A)', '----------------- ----------------'
for i=0L, 15L do begin
cspice_hx2dp, number[i], value, error, errmsg
if ( error ) then begin
print, format='(A17,2X,A)', number[i], errmsg
endif else begin
print, format='(A17,X,E17.9)', number[i], value
endelse
endfor
;;
;; Finally, try with a number that has too many digits in
;; the mantissa.
;;
cspice_hx2dp, '4ABC123AB346523BDC568798C2473678^1', $
value, error, errmsg
print
print, 'String 4ABC123AB346523BDC568798C2473678^1 produces:'
print, ' ', errmsg
END
When this program was executed on a Mac/Intel/IDL8.x/64-bit
platform, the output was:
string number
----------------- ----------------
89705F4136B4A6^-7 2.000000000E-09
12357898765X34 ERROR: Illegal character 'X' encountered.
1^1 1.000000000E+00
-1^1 -1.000000000E+00
4^3 1.024000000E+03
-4^3 -1.024000000E+03
7F5EB^5 5.217070000E+05
7F5eb^5 5.217070000E+05
1B^2 2.700000000E+01
+1B^2 2.700000000E+01
+1B^+2 2.700000000E+01
0^0 0.000000000E+00
ERROR: A blank input string is not allowed.
-ab238z^2 ERROR: Illegal character 'z' encountered.
234ABC ERROR: Missing exponent.
234ABC^ ERROR: Missing exponent.
String 4ABC123AB346523BDC568798C2473678^1 produces:
ERROR: Too many digits in the mantissa (> 31).
Note: The hat or caret, '^', signals an exponent.
This routine will convert a character string containing a number
in base 16 "scientific notation" into its equivalent double
precision number.
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.
1) If an unexpected character is encountered, an appropriate
error message will be set, and the routine will exit. The
value of `number' will be unchanged.
2) If the input string represents a number that is larger in
absolute magnitude than the maximum representable
double precision number an appropriate error message
will be set, and the routine will exit. The value of
`number' will be unchanged.
3) If the input string is blank, an appropriate error message
will be set, and the routine will exit. The value of
`number' will be unchanged.
4) If the string has too many digits in the mantissa, then an
appropriate error message will be set, and the routine will
exit. The value of `number' will be unchanged.
5) This routine does NOT check for underflow errors when
constructing a double precision number.
6) If the input argument `string' is undefined, an error is
signaled by the IDL error handling system.
7) If the input argument `string' is not of the expected type, or
it does not have the expected dimensions and size, an error is
signaled by the Icy interface.
8) If any of the output arguments, `number', `error' or `errmsg',
is not a named variable, an error is signaled by the Icy
interface.
None.
1) The current value of MAXMAN is more than sufficient for most
double precision implementations, providing almost twice as
many digits as can actually be produced.
ICY.REQ
None.
J. Diaz del Rio (ODC Space)
E.D. Wright (JPL)
-Icy Version 1.0.1, 01-JUN-2021 (JDR)
Edited the header to comply with NAIF standard. Added complete
code example based on existing example.
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)
convert signed normalized hexadecimal string to d.p.
convert encoded d.p. number to d.p. number
convert base 16 scientific notation d.p. number
|