Returns a
Double
object holding the
double
value represented by the argument string
s
.
If s
is null
, then a
NullPointerException
is thrown.
Leading and trailing whitespace characters in s
are ignored. Whitespace is removed as if by the String.trim()
method; that is, both ASCII space and control
characters are removed. The rest of s
should
constitute a FloatValue as described by the lexical
syntax rules:
- FloatValue:
- Signopt
NaN
- Signopt
Infinity
- Signopt FloatingPointLiteral
- Signopt HexFloatingPointLiteral
- SignedInteger
- HexFloatingPointLiteral:
- HexSignificand BinaryExponent FloatTypeSuffixopt
- HexSignificand:
- HexNumeral
- HexNumeral
.
0x
HexDigitsopt
.
HexDigits
0X
HexDigitsopt
.
HexDigits
- BinaryExponent:
- BinaryExponentIndicator SignedInteger
- BinaryExponentIndicator:
p
P
where
Sign,
FloatingPointLiteral,
HexNumeral,
HexDigits,
SignedInteger and
FloatTypeSuffix are as defined in the lexical structure
sections of the of the
Java Language
Specification. If
s
does not have the form of
a
FloatValue, then a
NumberFormatException
is thrown. Otherwise,
s
is regarded as
representing an exact decimal value in the usual
"computerized scientific notation" or as an exact
hexadecimal value; this exact numerical value is then
conceptually converted to an "infinitely precise"
binary value that is then rounded to type
double
by the usual round-to-nearest rule of IEEE 754 floating-point
arithmetic, which includes preserving the sign of a zero
value. Finally, a
Double
object representing this
double
value is returned.
To interpret localized string representations of a
floating-point value, use subclasses of NumberFormat
.
Note that trailing format specifiers, specifiers that
determine the type of a floating-point literal
(1.0f
is a float
value;
1.0d
is a double
value), do
not influence the results of this method. In other
words, the numerical value of the input string is converted
directly to the target floating-point type. The two-step
sequence of conversions, string to float
followed
by float
to double
, is not
equivalent to converting a string directly to
double
. For example, the float
literal 0.1f
is equal to the double
value 0.10000000149011612
; the float
literal 0.1f
represents a different numerical
value than the double
literal
0.1
. (The numerical value 0.1 cannot be exactly
represented in a binary floating-point number.)
To avoid calling this method on an invalid string and having
a NumberFormatException
be thrown, the regular
expression below can be used to screen the input string:
final String Digits = "(\\p{Digit}+)";
final String HexDigits = "(\\p{XDigit}+)";
// an exponent is 'e' or 'E' followed by an optionally
// signed decimal integer.
final String Exp = "[eE][+-]?"+Digits;
final String fpRegex =
("[\\x00-\\x20]*"+ // Optional leading "whitespace"
"[+-]?(" + // Optional sign character
"NaN|" + // "NaN" string
"Infinity|" + // "Infinity" string
// A decimal floating-point string representing a finite positive
// number without a leading sign has at most five basic pieces:
// Digits . Digits ExponentPart FloatTypeSuffix
//
// Since this method allows integer-only strings as input
// in addition to strings of floating-point literals, the
// two sub-patterns below are simplifications of the grammar
// productions from the Java Language Specification, 2nd
// edition, section 3.10.2.
// Digits ._opt Digits_opt ExponentPart_opt FloatTypeSuffix_opt
"((("+Digits+"(\\.)?("+Digits+"?)("+Exp+")?)|"+
// . Digits ExponentPart_opt FloatTypeSuffix_opt
"(\\.("+Digits+")("+Exp+")?)|"+
// Hexadecimal strings
"((" +
// 0[xX] HexDigits ._opt BinaryExponent FloatTypeSuffix_opt
"(0[xX]" + HexDigits + "(\\.)?)|" +
// 0[xX] HexDigits_opt . HexDigits BinaryExponent FloatTypeSuffix_opt
"(0[xX]" + HexDigits + "?(\\.)" + HexDigits + ")" +
")[pP][+-]?" + Digits + "))" +
"[fFdD]?))" +
"[\\x00-\\x20]*");// Optional trailing "whitespace"
if (Pattern.matches(fpRegex, myString))
Double.valueOf(myString); // Will not throw NumberFormatException
else {
// Perform suitable alternative action
}
Returns:
a Double
object holding the value
represented by the String
argument.
Parameters:
- s - the string to be parsed.
Throws:
- NumberFormatException - if the string does not contain a
parsable number.