Package net.sf.saxon.s9api

## Class XdmAtomicValue

- java.lang.Object
- - net.sf.saxon.s9api.XdmValue
  - - net.sf.saxon.s9api.XdmItem
    - - net.sf.saxon.s9api.XdmAtomicValue

- All Implemented Interfaces:
    `java.lang.Iterable<XdmItem>`

      public class XdmAtomicValue
      extends XdmItem

  The class XdmAtomicValue represents an item in an XPath 2.0 sequence that is an atomic value. The value may belong to any of the 19 primitive types defined in XML Schema, or to a type derived from these primitive types, or the XPath 2.0 type xs:untypedAtomic. The type may be either a built-in type or a user-defined type.

  An `XdmAtomicValue` is immutable.

- - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `` | `XdmAtomicValue​(boolean value)` | Create an `xs:boolean` atomic value
    `` | `XdmAtomicValue​(byte value)` | Create an `xs:short` atomic value
    `` | `XdmAtomicValue​(double value)` | Create an `xs:double` atomic value
    `` | `XdmAtomicValue​(float value)` | Create an `xs:float` atomic value
    `` | `XdmAtomicValue​(int value)` | Create an `xs:int` atomic value
    `` | `XdmAtomicValue​(long value)` | Create an `xs:long` atomic value
    `` | `XdmAtomicValue​(short value)` | Create an `xs:short` atomic value
    `` | `XdmAtomicValue​(java.lang.String value)` | Create an `xs:string` atomic value
    `` | `XdmAtomicValue​(java.lang.String lexicalForm, ItemType type)` | Construct an atomic value given its lexical representation and the name of the required built-in atomic type.
    `` | `XdmAtomicValue​(java.math.BigDecimal value)` | Create an `xs:decimal` atomic value
    `` | `XdmAtomicValue​(java.net.URI value)` | Create an `xs:anyURI` atomic value
    `` | `XdmAtomicValue​(java.time.Instant value)` | Create an `xs:dateTime` atomic value from a `Instant`.
    `` | `XdmAtomicValue​(java.time.LocalDate value)` | Create an `xs:date` atomic value from a `LocalDate`.
    `` | `XdmAtomicValue​(java.time.LocalDateTime value)` | Create an `xs:dateTime` atomic value from a `LocalDateTime`.
    `` | `XdmAtomicValue​(java.time.OffsetDateTime value)` | Create an `xs:dateTime` atomic value from a `OffsetDateTime`.
    `` | `XdmAtomicValue​(java.time.ZonedDateTime value)` | Create an `xs:dateTime` atomic value from a `ZonedDateTime`.
    `` | `XdmAtomicValue​(QName value)` | Create an `xs:QName` atomic value
    `protected` | `XdmAtomicValue​(AtomicValue value, boolean flag)` |

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `boolean` | `equals​(java.lang.Object other)` | Compare values for equality.
    `boolean` | `getBooleanValue()` | Get the value converted to a boolean using the XPath casting rules
    `java.math.BigDecimal` | `getDecimalValue()` | Get the value converted to a decimal using the XPath casting rules
    `double` | `getDoubleValue()` | Get the value converted to a double using the XPath casting rules.
    `java.time.Instant` | `getInstant()` | For an XdmAtomicValue representing an xs:dateTime value including timezone, get the value as an instance of `Instant`
    `java.time.LocalDate` | `getLocalDate()` | For an XdmAtomicValue representing an xs:date value, get the value as an instance of `LocalDate`.
    `java.time.LocalDateTime` | `getLocalDateTime()` | For an XdmAtomicValue representing an xs:dateTime value, get the value as an instance of `LocalDateTime`.
    `long` | `getLongValue()` | Get the value converted to an integer using the XPath casting rules
    `java.time.OffsetDateTime` | `getOffsetDateTime()` | For an XdmAtomicValue representing an xs:dateTime value including timezone, get the value as an instance of `OffsetDateTime`
    `QName` | `getPrimitiveTypeName()` | Get the primitive type of this atomic value, as a QName.
    `QName` | `getQNameValue()` | For an XdmAtomicValue representing an xs:QName or xs:NOTATION value, get the value as an instance of QName
    `QName` | `getTypeName()` | Get the type of this atomic value, as a QName.
    `AtomicValue` | `getUnderlyingValue()` | Get the underlying implementation object representing the value.
    `java.lang.Object` | `getValue()` | Get the value as a Java object of the nearest equivalent type.
    `java.time.ZonedDateTime` | `getZonedDateTime()` | For an XdmAtomicValue representing an xs:dateTime value including timezone, get the value as an instance of `ZonedDateTime`
    `int` | `hashCode()` | Get a hashcode that reflects the rules for equality matching
    `static XdmAtomicValue` | `makeAtomicValue​(java.lang.Object value)` | Attempt conversion from an arbitrary Java object
    `java.lang.String` | `toString()` | Get the result of converting the atomic value to a string.

    - ### Methods inherited from class net.sf.saxon.s9api.XdmItem

      `asMap, getStringValue, isAtomicValue, isNode, matches, size, stream, wrapItem, wrapItem, wrapItem`

    - ### Methods inherited from class net.sf.saxon.s9api.XdmValue

      `append, documentOrder, fromGroundedValue, isEmpty, itemAt, iterator, makeSequence, makeValue, select, setValue, wrap, wrap`

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

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

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

      `forEach, spliterator`

- - ### Constructor Detail

    - #### XdmAtomicValue

          protected XdmAtomicValue​(AtomicValue value,
                                   boolean flag)

    - #### XdmAtomicValue

          public XdmAtomicValue​(boolean value)

      Create an `xs:boolean` atomic value
      Parameters:
        `value` - the boolean value, true or false

    - #### XdmAtomicValue

          public XdmAtomicValue​(long value)

      Create an `xs:long` atomic value
      Parameters:
        `value` - the `xs:integer` value, as a long

    - #### XdmAtomicValue

          public XdmAtomicValue​(int value)

      Create an `xs:int` atomic value
      Parameters:
        `value` - the `xs:integer` value, as a long

    - #### XdmAtomicValue

          public XdmAtomicValue​(short value)

      Create an `xs:short` atomic value
      Parameters:
        `value` - the `xs:integer` value, as a long

    - #### XdmAtomicValue

          public XdmAtomicValue​(byte value)

      Create an `xs:short` atomic value
      Parameters:
        `value` - the `xs:integer` value, as a long

    - #### XdmAtomicValue

          public XdmAtomicValue​(java.math.BigDecimal value)

      Create an `xs:decimal` atomic value
      Parameters:
        `value` - the `xs:decimal` value, as a BigDecimal

    - #### XdmAtomicValue

          public XdmAtomicValue​(double value)

      Create an `xs:double` atomic value
      Parameters:
        `value` - the `xs:double` value, as a double

    - #### XdmAtomicValue

          public XdmAtomicValue​(float value)

      Create an `xs:float` atomic value
      Parameters:
        `value` - the `xs:float` value, as a float

    - #### XdmAtomicValue

          public XdmAtomicValue​(java.lang.String value)

      Create an `xs:string` atomic value
      Parameters:
        `value` - the `xs:string` value, as a string

    - #### XdmAtomicValue

          public XdmAtomicValue​(java.net.URI value)

      Create an `xs:anyURI` atomic value
      Parameters:
        `value` - the `xs:anyURI` value, as a URI

    - #### XdmAtomicValue

          public XdmAtomicValue​(QName value)

      Create an `xs:QName` atomic value
      Parameters:
        `value` - the `xs:QName` value, as a QName

    - #### XdmAtomicValue

          public XdmAtomicValue​(java.time.Instant value)

      Create an `xs:dateTime` atomic value from a `Instant`. The resulting value will always have a timezone component.
      Parameters:
        `value` - the `xs:dateTime` value in the form of a `Instant`
      Since:
        10.0

    - #### XdmAtomicValue

          public XdmAtomicValue​(java.time.ZonedDateTime value)

      Create an `xs:dateTime` atomic value from a `ZonedDateTime`. The resulting value will always have a timezone component. Note that the timezone offset (e.g. -05:00) is retained, but the civil time zone identity (e.g. America/New_York) is lost.
      Parameters:
        `value` - the `xs:dateTime` value in the form of a `ZonedDateTime`
      Since:
        10.0

    - #### XdmAtomicValue

          public XdmAtomicValue​(java.time.OffsetDateTime value)

      Create an `xs:dateTime` atomic value from a `OffsetDateTime`. The resulting value will always have a timezone component. The timezone offset (e.g. -05:00) is retained.
      Parameters:
        `value` - the `xs:dateTime` value in the form of a `OffsetDateTime`
      Since:
        10.0

    - #### XdmAtomicValue

          public XdmAtomicValue​(java.time.LocalDateTime value)

      Create an `xs:dateTime` atomic value from a `LocalDateTime`. The resulting value will have no timezone component.
      Parameters:
        `value` - the `xs:dateTime` value in the form of a `LocalDateTime`
      Since:
        10.0

    - #### XdmAtomicValue

          public XdmAtomicValue​(java.time.LocalDate value)

      Create an `xs:date` atomic value from a `LocalDate`. The resulting value will have no timezone component.
      Parameters:
        `value` - the `xs:dateTime` value in the form of a `LocalDate`
      Since:
        10.0

    - #### XdmAtomicValue

          public XdmAtomicValue​(java.lang.String lexicalForm,
                                ItemType type)
                         throws SaxonApiException

      Construct an atomic value given its lexical representation and the name of the required built-in atomic type.

      This method cannot be used to construct values that are namespace-sensitive (QNames and Notations)

      Parameters:
        `lexicalForm` - the value in the lexical space of the target data type. More strictly, the input value before the actions of the whitespace facet for the target data type are applied.
        `type` - the required atomic type. This must either be one of the built-in atomic types defined in XML Schema, or a user-defined type whose definition appears in a schema that is known to the Processor. It must not be an abstract type.
      Throws:
        `SaxonApiException` - if the type is unknown, or is not atomic, or is namespace-sensitive; or if the value supplied in `lexicalForm` is not in the lexical space of the specified atomic type.

  - ### Method Detail

    - #### makeAtomicValue

          public static XdmAtomicValue makeAtomicValue​(java.lang.Object value)

      Attempt conversion from an arbitrary Java object
      Parameters:
        `value` - the value to convert from. This must either be an instance of `AtomicValue` or `QName`, or one of the basic Java types Boolean, Integer, Long, Short, Character, Byte, String, Double, Float, BigDecimal, BigInteger, URI, ZonedDateTime, LocalDateTime, or LocalDate
      Returns:
        the result of the conversion if successful
      Throws:
        `java.lang.IllegalArgumentException` - if conversion from this kind of Object is not supported
      Since:
        10.0 (extended in 10.0 to handle additional data types ZonedDateTime, LocalDateTime, LocalDate)

    - #### getUnderlyingValue

          public AtomicValue getUnderlyingValue()

      Get the underlying implementation object representing the value. This method allows access to lower-level Saxon functionality, including classes and methods that offer no guarantee of stability across releases.
      Overrides:
        `getUnderlyingValue` in class `XdmItem`
      Returns:
        the underlying implementation object representing the value
      Since:
        9.8 (previously inherited from XdmValue which returns a Sequence)

    - #### toString

          public java.lang.String toString()

      Get the result of converting the atomic value to a string. This has the same effect as the XPath string() function.
      Overrides:
        `toString` in class `XdmValue`
      Returns:
        a string representation of the value

    - #### getPrimitiveTypeName

          public QName getPrimitiveTypeName()

      Get the primitive type of this atomic value, as a QName. The primitive types for this purpose are the 19 primitive types of XML Schema, plus xs:integer, xs:dayTimeDuration and xs:yearMonthDuration, and xs:untypedAtomic. For external objects, the result is xs:anyAtomicType.
      Returns:
        a QName naming the primitive type of this atomic value. This will always be an atomic type.

    - #### getTypeName

          public QName getTypeName()

      Get the type of this atomic value, as a QName.
      Returns:
        a QName naming the type of this atomic value. This will always be an atomic type.

    - #### getValue

          public java.lang.Object getValue()

      Get the value as a Java object of the nearest equivalent type.

      The result type is as follows:

      XPath types and corresponding Java classes
      XPath type | Java class
      --- | ---
      xs:string | String
      xs:integer | java.math.BigInteger
      xs:decimal | java.math.BigDecimal
      xs:double | Double
      xs:float | Float
      xs:boolean | Boolean
      xs:QName | QName
      xs:anyURI | String
      xs:dateTime | ZonedDateTime or LocalDateTime (depending whether a timezone is present)
      xs:date | LocalDate (dropping any timezone)
      xs:untypedAtomic | String
      Other types | currently String, but this may change in the future

      Returns:
        the value, converted to a Java object of a suitable type
      Since:
        10.0 (added additional return types for xs:dateTime and xs:date)

    - #### getBooleanValue

          public boolean getBooleanValue()
                                  throws SaxonApiException

      Get the value converted to a boolean using the XPath casting rules
      Returns:
        the result of converting to a boolean (Note: this is not the same as the effective boolean value).
      Throws:
        `SaxonApiException` - if the value cannot be cast to a boolean

    - #### getLongValue

          public long getLongValue()
                            throws SaxonApiException

      Get the value converted to an integer using the XPath casting rules
      Returns:
        the result of converting to an integer
      Throws:
        `SaxonApiException` - if the value cannot be cast to an integer

    - #### getDoubleValue

          public double getDoubleValue()
                                throws SaxonApiException

      Get the value converted to a double using the XPath casting rules.

      If the value is a string, the XSD 1.1 rules are used, which means that the string "+INF" is recognised.

      Returns:
        the result of converting to a double
      Throws:
        `SaxonApiException` - if the value cannot be cast to a double

    - #### getDecimalValue

          public java.math.BigDecimal getDecimalValue()
                                               throws SaxonApiException

      Get the value converted to a decimal using the XPath casting rules
      Returns:
        the result of converting to a decimal
      Throws:
        `SaxonApiException` - if the value cannot be cast to a double

    - #### getQNameValue

          public QName getQNameValue()

      For an XdmAtomicValue representing an xs:QName or xs:NOTATION value, get the value as an instance of QName
      Returns:
        the corresponding QName if the value is an xs:QName or xs:NOTATION, or null otherwise

    - #### getInstant

          public java.time.Instant getInstant()

      For an XdmAtomicValue representing an xs:dateTime value including timezone, get the value as an instance of `Instant`
      Returns:
        the corresponding Instant if the value is an xs:dateTime including a timezone; otherwise null
      Since:
        10.0

    - #### getZonedDateTime

          public java.time.ZonedDateTime getZonedDateTime()

      For an XdmAtomicValue representing an xs:dateTime value including timezone, get the value as an instance of `ZonedDateTime`
      Returns:
        the corresponding ZonedDateTime if the value is an xs:dateTime including a timezone; otherwise null
      Since:
        10.0

    - #### getOffsetDateTime

          public java.time.OffsetDateTime getOffsetDateTime()

      For an XdmAtomicValue representing an xs:dateTime value including timezone, get the value as an instance of `OffsetDateTime`
      Returns:
        the corresponding OffsetDateTime if the value is an xs:dateTime including a timezone; otherwise null
      Since:
        10.0

    - #### getLocalDateTime

          public java.time.LocalDateTime getLocalDateTime()

      For an XdmAtomicValue representing an xs:dateTime value, get the value as an instance of `LocalDateTime`. Any timezone information in the value is discarded
      Returns:
        the corresponding LocalDateTime if the value is an xs:dateTime; otherwise null
      Since:
        10.0

    - #### getLocalDate

          public java.time.LocalDate getLocalDate()

      For an XdmAtomicValue representing an xs:date value, get the value as an instance of `LocalDate`. Any timezone information in the value is discarded
      Returns:
        the corresponding LocalDate if the value is an xs:date; otherwise null
      Since:
        10.0

    - #### equals

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

      Compare values for equality. Two atomic values are considered equal if they are equal according to the rules of the op:is-same-key() operation, used when comparing keys in maps
      Overrides:
        `equals` in class `java.lang.Object`
      Parameters:
        `other` - the value to be compared
      Returns:
        true if the values are deemed equal

    - #### hashCode

          public int hashCode()

      Get a hashcode that reflects the rules for equality matching
      Overrides:
        `hashCode` in class `java.lang.Object`
      Returns:
        a suitable hashcode