Package net.sf.saxon.value

## Class CalendarValue

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

- All Implemented Interfaces:
    `java.lang.Iterable<AtomicValue>`, `AtomicMatchKey`, `AtomicSequence`, `GroundedValue`, `IdentityComparable`, `Item`, `Sequence`, `ConversionResult`
  Direct Known Subclasses:
    `DateTimeValue`, `GDateValue`, `TimeValue`

      public abstract class CalendarValue
      extends AtomicValue
      implements AtomicMatchKey

  Abstract superclass for Date, Time, and DateTime.

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static int` | `MISSING_TIMEZONE` | The value MISSING_TIMEZONE is returned as the value of implicit-timezone() if the context has no known value for the implicit timezone, which typically arises when early (compile-time) evaluation is attempted.
    `static int` | `NO_TIMEZONE` | The value NO_TIMEZONE is used in a value that has no timezone, and it can be passed as an argument to a comparison operation if a value with no timezone is to be matched.

    - ### 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
    --- | ---
    `CalendarValue()` |

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `abstract CalendarValue` | `add​(DurationValue duration)` | Add a duration to this date/time value
    `abstract CalendarValue` | `adjustTimezone​(int tz)` | Return a new date, time, or dateTime with the same normalized value, but in a different timezone
    `CalendarValue` | `adjustTimezone​(DayTimeDurationValue tz)` | Return a new date, time, or dateTime with the same normalized value, but in a different timezone, specified as a dayTimeDuration
    `static void` | `appendTimezone​(int tz, FastStringBuffer sb)` | Format a timezone and append it to a buffer
    `void` | `appendTimezone​(FastStringBuffer sb)` | Add a string representation of the timezone, typically formatted as "Z" or "+03:00" or "-10:00", to a supplied string buffer
    `AtomicMatchKey` | `asMapKey()` | Get a value whose equals() method follows the "same key" rules for comparing the keys of a map.
    `abstract int` | `compareTo​(CalendarValue other, int implicitTimezone)` | Compare this value to another value of the same type, using the supplied implicit timezone if required.
    `abstract java.util.GregorianCalendar` | `getCalendar()` | Get a Java Calendar object that represents this date/time value.
    `AtomicMatchKey` | `getComparisonKey​(XPathContext context)` | Method retained only because it is used in a test case
    `int` | `getTimezoneInMinutes()` | Get the timezone value held in this object.
    `javax.xml.datatype.XMLGregorianCalendar` | `getXMLGregorianCalendar()` | Get an XMLGregorianCalendar object that represents this date/time value The object will be newly created for the purpose
    `AtomicMatchKey` | `getXPathComparable​(boolean ordered, StringCollator collator, int implicitTimezone)` | Get an object value that implements the XPath equality and ordering comparison semantics for this value.
    `boolean` | `hasTimezone()` | Determine whether this value includes a timezone
    `int` | `identityHashCode()` | Get a hashCode that offers the guarantee that if A.isIdentical(B), then A.identityHashCode() == B.identityHashCode()
    `boolean` | `isIdentical​(AtomicValue v)` | Determine whether two atomic values are identical, as determined by XML Schema rules.
    `static ConversionResult` | `makeCalendarValue​(java.lang.CharSequence s, ConversionRules rules)` | Parse a string to create a CalendarValue whose actual type will depend on the format of the string
    `CalendarValue` | `removeTimezone()` | Return a date, time, or dateTime with the same localized value, but without the timezone component
    `void` | `setTimezoneInMinutes​(int minutes)` | Modify the timezone value held in this object.
    `DayTimeDurationValue` | `subtract​(CalendarValue other, XPathContext context)` | Determine the difference between two points in time, as a duration
    `abstract DateTimeValue` | `toDateTime()` | Convert the value to a DateTime, retaining all the components that are actually present, and substituting conventional values for components that are missing

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

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

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

      `clone, finalize, getClass, hashCode, 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`

- - ### Field Detail

    - #### NO_TIMEZONE

          public static final int NO_TIMEZONE

      The value NO_TIMEZONE is used in a value that has no timezone, and it can be passed as an argument to a comparison operation if a value with no timezone is to be matched.
      See Also:
        Constant Field Values

    - #### MISSING_TIMEZONE

          public static final int MISSING_TIMEZONE

      The value MISSING_TIMEZONE is returned as the value of implicit-timezone() if the context has no known value for the implicit timezone, which typically arises when early (compile-time) evaluation is attempted. This makes it impossible to compare values with a timezone against values with no timezone
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### CalendarValue

          public CalendarValue()

  - ### Method Detail

    - #### makeCalendarValue

          public static ConversionResult makeCalendarValue​(java.lang.CharSequence s,
                                                           ConversionRules rules)

      Parse a string to create a CalendarValue whose actual type will depend on the format of the string
      Parameters:
        `s` - a string in the lexical space of one of the date/time types (date, time, dateTime, gYearMonth, gYear, gMonth, gMonthDay, or gDay
        `rules` -
      Returns:
        either a value of the appropriate type, or a ValidationFailure if the format is invalid

    - #### hasTimezone

          public final boolean hasTimezone()

      Determine whether this value includes a timezone
      Returns:
        true if there is a timezone in the value, false if not

    - #### setTimezoneInMinutes

          public final void setTimezoneInMinutes​(int minutes)

      Modify the timezone value held in this object. This must be done only while the value is being constructed.
      Parameters:
        `minutes` - The timezone offset from GMT in minutes, positive or negative; or the special value NO_TIMEZONE indicating that the value is not in a timezone (this is the default if this method is not called)

    - #### toDateTime

          public abstract DateTimeValue toDateTime()

      Convert the value to a DateTime, retaining all the components that are actually present, and substituting conventional values for components that are missing
      Returns:
        the equivalent DateTimeValue

    - #### getTimezoneInMinutes

          public final int getTimezoneInMinutes()

      Get the timezone value held in this object.
      Returns:
        The timezone offset from GMT in minutes, positive or negative; or the special value NO_TIMEZONE indicating that the value is not in a timezone

    - #### getCalendar

          public abstract java.util.GregorianCalendar getCalendar()

      Get a Java Calendar object that represents this date/time value. The Calendar object will be newly created for the purpose. This will respect the timezone if there is one (provided the timezone is within the range supported by the `GregorianCalendar` class, which in practice means that it is not -14:00). If there is no timezone or if the timezone is out of range, the result will be in GMT.
      Returns:
        A Calendar object representing the date and time. Note that Java can only represent the time to millisecond precision.

    - #### getXMLGregorianCalendar

          public javax.xml.datatype.XMLGregorianCalendar getXMLGregorianCalendar()

      Get an XMLGregorianCalendar object that represents this date/time value The object will be newly created for the purpose
      Returns:
        an XMLGregorianCalendar object representing the data and time; specifically, the components of the date and time that are actually present in this value

    - #### add

          public abstract CalendarValue add​(DurationValue duration)
                                     throws XPathException

      Add a duration to this date/time value
      Parameters:
        `duration` - the duration to be added (which might be negative)
      Returns:
        a new date/time value representing the result of adding the duration. The original object is not modified.
      Throws:
        `XPathException`

    - #### subtract

          public DayTimeDurationValue subtract​(CalendarValue other,
                                               XPathContext context)
                                        throws XPathException

      Determine the difference between two points in time, as a duration
      Parameters:
        `other` - the other point in time
        `context` - the dynamic context, used to obtain timezone information. May be set to null only if both values contain an explicit timezone, or if neither does so.
      Returns:
        the duration as an xs:dayTimeDuration
      Throws:
        `XPathException` - for example if one value is a date and the other is a time

    - #### removeTimezone

          public final CalendarValue removeTimezone()

      Return a date, time, or dateTime with the same localized value, but without the timezone component
      Returns:
        the result of removing the timezone

    - #### adjustTimezone

          public abstract CalendarValue adjustTimezone​(int tz)

      Return a new date, time, or dateTime with the same normalized value, but in a different timezone
      Parameters:
        `tz` - the new timezone offset from UTC, in minutes
      Returns:
        the date/time in the new timezone

    - #### adjustTimezone

          public final CalendarValue adjustTimezone​(DayTimeDurationValue tz)
                                             throws XPathException

      Return a new date, time, or dateTime with the same normalized value, but in a different timezone, specified as a dayTimeDuration
      Parameters:
        `tz` - the new timezone, in minutes
      Returns:
        the date/time in the new timezone
      Throws:
        `XPathException`

    - #### getXPathComparable

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

      Get an object value that implements the XPath equality and ordering comparison semantics for this value. If the ordered parameter is set to true, the result will be a Comparable and will support a compareTo() method with the semantics of the XPath lt/gt operator, provided that the other operand is also obtained using the getXPathComparable() method. In all cases the result will support equals() and hashCode() methods that support the semantics of the XPath eq operator, again provided that the other operand is also obtained using the getXPathComparable() method. A context argument is supplied for use in cases where the comparison semantics are context-sensitive, for example where they depend on the implicit timezone or the default collation.
      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` - collation used for strings
        `implicitTimezone` - the XPath dynamic evaluation context, used in cases where the comparison is context
      Returns:
        an Object whose equals() and hashCode() methods implement the XPath comparison semantics with respect to this atomic value. If ordered is specified, the result will either be null if no ordering is defined, or will be a Comparable
      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.

    - #### getComparisonKey

          public AtomicMatchKey getComparisonKey​(XPathContext context)

      Method retained only because it is used in a test case

    - #### asMapKey

          public AtomicMatchKey asMapKey()

      Get a value whose equals() method follows the "same key" rules for comparing the keys of a map.
      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.

    - #### compareTo

          public abstract int compareTo​(CalendarValue other,
                                        int implicitTimezone)
                                 throws NoDynamicContextException

      Compare this value to another value of the same type, using the supplied implicit timezone if required.
      Parameters:
        `other` - the other value to be compared
        `implicitTimezone` - the implicit timezone as an offset in minutes
      Returns:
        the comparison result
      Throws:
        `NoDynamicContextException` - if the result depends on the implicit timezone and the supplied timezone is `MISSING_TIMEZONE`

    - #### isIdentical

          public boolean isIdentical​(AtomicValue v)

      Description copied from class: `AtomicValue`
      Determine whether two atomic values are identical, as determined by XML Schema rules. This is a stronger test than equality (even schema-equality); for example two dateTime values are not identical unless they are in the same timezone.

      Note that even this check ignores the type annotation of the value. The integer 3 and the short 3 are considered identical, even though they are not fully interchangeable. "Identical" means the same point in the value space, regardless of type annotation.

      NaN is identical to itself.

      Overrides:
        `isIdentical` in class `AtomicValue`
      Parameters:
        `v` - the other value to be compared with this one
      Returns:
        true if the two values are identical, false otherwise.

    - #### identityHashCode

          public int identityHashCode()

      Get a hashCode that offers the guarantee that if A.isIdentical(B), then A.identityHashCode() == B.identityHashCode()
      Specified by:
        `identityHashCode` in interface `IdentityComparable`
      Overrides:
        `identityHashCode` in class `AtomicValue`
      Returns:
        a hashCode suitable for use when testing for identity.

    - #### appendTimezone

          public final void appendTimezone​(FastStringBuffer sb)

      Add a string representation of the timezone, typically formatted as "Z" or "+03:00" or "-10:00", to a supplied string buffer
      Parameters:
        `sb` - The StringBuffer that will be updated with the resulting string representation

    - #### appendTimezone

          public static void appendTimezone​(int tz,
                                            FastStringBuffer sb)

      Format a timezone and append it to a buffer
      Parameters:
        `tz` - the timezone
        `sb` - the buffer