Class JSONNumber

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Comparable<JSONValue>

    @NotMutable
    @ThreadSafety(level=COMPLETELY_THREADSAFE)
    public final class JSONNumber
    extends JSONValue
    This class provides an implementation of a JSON value that represents a base-ten numeric value of arbitrary size. It may or may not be a floating-point value (including a decimal point with numbers to the right of it), and it may or may not be expressed using scientific notation. The numeric value will be represented internally as a BigDecimal.

    The string representation of a JSON number consists of the following elements, in the following order:
    1. An optional minus sign to indicate that the value is negative. If this is absent, then the number will be positive. Positive numbers must not be prefixed with a plus sign.
    2. One or more numeric digits to specify the whole number portion of the value. There must not be any unnecessary leading zeroes, so the first digit may be zero only if it is the only digit in the whole number portion of the value.
    3. An optional decimal point followed by at least one numeric digit to indicate the fractional portion of the value. Trailing zeroes are allowed in the fractional component.
    4. An optional 'e' or 'E' character, followed by an optional '+' or '-' character and at least one numeric digit to indicate that the value is expressed in scientific notation and the number before the uppercase or lowercase E should be multiplied by the specified positive or negative power of ten.
    It is possible for the same number to have multiple equivalent string representations. For example, all of the following valid string representations of JSON numbers represent the same numeric value:
    • 12345
    • 12345.0
    • 1.2345e4
    • 1.2345e+4
    JSON numbers must not be enclosed in quotation marks.

    If a JSON number is created from its string representation, then that string representation will be returned from the toString() method (or appended to the provided buffer for the toString(StringBuilder) method). If a JSON number is created from a long or double value, then the Java string representation of that value (as obtained from the String.valueOf method) will be used as the string representation for the number. If a JSON number is created from a BigDecimal value, then the Java string representation will be obtained via that value's toPlainString method.

    The normalized representation of a JSON number is a canonical string representation for that number. That is, all equivalent JSON number values will have the same normalized representation. The normalized representation will never use scientific notation, will never have trailing zeroes in the fractional component, and will never have a fractional component if that fractional component would be zero. For example, for the logically-equivalent values "12345", "12345.0", "1.2345e4", and "1.2345e+4", the normalized representation will be "12345". For the logically-equivalent values "9876.5", "9876.50", and "9.8765e3", the normalized representation will be "9876.5".
    See Also:
    Serialized Form
    • Constructor Summary

      Constructors 
      Constructor Description
      JSONNumber​(double value)
      Creates a new JSON number with the provided value.
      JSONNumber​(long value)
      Creates a new JSON number with the provided value.
      JSONNumber​(java.lang.String stringRepresentation)
      Creates a new JSON number from the provided string representation.
      JSONNumber​(java.math.BigDecimal value)
      Creates a new JSON number with the provided value.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void appendToJSONBuffer​(JSONBuffer buffer)
      Appends this value to the provided JSON buffer.
      void appendToJSONBuffer​(java.lang.String fieldName, JSONBuffer buffer)
      Appends a field with the given name and this value to the provided JSON buffer.
      boolean equals​(JSONValue v, boolean ignoreFieldNameCase, boolean ignoreValueCase, boolean ignoreArrayOrder)
      Indicates whether this JSON value is considered equal to the provided JSON value, subject to the specified constraints.
      boolean equals​(java.lang.Object o)
      Indicates whether the provided object is equal to this JSON value.
      java.math.BigDecimal getValue()
      Retrieves the value of this JSON number as a BigDecimal.
      double getValueAsDouble()
      Retrieves the value of this JSON number as a double.
      java.lang.Integer getValueAsInteger()
      Retrieves the value of this JSON number as an Integer, but only if the value can be losslessly represented as an integer.
      java.lang.Long getValueAsLong()
      Retrieves the value of this JSON number as a Long, but only if the value can be losslessly represented as a long.
      int hashCode()
      Retrieves a hash code for this JSON value.
      java.lang.String toNormalizedString()
      Retrieves a normalized string representation of this number as it should appear in a JSON object.
      java.lang.String toNormalizedString​(boolean ignoreFieldNameCase, boolean ignoreValueCase, boolean ignoreArrayOrder)
      Retrieves a normalized string representation of this number as it should appear in a JSON object.
      void toNormalizedString​(java.lang.StringBuilder buffer)
      Appends a normalized string representation of this number as it should appear in a JSON object to the provided buffer.
      void toNormalizedString​(java.lang.StringBuilder buffer, boolean ignoreFieldNameCase, boolean ignoreValueCase, boolean ignoreArrayOrder)
      Appends a normalized string representation of this number as it should appear in a JSON object to the provided buffer.
      JSONNumber toNormalizedValue​(boolean ignoreFieldNameCase, boolean ignoreValueCase, boolean ignoreArrayOrder)
      Retrieves a normalized representation of this value using the provided settings.
      java.lang.String toSingleLineString()
      Retrieves a single-line string representation of this number as it should appear in a JSON object.
      void toSingleLineString​(java.lang.StringBuilder buffer)
      Appends a single-line string representation of this number as it should appear in a JSON object to the provided buffer.
      java.lang.String toString()
      Retrieves a string representation of this number as it should appear in a JSON object.
      void toString​(java.lang.StringBuilder buffer)
      Appends a string representation of this number as it should appear in a JSON object to the provided buffer.
      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait
    • Constructor Detail

      • JSONNumber

        public JSONNumber​(long value)
        Creates a new JSON number with the provided value.
        Parameters:
        value - The value for this JSON number.
      • JSONNumber

        public JSONNumber​(double value)
        Creates a new JSON number with the provided value.
        Parameters:
        value - The value for this JSON number.
      • JSONNumber

        public JSONNumber​(@NotNull
                          java.math.BigDecimal value)
        Creates a new JSON number with the provided value.
        Parameters:
        value - The value for this JSON number. It must not be null.
      • JSONNumber

        public JSONNumber​(@NotNull
                          java.lang.String stringRepresentation)
                   throws JSONException
        Creates a new JSON number from the provided string representation.
        Parameters:
        stringRepresentation - The string representation to parse as a JSON number. It must not be null.
        Throws:
        JSONException - If the provided string cannot be parsed as a valid JSON number.
    • Method Detail

      • getValue

        @NotNull
        public java.math.BigDecimal getValue()
        Retrieves the value of this JSON number as a BigDecimal.
        Returns:
        The value of this JSON number as a BigDecimal.
      • getValueAsInteger

        @Nullable
        public java.lang.Integer getValueAsInteger()
        Retrieves the value of this JSON number as an Integer, but only if the value can be losslessly represented as an integer.
        Returns:
        The Integer value for this JSON number, or null if the value has a fractional component or is outside the range of a Java integer.
      • getValueAsLong

        @Nullable
        public java.lang.Long getValueAsLong()
        Retrieves the value of this JSON number as a Long, but only if the value can be losslessly represented as a long.
        Returns:
        The Long value for this JSON number, or null if the value has a fractional component or is outside the range of a Java long.
      • getValueAsDouble

        public double getValueAsDouble()
        Retrieves the value of this JSON number as a double. Note that if the BigDecimal value is outside the range that can be represented by a double, then the value returned may be converted to positive or negative infinity. Further, the double value that is returned could potentially have less precision than the associated BigDouble value.
        Returns:
        The double value for this JSON number.
      • hashCode

        public int hashCode()
        Retrieves a hash code for this JSON value.
        Specified by:
        hashCode in class JSONValue
        Returns:
        The hash code for this JSON value.
      • equals

        public boolean equals​(@Nullable
                              java.lang.Object o)
        Indicates whether the provided object is equal to this JSON value.
        Specified by:
        equals in class JSONValue
        Parameters:
        o - The object to compare against this JSON value.
        Returns:
        true if the provided object is considered equal to this JSON value, or false if not.
      • equals

        public boolean equals​(@NotNull
                              JSONValue v,
                              boolean ignoreFieldNameCase,
                              boolean ignoreValueCase,
                              boolean ignoreArrayOrder)
        Indicates whether this JSON value is considered equal to the provided JSON value, subject to the specified constraints. Note that not all constraints will apply to all data types.
        Specified by:
        equals in class JSONValue
        Parameters:
        v - The JSON value for which to make the determination. It must not be null.
        ignoreFieldNameCase - Indicates whether to ignore differences in the capitalization of JSON field names.
        ignoreValueCase - Indicates whether to ignore differences in the capitalization of JSON values that represent strings.
        ignoreArrayOrder - Indicates whether to ignore differences in the order of elements in JSON arrays.
        Returns:
        true if this JSON value is considered equal to the provided JSON value (subject to the specified constraints), or false if not.
      • toString

        @NotNull
        public java.lang.String toString()
        Retrieves a string representation of this number as it should appear in a JSON object. If the object containing this number was decoded from a string, then this method will use the same string representation as in that original object. Otherwise, the string representation will be constructed.
        Specified by:
        toString in class JSONValue
        Returns:
        A string representation of this number as it should appear in a JSON object.
      • toString

        public void toString​(@NotNull
                             java.lang.StringBuilder buffer)
        Appends a string representation of this number as it should appear in a JSON object to the provided buffer. If the object containing this number was decoded from a string, then this method will use the same string representation as in that original object. Otherwise, the string representation will be constructed.
        Specified by:
        toString in class JSONValue
        Parameters:
        buffer - The buffer to which the information should be appended.
      • toSingleLineString

        @NotNull
        public java.lang.String toSingleLineString()
        Retrieves a single-line string representation of this number as it should appear in a JSON object. If the object containing this number was decoded from a string, then this method will use the same string representation as in that original object. Otherwise, the string representation will be constructed.
        Specified by:
        toSingleLineString in class JSONValue
        Returns:
        A single-line string representation of this number as it should appear in a JSON object.
      • toSingleLineString

        public void toSingleLineString​(@NotNull
                                       java.lang.StringBuilder buffer)
        Appends a single-line string representation of this number as it should appear in a JSON object to the provided buffer. If the object containing this number was decoded from a string, then this method will use the same string representation as in that original object. Otherwise, the string representation will be constructed.
        Specified by:
        toSingleLineString in class JSONValue
        Parameters:
        buffer - The buffer to which the information should be appended.
      • toNormalizedString

        @NotNull
        public java.lang.String toNormalizedString()
        Retrieves a normalized string representation of this number as it should appear in a JSON object. The normalized representation will not use exponentiation, will not include a decimal point if the value can be represented as an integer, and will not include any unnecessary trailing zeroes if it can only be represented as a floating-point value.
        Specified by:
        toNormalizedString in class JSONValue
        Returns:
        A normalized string representation of this number as it should appear in a JSON object.
      • toNormalizedString

        public void toNormalizedString​(@NotNull
                                       java.lang.StringBuilder buffer)
        Appends a normalized string representation of this number as it should appear in a JSON object to the provided buffer. The normalized representation will not use exponentiation, will not include a decimal point if the value can be represented as an integer, and will not include any unnecessary trailing zeroes if it can only be represented as a floating-point value.
        Specified by:
        toNormalizedString in class JSONValue
        Parameters:
        buffer - The buffer to which the information should be appended.
      • toNormalizedString

        @NotNull
        public java.lang.String toNormalizedString​(boolean ignoreFieldNameCase,
                                                   boolean ignoreValueCase,
                                                   boolean ignoreArrayOrder)
        Retrieves a normalized string representation of this number as it should appear in a JSON object. The normalized representation will not use exponentiation, will not include a decimal point if the value can be represented as an integer, and will not include any unnecessary trailing zeroes if it can only be represented as a floating-point value.
        Specified by:
        toNormalizedString in class JSONValue
        Parameters:
        ignoreFieldNameCase - Indicates whether field names should be treated in a case-sensitive (if false) or case-insensitive (if true) manner.
        ignoreValueCase - Indicates whether string field values should be treated in a case-sensitive (if false) or case-insensitive (if true) manner.
        ignoreArrayOrder - Indicates whether the order of elements in an array should be considered significant (if false) or insignificant (if true).
        Returns:
        A normalized string representation of this number as it should appear in a JSON object.
      • toNormalizedString

        public void toNormalizedString​(@NotNull
                                       java.lang.StringBuilder buffer,
                                       boolean ignoreFieldNameCase,
                                       boolean ignoreValueCase,
                                       boolean ignoreArrayOrder)
        Appends a normalized string representation of this number as it should appear in a JSON object to the provided buffer. The normalized representation will not use exponentiation, will not include a decimal point if the value can be represented as an integer, and will not include any unnecessary trailing zeroes if it can only be represented as a floating-point value.
        Specified by:
        toNormalizedString in class JSONValue
        Parameters:
        buffer - The buffer to which the information should be appended.
        ignoreFieldNameCase - Indicates whether field names should be treated in a case-sensitive (if false) or case-insensitive (if true) manner.
        ignoreValueCase - Indicates whether string field values should be treated in a case-sensitive (if false) or case-insensitive (if true) manner.
        ignoreArrayOrder - Indicates whether the order of elements in an array should be considered significant (if false) or insignificant (if true).
      • toNormalizedValue

        @NotNull
        public JSONNumber toNormalizedValue​(boolean ignoreFieldNameCase,
                                            boolean ignoreValueCase,
                                            boolean ignoreArrayOrder)
        Retrieves a normalized representation of this value using the provided settings.
        Specified by:
        toNormalizedValue in class JSONValue
        Parameters:
        ignoreFieldNameCase - Indicates whether field names should be treated in a case-sensitive (if false) or case-insensitive (if true) manner.
        ignoreValueCase - Indicates whether string field values should be treated in a case-sensitive (if false) or case-insensitive (if true) manner.
        ignoreArrayOrder - Indicates whether the order of elements in an array should be considered significant (if false) or insignificant (if true).
        Returns:
        A normalized representation of this value using the provided settings.
      • appendToJSONBuffer

        public void appendToJSONBuffer​(@NotNull
                                       JSONBuffer buffer)
        Appends this value to the provided JSON buffer. This will not include a field name, so it should only be used for Boolean value elements in an array.
        Specified by:
        appendToJSONBuffer in class JSONValue
        Parameters:
        buffer - The JSON buffer to which this value should be appended.
      • appendToJSONBuffer

        public void appendToJSONBuffer​(@NotNull
                                       java.lang.String fieldName,
                                       @NotNull
                                       JSONBuffer buffer)
        Appends a field with the given name and this value to the provided JSON buffer.
        Specified by:
        appendToJSONBuffer in class JSONValue
        Parameters:
        fieldName - The name to use for the field.
        buffer - The JSON buffer to which this value should be appended.