| hx2dp |
|
Table of contents
Procedure
HX2DP ( Hexadecimal string to d.p. number )
SUBROUTINE HX2DP ( STRING, NUMBER, ERROR, ERRMSG )
Abstract
Convert a string representing a double precision number in a
base 16 "scientific notation" into its equivalent double
precision number.
Required_Reading
None.
Keywords
ALPHANUMERIC
CONVERSION
Declarations
IMPLICIT NONE
INTEGER MAXMAN
PARAMETER ( MAXMAN = 31 )
CHARACTER*(*) STRING
DOUBLE PRECISION NUMBER
LOGICAL ERROR
CHARACTER*(*) ERRMSG
Brief_I/O
VARIABLE I/O DESCRIPTION
-------- --- --------------------------------------------------
MAXMAN P Maximum number of digits in a hex mantissa.
STRING I Hex form string to convert to double precision.
NUMBER O Double precision value to be returned.
ERROR O A logical flag which is .TRUE. on error.
ERRMSG O A descriptive error message.
Detailed_Input
STRING is 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.
Examples of such a string are:
'2A^3' = ( 2/16 + 10/( 16**2 ) ) * 16**3 = 672.0
and
'-B^1' = - ( 11/16 ) * 16**1 = -11.0
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.
Detailed_Output
NUMBER is the double precision value to be returned. The value
of this argument is not changed if an error occurs while
parsing the input string.
ERROR is a logical flag which indicates whether an error
occurred while attempting to parse NUMBER from the input
character string STRING. ERROR will have the value
.TRUE. if an error occurs. It will have the value
.FALSE. otherwise.
ERRMSG is a descriptive error message if an error occurs while
attempting to parse the number NUMBER from the
hexadecimal character string STRING, blank otherwise.
Parameters
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.
Exceptions
Error free.
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) If the output error message string is not long enough to
contain the entire error message, the error message will be
truncated on the right.
6) This routine does NOT check for underflow errors when
constructing a double precision number.
Files
None.
Particulars
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:
DP2HX -- Convert a double precision number into a base 16
"scientific notation" character string.
HX2DP -- Convert a base 16 "scientific notation"
character string into a double precision number.
Examples
The numerical results shown for this example may differ across
platforms. The results depend on the SPICE kernels used as
input, the compiler and supporting libraries, 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.
PROGRAM HX2DP_EX1
IMPLICIT NONE
C
C Local constants.
C
INTEGER ERRLEN
PARAMETER ( ERRLEN = 80 )
INTEGER STRLEN
PARAMETER ( STRLEN = 17 )
C
C Local variables.
C
CHARACTER*(ERRLEN) ERRMSG
CHARACTER*(STRLEN) NUMBER ( 16 )
DOUBLE PRECISION VALUE
INTEGER I
LOGICAL ERROR
C
C Assign an array of strings representing, in base 16
C "scientific notation", double precision numbers.
C Not all of them are valid representations.
C
DATA 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^' /
C
C Loop over the NUMBER array, call HX2DP for each
C element of NUMBER.
C
WRITE(*,'(A)') 'string number'
WRITE(*,'(A)') '----------------- ----------------'
DO I= 1, 16
CALL HX2DP ( NUMBER(I), VALUE, ERROR, ERRMSG )
IF ( ERROR ) THEN
WRITE(*,'(A17,2X,A)') NUMBER(I), ERRMSG
ELSE
WRITE(*,'(A17,X,E17.9)') NUMBER(I), VALUE
END IF
END DO
C
C Finally, try with a number that has too many digits in
C the mantissa.
C
CALL HX2DP ( '4ABC123AB346523BDC568798C2473678^1',
. VALUE, ERROR, ERRMSG )
WRITE(*,*)
WRITE(*,*) 'String 4ABC123AB346523BDC568798C2473678^1 '
. // 'produces:'
WRITE(*,*) ' ', ERRMSG
END
When this program was executed on a Mac/Intel/gfortran/64-bit
platform, the output was:
string number
----------------- ----------------
89705F4136B4A6^-7 0.200000000E-08
12357898765X34 ERROR: Illegal character 'X' encountered.
1^1 0.100000000E+01
-1^1 -0.100000000E+01
4^3 0.102400000E+04
-4^3 -0.102400000E+04
7F5EB^5 0.521707000E+06
7F5eb^5 0.521707000E+06
1B^2 0.270000000E+02
+1B^2 0.270000000E+02
+1B^+2 0.270000000E+02
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.
Note that some errors are machine dependent. For example,
for a VAX using D_floating arithmetic we get:
STRING = '23BCE^30'
NUMBER = ( Not defined )
ERROR = .TRUE.
ERRMSG = 'ERROR: Number is too large to be represented.'
STRING = '-2abc3^22'
NUMBER = ( Not defined )
ERROR = .TRUE.
ERRMSG = 'ERROR: Number is too small to be represented.'
Restrictions
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.
Literature_References
None.
Author_and_Institution
J. Diaz del Rio (ODC Space)
K.R. Gehringer (JPL)
B.V. Semenov (JPL)
Version
SPICELIB Version 1.1.0, 06-JUL-2021 (JDR) (BVS)
Added IMPLICIT NONE statement.
The declaration of MAXMAN has been promoted to the
$Declarations section and the error produced when the maximum
number of digits for the mantissa is exceeded has been updated
to inform about MAXMAN value.
Edited the header to comply with NAIF standard. Added complete
code example based on existing example.
Updated $Brief_I/O, $Parameters, $Exceptions and $Restrictions
sections to properly describe MAXMAN.
Corrected $Revisions entries.
SPICELIB Version 1.0.1, 10-MAR-1994 (KRG)
Fixed a typo in the description of the input argument STRING.
The example showing the expansion of 160 into hexadecimal
was incorrect. 160 was replaced with 672 which makes the
example correct.
SPICELIB Version 1.0.0, 26-OCT-1992 (KRG)
|
Fri Dec 31 18:36:26 2021