net.sf.saxon.value

Class DateTimeValue

public final class DateTimeValue extends CalendarValue

A value of type DateTime
Constructor Summary
DateTimeValue(Calendar calendar, boolean tzSpecified)
Constructor: create a dateTime value given a Java calendar object
DateTimeValue(DateValue date, TimeValue time)
Constructor: create a dateTime value given a date and a time.
DateTimeValue(CharSequence s)
Constructor: create a dateTime value from a supplied string, in ISO 8601 format
DateTimeValue(int year, byte month, byte day, byte hour, byte minute, byte second, int microsecond, int tz)
Constructor: construct a DateTimeValue from its components.
Method Summary
CalendarValueadd(DurationValue duration)
Add a duration to a dateTime
CalendarValueadjustTimezone(int timezone)
Return a new dateTime with the same normalized value, but in a different timezone.
intcompareTo(Object other)
Compare the value to another dateTime value.
intcompareTo(CalendarValue other, XPathContext cc)
Compare the value to another dateTime value, following the XPath comparison semantics
AtomicValueconvertPrimitive(BuiltInAtomicType requiredType, boolean validate, XPathContext context)
Convert to target data type
ObjectconvertToJava(Class target, XPathContext context)
Convert to Java object (for passing to external functions)
CalendarValuecopy()
Make a copy of this date, time, or dateTime value
booleanequals(Object other)
static DateTimeValuefromJulianInstant(BigDecimal instant)
Get the DateTimeValue corresponding to a given Julian instant
GregorianCalendargetCalendar()
Get a Calendar object representing the value of this DateTime.
AtomicValuegetComponent(int component)
Get a component of the value.
static DateTimeValuegetCurrentDateTime(XPathContext context)
Get the dateTime value representing the nominal date/time of this transformation run.
bytegetDay()
Get the day component, 1-31
bytegetHour()
Get the hour component, 0-23
ItemTypegetItemType(TypeHierarchy th)
Determine the data type of the exprssion
intgetMicrosecond()
Get the microsecond component, 0-999999
bytegetMinute()
Get the minute component, 0-59
bytegetMonth()
Get the month component, 1-12
bytegetSecond()
Get the second component, 0-59
CharSequencegetStringValueCS()
Convert to string
intgetYear()
Get the year component, in its internal form (which allows a year zero)
inthashCode()
DateTimeValuenormalize(XPathContext cc)
Normalize the date and time to be in timezone Z.
SecondsDurationValuesubtract(CalendarValue other, XPathContext context)
Determine the difference between two points in time, as a duration
DateTimeValuetoDateTime()
Convert the value to a DateTime, retaining all the components that are actually present, and substituting conventional values for components that are missing
BigDecimaltoJulianInstant()
Get the Julian instant: a decimal value whose integer part is the Julian day number multiplied by the number of seconds per day, and whose fractional part is the fraction of the second.

Constructor Detail

DateTimeValue

public DateTimeValue(Calendar calendar, boolean tzSpecified)
Constructor: create a dateTime value given a Java calendar object

Parameters: calendar holds the date and time tzSpecified indicates whether the timezone is specified

DateTimeValue

public DateTimeValue(DateValue date, TimeValue time)
Constructor: create a dateTime value given a date and a time.

Parameters: date the date time the time

Throws: net.sf.saxon.trans.XPathException if the timezones are both present and inconsistent

DateTimeValue

public DateTimeValue(CharSequence s)
Constructor: create a dateTime value from a supplied string, in ISO 8601 format

DateTimeValue

public DateTimeValue(int year, byte month, byte day, byte hour, byte minute, byte second, int microsecond, int tz)
Constructor: construct a DateTimeValue from its components. This constructor performs no validation.

Parameters: year The year as held internally (note that the year before 1AD is 0) month The month, 1-12 day The day 1-31 hour the hour value, 0-23 minute the minutes value, 0-59 second the seconds value, 0-59 microsecond the number of microseconds, 0-999999 tz the timezone displacement in minutes from UTC. Supply the value CalendarValue.NO_TIMEZONE if there is no timezone component.

Method Detail

add

public CalendarValue add(DurationValue duration)
Add a duration to a dateTime

Parameters: duration the duration to be added (may be negative)

Returns: the new date

Throws: net.sf.saxon.trans.XPathException if the duration is an xs:duration, as distinct from a subclass thereof

adjustTimezone

public CalendarValue adjustTimezone(int timezone)
Return a new dateTime with the same normalized value, but in a different timezone. This is called only for a DateTimeValue that has an explicit timezone

Parameters: timezone the new timezone offset, in minutes

Returns: the date/time in the new timezone. This will be a new DateTimeValue unless no change was required to the original value

compareTo

public int compareTo(Object other)
Compare the value to another dateTime value.

This method is not used for XPath comparisons because it does not have access to the implicitTimezone from the dynamic context. It is available for schema comparisons, although it does not currently implement the XML Schema semantics for timezone comparison (which involve partial ordering)

Parameters: other The other dateTime value

Returns: negative value if this one is the earler, 0 if they are chronologically equal, positive value if this one is the later. For this purpose, dateTime values with an unknown timezone are considered to be values in the implicit timezone (the Comparable interface requires a total ordering).

Throws: ClassCastException if the other value is not a DateTimeValue (the parameter is declared as Object to satisfy the Comparable interface)

compareTo

public int compareTo(CalendarValue other, XPathContext cc)
Compare the value to another dateTime value, following the XPath comparison semantics

Parameters: other The other dateTime value cc A ConversionContext used to supply the implicit timezone

Returns: negative value if this one is the earler, 0 if they are chronologically equal, positive value if this one is the later. For this purpose, dateTime values with an unknown timezone are considered to be values in the implicit timezone (the Comparable interface requires a total ordering).

Throws: ClassCastException if the other value is not a DateTimeValue (the parameter is declared as Object to satisfy the Comparable interface)

convertPrimitive

public AtomicValue convertPrimitive(BuiltInAtomicType requiredType, boolean validate, XPathContext context)
Convert to target data type

Parameters: requiredType an integer identifying the required atomic type context

Returns: an AtomicValue, a value of the required type; or an ErrorValue

convertToJava

public Object convertToJava(Class target, XPathContext context)
Convert to Java object (for passing to external functions)

copy

public CalendarValue copy()
Make a copy of this date, time, or dateTime value

equals

public boolean equals(Object other)

fromJulianInstant

public static DateTimeValue fromJulianInstant(BigDecimal instant)
Get the DateTimeValue corresponding to a given Julian instant

getCalendar

public GregorianCalendar getCalendar()
Get a Calendar object representing the value of this DateTime. This will respect the timezone if there is one, or be in GMT otherwise.

getComponent

public AtomicValue getComponent(int component)
Get a component of the value. Returns null if the timezone component is requested and is not present.

getCurrentDateTime

public static DateTimeValue getCurrentDateTime(XPathContext context)
Get the dateTime value representing the nominal date/time of this transformation run. Two calls within the same query or transformation will always return the same answer.

getDay

public byte getDay()
Get the day component, 1-31

getHour

public byte getHour()
Get the hour component, 0-23

getItemType

public ItemType getItemType(TypeHierarchy th)
Determine the data type of the exprssion

Parameters: th

Returns: Type.DATE_TIME,

getMicrosecond

public int getMicrosecond()
Get the microsecond component, 0-999999

getMinute

public byte getMinute()
Get the minute component, 0-59

getMonth

public byte getMonth()
Get the month component, 1-12

getSecond

public byte getSecond()
Get the second component, 0-59

getStringValueCS

public CharSequence getStringValueCS()
Convert to string

Returns: ISO 8601 representation. The value returned is the localized representation, that is it uses the timezone contained within the value itself.

getYear

public int getYear()
Get the year component, in its internal form (which allows a year zero)

hashCode

public int hashCode()

normalize

public DateTimeValue normalize(XPathContext cc)
Normalize the date and time to be in timezone Z.

Parameters: cc used to supply the implicit timezone, used when the value has no explicit timezone

Returns: in general, a new DateTimeValue in timezone Z, representing the same instant in time. Returns the original DateTimeValue if this is already in timezone Z.

subtract

public SecondsDurationValue subtract(CalendarValue other, XPathContext context)
Determine the difference between two points in time, as a duration

Parameters: other the other point in time context

Returns: the duration as an xdt:dayTimeDuration

Throws: net.sf.saxon.trans.XPathException for example if one value is a date and the other is a time

toDateTime

public 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

toJulianInstant

public BigDecimal toJulianInstant()
Get the Julian instant: a decimal value whose integer part is the Julian day number multiplied by the number of seconds per day, and whose fractional part is the fraction of the second. This method operates on the local time, ignoring the timezone. The caller should call normalize() before calling this method to get a normalized time.