Interface JsonNumber

All Superinterfaces:

JsonValue

public non-sealed interface JsonNumber
extends JsonValue

The interface that represents JSON number, an arbitrary-precision number represented in base 10 using decimal digits.

A JsonNumber can be created by parsing JSON text using either Json.parse(String) or Json.parse(char[]). When a JSON number is parsed, a JsonNumber object is created as long as the input number text adheres to the JSON number syntax.

Alternatively, of(int), of(long), of(double), or of(String) can be used to obtain a JsonNumber. The value of the JsonNumber can be retrieved as an int with asInt(), as a long with asLong(), or as a double with asDouble(). toString() can be used to return the string representation of the JsonNumber.

API Note:

To avoid precision loss when converting JsonNumbers to Java types, or when converting JsonNumbers outside the range of long or double, use toString() to create arbitrary-precision Java objects, for example,

new BigDecimal(jsonNumber.toString())
// or if an integral number is preferred
new BigInteger(jsonNumber.toString())
// for cases with an exponent or zero fractional part
new BigDecimal(jsonNumber.toString()).toBigIntegerExact()

Since:

28

External Specifications

• RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format - Numbers

Method Summary

Modifier and Type	Method	Description
double	asDouble()	Returns a double if this JsonValue is an instance of JsonNumber that can be converted, as if by Double.parseDouble, to a finite double value; otherwise, throws a JsonValueException.
int	asInt()	Returns an int if this JsonValue is an instance of JsonNumber that can be converted exactly; otherwise, throws a JsonValueException.
long	asLong()	Returns a long if this JsonValue is an instance of JsonNumber that can be converted exactly; otherwise, throws a JsonValueException.
static JsonNumber	of(double num)	Creates a JsonNumber from the given double value.
static JsonNumber	of(int num)	Creates a JsonNumber from the given int value.
static JsonNumber	of(long num)	Creates a JsonNumber from the given long value.
static JsonNumber	of(String num)	Creates a JsonNumber from the given String value.
String	toString()	Returns the string representation of this JsonNumber.

Methods declared in interface JsonValue

asBoolean, asList, asMap, asString, get, get, tryGet, tryValue

Modifier and Type	Method	Description
default boolean	asBoolean()	Returns the boolean value represented by this JsonValue if it is an instance of JsonBoolean; otherwise, throws a JsonValueException.
default List<JsonValue>	asList()	Returns an unmodifiable list of the JsonValues if this JsonValue is an instance of JsonArray; otherwise, throws a JsonValueException.
default Map<String, JsonValue>	asMap()	Returns an unmodifiable map of String to JsonValue if this JsonValue is an instance of JsonObject; otherwise, throws a JsonValueException.
default String	asString()	Returns the String value represented by this JsonValue if it is an instance of JsonString; otherwise, throws a JsonValueException.
default JsonValue	get(int index)	Returns the JsonValue associated with the given index if this JsonValue is an instance of JsonArray; otherwise, throws a JsonValueException.
default JsonValue	get(String name)	Returns the JsonValue associated with the given member name if this JsonValue is an instance of JsonObject; otherwise, throws a JsonValueException.
default Optional<JsonValue>	tryGet(String name)	Returns an Optional containing the value of a given member of this JsonObject, or an empty Optional if the member is absent; throws JsonValueException if this JsonValue is not a JsonObject.
default Optional<JsonValue>	tryValue()	Returns an Optional containing this JsonValue if it is not an instance of JsonNull, otherwise an empty Optional.

Method Details

asInt

int asInt()

Returns an int if this JsonValue is an instance of JsonNumber that can be converted exactly; otherwise, throws a JsonValueException. This JsonValue must be a JSON number that represents a whole number and that is within the range Integer.MIN_VALUE to Integer.MAX_VALUE, inclusive. This is true even if the JSON number contains an exponent or a fractional part consisting of all zeroes. For example, the JSON numbers "123.0" and "1.23e2" both produce an int value of 123. A JsonValueException is thrown when the numeric value cannot be represented as an int; for example, the JSON number "5.5".

Specified by:

asInt in interface JsonValue

Returns:

an int if this JsonValue is an instance of JsonNumber that can be converted exactly; otherwise, throws a JsonValueException

Throws:

JsonValueException - if this JsonNumber is not representable as an int.

asLong

long asLong()

Returns a long if this JsonValue is an instance of JsonNumber that can be converted exactly; otherwise, throws a JsonValueException. This JsonValue must be a JSON number that represents a whole number and that is within the range Long.MIN_VALUE to Long.MAX_VALUE, inclusive. This is true even if the JSON number contains an exponent or a fractional part consisting of all zeroes. For example, the JSON numbers "123.0" and "1.23e2" both produce a long value of 123. A JsonValueException is thrown when the numeric value cannot be represented as a long; for example, the JSON number "5.5".

Specified by:

asLong in interface JsonValue

Returns:

a long if this JsonValue is an instance of JsonNumber that can be converted exactly; otherwise, throws a JsonValueException

Throws:

JsonValueException - if this JsonNumber is not representable as a long.

asDouble

double asDouble()

Returns a double if this JsonValue is an instance of JsonNumber that can be converted, as if by Double.parseDouble, to a finite double value; otherwise, throws a JsonValueException.

Specified by:

asDouble in interface JsonValue

API Note:

Callers of this method should be aware of the potential loss in precision or magnitude when a JsonNumber is converted to a double. A JSON number may be rounded to the nearest representable double value, and a JSON number with more than about 15 decimal digits may lose precision. A JSON number with a magnitude larger than about 1.8 × 10³⁰⁸ cannot be represented as a finite double, and attempting to convert such a number will result in JsonValueException. (This differs from Double.parseDouble, which will return Double.POSITIVE_INFINITY or Double.NEGATIVE_INFINITY for such cases.) This method will never return Double.NaN. However, this method will properly convert and return negative zero (-0.0). To handle numbers of almost arbitrary precision and magnitude, consider converting to BigDecimal using new BigDecimal(jsonNumber.toString()). Note that BigDecimal cannot represent negative zero.

Returns:

a double if this JsonValue is an instance of JsonNumber that can be converted, as if by Double.parseDouble, to a finite double value; otherwise, throws a JsonValueException

Throws:

JsonValueException - if this JsonNumber is not representable as a finite double.

of

static JsonNumber of(double num)

Creates a JsonNumber from the given double value. The string representation of the JsonNumber created is produced by applying Double.toString(double) on num.

Parameters:

num - the given double value.

Returns:

a JsonNumber created from the double value

Throws:

IllegalArgumentException - if the given double value is not a finite floating-point value (NaN, positive infinity, or negative infinity).

of

static JsonNumber of(int num)

Creates a JsonNumber from the given int value. The string representation of the JsonNumber created is produced by applying Integer.toString(int) on num.

Parameters:

num - the given int value.

Returns:

a JsonNumber created from the int value

of

static JsonNumber of(long num)

Creates a JsonNumber from the given long value. The string representation of the JsonNumber created is produced by applying Long.toString(long) on num.

Parameters:

num - the given long value.

Returns:

a JsonNumber created from the long value

of

static JsonNumber of(String num)

Creates a JsonNumber from the given String value. The string representation of the JsonNumber created is equivalent to num with any leading or trailing JSON insignificant whitespaces removed.

Parameters:

num - the given String value.

Returns:

a JsonNumber created from the String value

Throws:

IllegalArgumentException - if num is not a valid string representation of a JsonNumber.

NullPointerException - if num is null

toString

String toString()

Returns the string representation of this JsonNumber. If this JsonNumber is created by parsing a JSON number in a JSON text, it preserves the string representation in the JSON text, regardless of its precision or range. For example, a JSON number like "3.141592653589793238462643383279" in the JSON text will be returned exactly as it appears. If this JsonNumber is created via one of the factory methods, such as of(double), then the string representation is specified by the factory method.

Specified by:

toString in interface JsonValue

Overrides:

toString in class Object

Returns:

the string representation of this JsonNumber

See Also:

• Json.toDisplayString(JsonValue, String)