Package net.sf.saxon.value

## Class NumericValue

- java.lang.Object
- - net.sf.saxon.value.AtomicValue
  - - net.sf.saxon.value.NumericValue

- All Implemented Interfaces:
    `java.lang.Comparable<NumericValue>`, `java.lang.Iterable<AtomicValue>`, `AtomicMatchKey`, `AtomicSequence`, `GroundedValue`, `IdentityComparable`, `Item`, `Sequence`, `ConversionResult`
  Direct Known Subclasses:
    `DecimalValue`, `DoubleValue`, `FloatValue`

      public abstract class NumericValue
      extends AtomicValue
      implements java.lang.Comparable<NumericValue>, AtomicMatchKey

  NumericValue is an abstract superclass for IntegerValue, DecimalValue, FloatValue, and DoubleValue

- - ### Field Summary

    - ### Fields inherited from class net.sf.saxon.value.AtomicValue

      `typeLabel`

    - ### Fields inherited from interface net.sf.saxon.expr.sort.AtomicMatchKey

      `NaN_MATCH_KEY`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `NumericValue()` |

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `abstract NumericValue` | `abs()` | Get the absolute value as defined by the XPath abs() function
    `abstract int` | `asSubscript()` | Test whether a number is a possible subscript into a sequence, that is, a whole number greater than zero and less than 2^31
    `abstract NumericValue` | `ceiling()` | Implement the XPath ceiling() function
    `abstract int` | `compareTo​(long other)` | Compare the value to a long
    `int` | `compareTo​(NumericValue other)` | Compare the value to another numeric value
    `abstract boolean` | `effectiveBooleanValue()` | Get the effective boolean value of the value.
    `boolean` | `equals​(java.lang.Object other)` | The equals() function compares numeric equality among integers, decimals, floats, doubles, and their subtypes
    `abstract NumericValue` | `floor()` | Implement the XPath floor() function
    `abstract java.math.BigDecimal` | `getDecimalValue()` | Get the numeric value converted to a decimal
    `abstract double` | `getDoubleValue()` | Get the numeric value as a double
    `abstract float` | `getFloatValue()` | Get the numeric value converted to a float
    `AtomicMatchKey` | `getXPathComparable​(boolean ordered, StringCollator collator, int implicitTimezone)` | Get a Comparable value that implements the XPath ordering comparison semantics for this value.
    `abstract int` | `hashCode()` | hashCode() must be the same for two values that are equal.
    `static boolean` | `isInteger​(AtomicValue value)` | Test whether a value is an integer (an instance of a subtype of xs:integer)
    `boolean` | `isNegativeZero()` | Ask whether this value is negative zero
    `abstract boolean` | `isWholeNumber()` | Ask whether the value is a whole number, that is, whether it compares equal to some integer
    `abstract long` | `longValue()` | Return the numeric value as a Java long.
    `abstract NumericValue` | `negate()` | Change the sign of the number
    `static NumericValue` | `parseNumber​(java.lang.String in)` | Get a numeric value by parsing a string; the type of numeric value depends on the lexical form of the string, following the rules for XPath numeric literals.
    `abstract NumericValue` | `round​(int scale)` | Implement the XPath round() function
    `abstract NumericValue` | `roundHalfToEven​(int scale)` | Implement the XPath 2.0 round-half-to-even() function
    `abstract int` | `signum()` | Ask whether the value is negative, zero, or positive
    `java.lang.String` | `toString()` | Produce a string representation of the value

    - ### Methods inherited from class net.sf.saxon.value.AtomicValue

      `asAtomic, asMapKey, atomize, checkPermittedContents, checkValidInJavascript, copyAsSubType, getCanonicalLexicalRepresentation, getCardinality, getComponent, getGenre, getItemType, getLength, getPrimitiveStringValue, getPrimitiveType, getSchemaComparable, getStringValue, getStringValueCS, getUType, head, identityHashCode, isIdentical, isIdentical, isNaN, itemAt, iterate, iterator, setTypeLabel`

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

    - ### Methods inherited from interface net.sf.saxon.expr.sort.AtomicMatchKey

      `asAtomic`

    - ### Methods inherited from interface net.sf.saxon.om.GroundedValue

      `asIterable, concatenate, containsNode, materialize`

    - ### Methods inherited from interface net.sf.saxon.om.Item

      `isStreamed, reduce, subsequence, toShortString`

    - ### Methods inherited from interface java.lang.Iterable

      `forEach, spliterator`

    - ### Methods inherited from interface net.sf.saxon.om.Sequence

      `makeRepeatable`

- - ### Constructor Detail

    - #### NumericValue

          public NumericValue()

  - ### Method Detail

    - #### parseNumber

          public static NumericValue parseNumber​(java.lang.String in)

      Get a numeric value by parsing a string; the type of numeric value depends on the lexical form of the string, following the rules for XPath numeric literals.
      Parameters:
        `in` - the input string
      Returns:
        a NumericValue representing the value of the string. Returns Double.NaN if the value cannot be parsed as a string.

    - #### getDoubleValue

          public abstract double getDoubleValue()

      Get the numeric value as a double
      Returns:
        A double representing this numeric value; NaN if it cannot be converted

    - #### getFloatValue

          public abstract float getFloatValue()

      Get the numeric value converted to a float
      Returns:
        a float representing this numeric value; NaN if it cannot be converted

    - #### getDecimalValue

          public abstract java.math.BigDecimal getDecimalValue()
                                                        throws ValidationException

      Get the numeric value converted to a decimal
      Returns:
        a decimal representing this numeric value;
      Throws:
        `ValidationException` - if the value cannot be converted, for example if it is NaN or infinite

    - #### effectiveBooleanValue

          public abstract boolean effectiveBooleanValue()

      Get the effective boolean value of the value. This override of this method throws no exceptions.
      Specified by:
        `effectiveBooleanValue` in interface `GroundedValue`
      Overrides:
        `effectiveBooleanValue` in class `AtomicValue`
      Returns:
        true, unless the value is boolean false, numeric zero, or zero-length string

    - #### isInteger

          public static boolean isInteger​(AtomicValue value)

      Test whether a value is an integer (an instance of a subtype of xs:integer)
      Parameters:
        `value` - the value being tested
      Returns:
        true if the value is an instance of xs:integer or a type derived therefrom

    - #### longValue

          public abstract long longValue()
                                  throws XPathException

      Return the numeric value as a Java long.
      Returns:
        the numeric value as a Java long. This performs truncation towards zero.
      Throws:
        `XPathException` - if the value cannot be converted

    - #### negate

          public abstract NumericValue negate()

      Change the sign of the number
      Returns:
        a value, of the same type as the original, with its sign inverted

    - #### floor

          public abstract NumericValue floor()

      Implement the XPath floor() function
      Returns:
        a value, of the same type as that supplied, rounded towards minus infinity

    - #### ceiling

          public abstract NumericValue ceiling()

      Implement the XPath ceiling() function
      Returns:
        a value, of the same type as that supplied, rounded towards plus infinity

    - #### round

          public abstract NumericValue round​(int scale)

      Implement the XPath round() function
      Parameters:
        `scale` - the number of decimal places required in the result (supply 0 for rounding to an integer)
      Returns:
        a value, of the same type as that supplied, rounded towards the nearest whole number (0.5 rounded up)

    - #### roundHalfToEven

          public abstract NumericValue roundHalfToEven​(int scale)

      Implement the XPath 2.0 round-half-to-even() function
      Parameters:
        `scale` - the decimal position for rounding: e.g. 2 rounds to a multiple of 0.01, while -2 rounds to a multiple of 100
      Returns:
        a value, of the same type as the original, rounded towards the nearest multiple of 10**(-scale), with rounding towards the nearest even number if two values are equally near

    - #### signum

          public abstract int signum()

      Ask whether the value is negative, zero, or positive
      Returns:
        -1 if negative, 0 if zero (including negative zero) or NaN, +1 if positive

    - #### isNegativeZero

          public boolean isNegativeZero()

      Ask whether this value is negative zero
      Returns:
        true if this value is float or double negative zero

    - #### isWholeNumber

          public abstract boolean isWholeNumber()

      Ask whether the value is a whole number, that is, whether it compares equal to some integer
      Returns:
        true if the value is a whole number

    - #### asSubscript

          public abstract int asSubscript()

      Test whether a number is a possible subscript into a sequence, that is, a whole number greater than zero and less than 2^31
      Returns:
        the number as an int if it is a possible subscript, or -1 otherwise

    - #### abs

          public abstract NumericValue abs()

      Get the absolute value as defined by the XPath abs() function
      Returns:
        the absolute value
      Since:
        9.2

    - #### getXPathComparable

          public final AtomicMatchKey getXPathComparable​(boolean ordered,
                                                         StringCollator collator,
                                                         int implicitTimezone)

      Get a Comparable value that implements the XPath ordering comparison semantics for this value. Returns null if the value is not comparable according to XPath rules. The implementation for all kinds of NumericValue returns the value itself.
      Specified by:
        `getXPathComparable` in class `AtomicValue`
      Parameters:
        `ordered` - true if an ordered comparison is required. In this case the result is null if the type is unordered; in other cases the returned value will be a Comparable.
        `collator` - the collation to be used when comparing strings
        `implicitTimezone` - the implicit timezone in the dynamic context, used when comparing dates/times with and without timezone
      Returns:
        a collation key that implements the comparison semantics

    - #### compareTo

          public int compareTo​(NumericValue other)

      Compare the value to another numeric value
      Specified by:
        `compareTo` in interface `java.lang.Comparable<NumericValue>`
      Parameters:
        `other` - The other numeric value
      Returns:
        -1 if this one is the lower, 0 if they are numerically equal, +1 if this one is the higher, or if either value is NaN. Where NaN values are involved, they should be handled by the caller before invoking this method.
      Throws:
        `java.lang.ClassCastException` - if the other value is not a NumericValue (the parameter is declared as Object to satisfy the Comparable interface)

    - #### compareTo

          public abstract int compareTo​(long other)

      Compare the value to a long
      Parameters:
        `other` - the value to be compared with
      Returns:
        -1 if this is less, 0 if this is equal, +1 if this is greater or if this is NaN

    - #### equals

          public final boolean equals​(java.lang.Object other)

      The equals() function compares numeric equality among integers, decimals, floats, doubles, and their subtypes
      Specified by:
        `equals` in class `AtomicValue`
      Parameters:
        `other` - the value to be compared with this one
      Returns:
        true if the two values are numerically equal

    - #### hashCode

          public abstract int hashCode()

      hashCode() must be the same for two values that are equal. One way to ensure this is to convert the value to a double, and take the hashCode of the double. But this is expensive in the common case where we are comparing integers. So we adopt the rule: for values that are in the range of a Java Integer, we use the int value as the hashcode. For values outside that range, we convert to a double and take the hashCode of the double. This method needs to have a compatible implementation in each subclass.
      Overrides:
        `hashCode` in class `java.lang.Object`
      Returns:
        the hash code of the numeric value

    - #### toString

          public java.lang.String toString()

      Produce a string representation of the value
      Overrides:
        `toString` in class `AtomicValue`
      Returns:
        The result of casting the number to a string