Package net.sf.saxon.value

Class CalendarValue

java.lang.Object

net.sf.saxon.value.AtomicValue

net.sf.saxon.value.CalendarValue

All Implemented Interfaces:

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 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.
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.

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

typeLabel

Constructor Summary

Constructors

Constructor	Description
CalendarValue(AtomicType typeLabel)
CalendarValue(AtomicType typeLabel, int tzMinutes)

Method Summary

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
final 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
protected static void	appendString(UnicodeBuilder sb, int value, int size)	Append an integer, formatted with leading zeros to a fixed size, to a string buffer
static void	appendTimezone(int tz, UnicodeBuilder sb)	Format a timezone and append it to a buffer
final void	appendTimezone(UnicodeBuilder sb)	Add a string representation of the timezone, typically formatted as "Z" or "+03:00" or "-10:00", to a supplied string buffer
protected static void	appendTwoDigits(UnicodeBuilder sb, int value)	Append an integer, formatted as two digits, to a 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 GregorianCalendar	getCalendar()	Get a Java Calendar object that represents this date/time value.
final int	getTimezoneInMinutes()	Get the timezone value held in this object.
XMLGregorianCalendar	getXMLGregorianCalendar()	Get an XMLGregorianCalendar object that represents this date/time value The object will be newly created for the purpose
XPathComparable	getXPathComparable(StringCollator collator, int implicitTimezone)	Get an object value that implements the XPath equality and ordering comparison semantics for this value.
AtomicMatchKey	getXPathMatchKey(StringCollator collator, int implicitTimezone)	Get an object value that implements the XPath equality and ordering comparison semantics for this value.
final 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(UnicodeString s, ConversionRules rules)	Parse a string to create a CalendarValue whose actual type will depend on the format of the string
final CalendarValue	removeTimezone()	Return a date, time, or dateTime with the same localized value, but without the timezone component
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, getUnicodeStringValue, getUType, hashCode, head, isIdentical, isNaN, isUntypedAtomic, itemAt, iterate, iterator, show, toShortString, toString

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

getStringValue, isStreamed, reduce, subsequence

Methods inherited from interface java.lang.Iterable

forEach, spliterator

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

makeRepeatable

Field Details

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 Details

CalendarValue

public CalendarValue(AtomicType typeLabel)

CalendarValue

public CalendarValue(AtomicType typeLabel,
 int tzMinutes)

Method Details

makeCalendarValue

public static ConversionResult makeCalendarValue(UnicodeString 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 - conversion rules to apply (affects handling of year 0)

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

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. 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 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 - if an error is detected

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; the value NO_TIMEZONE indicates that any existing timezone should be removed

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 - if an error is detected

getXPathMatchKey

public AtomicMatchKey getXPathMatchKey(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:

getXPathMatchKey in class AtomicValue

Parameters:

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.

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.

getXPathComparable

public XPathComparable getXPathComparable(StringCollator collator,
 int implicitTimezone)
                                   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

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 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(UnicodeBuilder 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,
 UnicodeBuilder sb)

Format a timezone and append it to a buffer

Parameters:

tz - the timezone

sb - the buffer

appendString

protected static void appendString(UnicodeBuilder sb,
 int value,
 int size)

Append an integer, formatted with leading zeros to a fixed size, to a string buffer

Parameters:

sb - the string buffer

value - the integer to be formatted

size - the number of digits required (max 9)

appendTwoDigits

protected static void appendTwoDigits(UnicodeBuilder sb,
 int value)

Append an integer, formatted as two digits, to a string buffer

Parameters:

sb - the string buffer

value - the integer to be formatted (must be in the range 0..99