net.sf.saxon.value
Class CalendarValue

java.lang.Object
  extended by net.sf.saxon.value.Value
      extended by net.sf.saxon.value.AtomicValue
          extended by net.sf.saxon.value.CalendarValue
All Implemented Interfaces:
Serializable, PullEvent, SequenceIterable, GroundedValue, Item, ValueRepresentation, ConversionResult
Direct Known Subclasses:
DateTimeValue, GDateValue, TimeValue

public abstract class CalendarValue
extends AtomicValue

Abstract superclass for Date, Time, and DateTime.

See Also:
Serialized Form

Field Summary
static int NO_TIMEZONE
           
 
Fields inherited from class net.sf.saxon.value.AtomicValue
typeLabel
 
Fields inherited from class net.sf.saxon.value.Value
INDETERMINATE_ORDERING
 
Fields inherited from interface net.sf.saxon.om.ValueRepresentation
EMPTY_VALUE_ARRAY
 
Constructor Summary
CalendarValue()
           
 
Method Summary
abstract  CalendarValue add(DurationValue duration)
          Add a duration to this date/time value
 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
abstract  CalendarValue adjustTimezone(int tz)
          Return a new date, time, or dateTime with the same normalized value, but in a different timezone
 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
static void appendTimezone(int tz, FastStringBuffer sb)
          Format a timezone and append it to a buffer
abstract  int compareTo(CalendarValue other, XPathContext context)
          Compare this value to another value of the same type, using the supplied Configuration to get the implicit timezone if required.
abstract  GregorianCalendar getCalendar()
          Get a Java Calendar object that represents this date/time value.
abstract  ComparisonKey getComparisonKey(XPathContext context)
          Get a comparison key for this value.
 int getTimezoneInMinutes()
          Get the timezone value held in this object.
 Object getXPathComparable(boolean ordered, StringCollator collator, XPathContext context)
          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
 boolean isIdentical(Value v)
          Determine whether two atomic values are identical, as determined by XML Schema rules.
static ConversionResult makeCalendarValue(CharSequence s)
          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, checkPermittedContents, convert, convert, convertPrimitive, copyAsSubType, effectiveBooleanValue, equals, getCardinality, getComponent, getItemType, getLength, getPrimitiveStringValue, getPrimitiveType, getSchemaComparable, getStringValue, getStringValueCS, getTypedValue, getTypeLabel, isNaN, itemAt, iterate, process, setTypeLabel, subsequence, toString
 
Methods inherited from class net.sf.saxon.value.Value
asItem, asItem, asIterator, asValue, convertToJava, fromItem, getCanonicalLexicalRepresentation, getIterator, iterate, reduce, stringToNumber
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

NO_TIMEZONE

public static final int NO_TIMEZONE
See Also:
Constant Field Values
Constructor Detail

CalendarValue

public CalendarValue()
Method Detail

makeCalendarValue

public static ConversionResult makeCalendarValue(CharSequence s)
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
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 GregorianCalendar getCalendar()
Get a Java Calendar object that represents this date/time value. The Calendar object will be newly created for the purpose

Returns:
A Calendar object representing the date and time. Note that Java can only represent the time to millisecond precision, and that it does not support the full range of timezones required by XPath (-14:00 to +14:00)

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 Object getXPathComparable(boolean ordered,
                                 StringCollator collator,
                                 XPathContext context)
                          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
context - the XPath dynamic evaluation context, used in cases where the comparison is context sensitive @return 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
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 comparison depends on dynamic context information that is not available, for example implicit timezone

compareTo

public abstract int compareTo(CalendarValue other,
                              XPathContext context)
                       throws NoDynamicContextException
Compare this value to another value of the same type, using the supplied Configuration to get the implicit timezone if required.

Parameters:
other - the other value to be compared
context - the XPath dynamic evaluation context
Returns:
the comparison result
Throws:
NoDynamicContextException - if the supplied context is an early evaluation context and the result depends on the implicit timezone, which is not available at compile time

getComparisonKey

public abstract ComparisonKey getComparisonKey(XPathContext context)
                                        throws NoDynamicContextException
Get a comparison key for this value. Two values are equal if and only if they their comparison keys are equal

Parameters:
context - XPath dynamic evaluation context, used to obtain implicit timezone
Returns:
a comparison key
Throws:
NoDynamicContextException - if the implicit timezone is needed and is not available

isIdentical

public boolean isIdentical(Value 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.

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


Copyright (c) Saxonica Limited. All rights reserved.