Package net.sf.saxon.value

Class NumericValue

java.lang.Object
net.sf.saxon.value.AtomicValue
net.sf.saxon.value.NumericValue
All Implemented Interfaces:
Comparable<XPathComparable>, Iterable<AtomicValue>, AtomicMatchKey, XPathComparable, AtomicSequence, GroundedValue, IdentityComparable, Item, Sequence, ConversionResult
Direct Known Subclasses:
DecimalValue, DoubleValue, FloatValue
public abstract class NumericValue extends AtomicValue implements XPathComparable, AtomicMatchKey
NumericValue is an abstract superclass for IntegerValue, DecimalValue, FloatValue, and DoubleValue

  • Constructor Details

  • Method Details

    • parseNumber

      public static NumericValue parseNumber(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 BigDecimal getDecimalValue() throws ValidationException
      Get the numeric value converted to a decimal. This method implements the casting rules, which may lose some precision.
      Returns:
      a decimal representing this numeric value;
      Throws:
      ValidationException - if the value cannot be converted, for example if it is NaN or infinite

    • getExactDecimalValue

      public BigDecimal getExactDecimalValue() throws ValidationException
      Get the numeric value converted to a decimal. This method gets the exact value as needed for map keys and fn:compare, to give transitive comparison semantics
      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)

    • round

      public abstract NumericValue round(int scale, Round.RoundingRule roundingRule)
      Implement the XPath 2.0 round-half-to-even() and XPath 4.0 round#3 functions
      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
      roundingRule - the rule to be used for rounding (up, down, towards zero, etc)
      Returns:
      a value, of the same type as the original, rounded to a multiple of 10^(-scale), according to the rounding rules requested

    • 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

    • getXPathMatchKey

      public final AtomicMatchKey getXPathMatchKey(StringCollator collator, int implicitTimezone, int specVersion)
      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 in 3.1, but not in 4.0.
      Specified by:
      getXPathMatchKey in class AtomicValue
      Parameters:
      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
      specVersion - the XPath specification version
      Returns:
      a match key that implements the comparison semantics

    • asMapKey

      public abstract AtomicMatchKey asMapKey(int specVersion)
      Get a value whose equals() and hashcode() methods follows the "same key" rules for comparing the keys of a map. For numeric values, this is done as follows:
      • For NaN, return AtomicSortComparer.COLLATION_KEY_NaN;
      • For +INF and -INF, call java.lang.Double.hashcode()
      • For any value that is numerically equal to some 32-bit signed integer, return a Int32MapKey
      • For any other value, return a BigDecimalMapKey
      Overrides:
      asMapKey in class AtomicValue
      Returns:
      a value with the property that the equals() and hashcode() methods follow the rules for comparing keys in maps.

    • getXPathComparable

      public XPathComparable getXPathComparable(StringCollator collator, int implicitTimezone, int specVersion) throws NoDynamicContextException
      Description copied from class: AtomicValue
      Get an object value that implements the XPath equality and ordering comparison semantics for this value. A collation is supplied for comparing strings, and an implicit timezone for comparing date/time values that have no saved timezone. An atomic value may return itself as the result, provided that its ordering rules are independent of the collation and timezone, and provided that it implements the XPathComparable interface: which means that its compareTo, equals, and hashCode methods must be compatible with the rules for XPath value comparisons.
      Specified by:
      getXPathComparable in class AtomicValue
      Parameters:
      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
      specVersion - the version of the XPath specification (31 for 3.1, 40 for 4.0)
      Returns:
      an Object that implements the XPath value comparison semantics with respect to this atomic value. For an atomic type that is not ordered (according to XPath rules), return null.
      Throws:
      NoDynamicContextException - if the supplied implicit timezone is "NO_TIMEZONE" (meaning unknown), and the implicit timezone is actually required because the value in question is a date/time value with no timezone. This can cause a failure to evaluate expressions statically (because the implicit timezone is not known statically), and it will then be caught, meaning that the expression has to be evaluated dynamically.

    • compareTo

      public int compareTo(XPathComparable other)
      Compare the value to another numeric value
      Specified by:
      compareTo in interface Comparable<XPathComparable>
      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:
      ClassCastException - if the other value is not a NumericValue (the parameter is declared as Object to satisfy the Comparable interface)

    • transitiveCompareTo

      public abstract int transitiveCompareTo(NumericValue other)
      Comparison method using transitive semantics (for 4.0). When comparing mixed data types, doubles and floats are converted to an exact decimal.

      Where NaN values are involved, they should be handled by the caller before invoking this method.

      Parameters:
      other - the other comparand
      Returns:
      -1, 0, or +1 depending on the magnitude relationship.

    • 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(Object other)
      The equals() function compares numeric equality among integers, decimals, floats, doubles, and their subtypes.
      Overrides:
      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.

      Note that this method is not used (in general) when comparing keys in maps. When we build a map, we use asMapKey(int) to generate a key for comparison purposes; in the case of numeric values this will in most cases be either a Int32MapKey or a BigDecimalMapKey.

      Overrides:
      hashCode in class AtomicValue
      Returns:
      the hash code of the numeric value

    • show

      public String show()
      Produce a string representation of the value
      Overrides:
      show in class AtomicValue
      Returns:
      The result of casting the number to a string