XPath/XQuery Functions: Date and Time
Altova's date/time extension functions can be used in XPath and XQuery expressions and provide additional functionality for the processing of data held as XML Schema's various date and time datatypes.
Note about naming of functions and language applicability
Altova extension functions can be used in XPath/XQuery expressions. They provide additional functionality to the functionality that is available in the standard library of XPath, XQuery, and XSLT functions. •In order to distinguish Altova extension functions from functions in the standard library, Altova extension functions are named in this documentation with a suffix of [altova:]. For example: add-years-to-date [altova:]. •When using Altova extension functions in your XPath/XQuery expressions, however, you must use the function without any prefix or suffix, just as you would use any standard XPath/XQuery function. Use an Altova extension like this: add-years-to-date(xs:date("2014-01-15"), 10).
|
altova:add-minutes-to-dateTime altova:add-seconds-to-dateTime altova:dateTime-from-epoch-no-TZ altova:hours-from-dateTimeDuration-accumulated altova:minutes-from-dateTimeDuration-accumulated |
[ Top ]
Add a duration to xs:dateTime XP3.1 XQ3.1
These functions add a duration to xs:dateTime and return xs:dateTime. The xs:dateTime type has a format of CCYY-MM-DDThh:mm:ss.sss. This is a concatenation of the xs:date and xs:time formats separated by the letter T. A timezone suffix (+01:00, for example) is optional.
add-years-to-dateTime(DateTime as xs:dateTime, Years as xs:integer) as xs:dateTime XP3.1 XQ3.1 Adds a duration in years to an xs:dateTime (see examples below). The second argument is the number of years to be added to the xs:dateTime supplied as the first argument. The result is of type xs:dateTime.
|
add-months-to-dateTime(DateTime as xs:dateTime, Months as xs:integer) as xs:dateTime XP3.1 XQ3.1 Adds a duration in months to an xs:dateTime (see examples below). The second argument is the number of months to be added to the xs:dateTime supplied as the first argument. The result is of type xs:dateTime.
|
add-days-to-dateTime(DateTime as xs:dateTime, Days as xs:integer) as xs:dateTime XP3.1 XQ3.1 Adds a duration in days to an xs:dateTime (see examples below). The second argument is the number of days to be added to the xs:dateTime supplied as the first argument. The result is of type xs:dateTime.
|
add-hours-to-dateTime(DateTime as xs:dateTime, Hours as xs:integer) as xs:dateTime XP3.1 XQ3.1 Adds a duration in hours to an xs:dateTime (see examples below). The second argument is the number of hours to be added to the xs:dateTime supplied as the first argument. The result is of type xs:dateTime.
|
add-minutes-to-dateTime(DateTime as xs:dateTime, Minutes as xs:integer) as xs:dateTime XP3.1 XQ3.1 Adds a duration in minutes to an xs:dateTime (see examples below). The second argument is the number of minutes to be added to the xs:dateTime supplied as the first argument. The result is of type xs:dateTime.
|
add-seconds-to-dateTime(DateTime as xs:dateTime, Seconds as xs:integer) as xs:dateTime XP3.1 XQ3.1 Adds a duration in seconds to an xs:dateTime (see examples below). The second argument is the number of seconds to be added to the xs:dateTime supplied as the first argument. The result is of type xs:dateTime.
|
[ Top ]
Add a duration to xs:date XP3.1 XQ3.1
These functions add a duration to xs:date and return xs:date. The xs:date type has a format of CCYY-MM-DD.
add-years-to-date(Date as xs:date, Years as xs:integer) as xs:date XP3.1 XQ3.1 Adds a duration in years to a date. The second argument is the number of years to be added to the xs:date supplied as the first argument. The result is of type xs:date.
|
add-months-to-date(Date as xs:date, Months as xs:integer) as xs:date XP3.1 XQ3.1 Adds a duration in months to a date. The second argument is the number of months to be added to the xs:date supplied as the first argument. The result is of type xs:date.
|
add-days-to-date(Date as xs:date, Days as xs:integer) as xs:date XP3.1 XQ3.1 Adds a duration in days to a date. The second argument is the number of days to be added to the xs:date supplied as the first argument. The result is of type xs:date.
|
[ Top ]
Format and retrieve durations XP3.1 XQ3.1
These functions parse an input xs:duration or xs:string and return, respectively, an xs:string or xs:duration.
format-duration(Duration as xs:duration, Picture as xs:string) as xs:string XP3.1 XQ3.1 Formats a duration, which is submitted as the first argument, according to a picture string submitted as the second argument. The output is a text string formatted according to the picture string.
|
parse-duration(InputString as xs:string, Picture as xs:string) as xs:duration XP3.1 XQ3.1 Takes a patterned string as the first argument, and a picture string as the second argument. The input string is parsed on the basis of the picture string, and an xs:duration is returned.
|
[ Top ]
Add a duration to xs:time XP3.1 XQ3.1
These functions add a duration to xs:time and return xs:time. The xs:time type has a lexical form of hh:mm:ss.sss. An optional time zone may be suffixed. The letter Z indicates Coordinated Universal Time (UTC). All other time zones are represented by their difference from UTC in the format +hh:mm, or -hh:mm. If no time zone value is present, it is considered unknown; it is not assumed to be UTC.
add-hours-to-time(Time as xs:time, Hours as xs:integer) as xs:time XP3.1 XQ3.1 Adds a duration in hours to a time. The second argument is the number of hours to be added to the xs:time supplied as the first argument. The result is of type xs:time.
|
add-minutes-to-time(Time as xs:time, Minutes as xs:integer) as xs:time XP3.1 XQ3.1 Adds a duration in minutes to a time. The second argument is the number of minutes to be added to the xs:time supplied as the first argument. The result is of type xs:time.
|
add-seconds-to-time(Time as xs:time, Minutes as xs:integer) as xs:time XP3.1 XQ3.1 Adds a duration in seconds to a time. The second argument is the number of seconds to be added to the xs:time supplied as the first argument. The result is of type xs:time. The Seconds component can be in the range of 0 to 59.999.
|
[ Top ]
Remove the timezone part from date/time datatypes XP3.1 XQ3.1
These functions remove the timezone from the current xs:dateTime, xs:date, or xs:time values, respectively. Note that the difference between xs:dateTime and xs:dateTimeStamp is that in the case of the latter the timezone part is required (while it is optional in the case of the former). So the format of an xs:dateTimeStamp value is: CCYY-MM-DDThh:mm:ss.sss±hh:mm. or CCYY-MM-DDThh:mm:ss.sssZ. If the date and time is read from the system clock as xs:dateTimeStamp, the current-dateTime-no-TZ() function can be used to remove the timezone if so required.
current-date-no-TZ() as xs:date XP3.1 XQ3.1 This function takes no argument. It removes the timezone part of current-date() (which is the current date according to the system clock) and returns an xs:date value.
|
current-dateTime-no-TZ() as xs:dateTime XP3.1 XQ3.1 This function takes no argument. It removes the timezone part of current-dateTime() (which is the current date-and-time according to the system clock) and returns an xs:dateTime value.
|
current-time-no-TZ() as xs:time XP3.1 XQ3.1 This function takes no argument. It removes the timezone part of current-time() (which is the current time according to the system clock) and returns an xs:time value.
|
date-no-TZ(InputDate as xs:date) as xs:date XP3.1 XQ3.1 This function takes an xs:date argument, removes the timezone part from it, and returns an xs:date value. Note that the date is not modified.
|
dateTime-no-TZ(InputDateTime as xs:dateTime) as xs:dateTime XP3.1 XQ3.1 This function takes an xs:dateTime argument, removes the timezone part from it, and returns an xs:dateTime value. Note that neither the date nor the time is modified.
|
time-no-TZ(InputTime as xs:time) as xs:time XP3.1 XQ3.1 This function takes an xs:time argument, removes the timezone part from it, and returns an xs:time value. Note that the time is not modified.
|
[ Top ]
Return the number of days, hours, minutes, seconds from durations XP3.1 XQ3.1
These functions return the number of days in a month, and the number of hours, minutes, and seconds, respectively, from durations.
days-in-month(Year as xs:integer, Month as xs:integer) as xs:integer XP3.1 XQ3.1 Returns the number of days in the specified month. The month is specified by means of the Year and Month arguments.
|
hours-from-dayTimeDuration-accumulated(DayAndTime as xs:duration) as xs:integer XP3.1 XQ3.1 Returns the total number of hours in the duration submitted by the DayAndTime argument (which is of type xs:duration). The hours in the Day and Time components are added together to give a result that is an integer. A new hour is counted only for a full 60 minutes. Negative durations result in a negative hour value.
|
minutes-from-dayTimeDuration-accumulated(DayAndTime as xs:duration) as xs:integer XP3.1 XQ3.1 Returns the total number of minutes in the duration submitted by the DayAndTime argument (which is of type xs:duration). The minutes in the Day and Time components are added together to give a result that is an integer. Negative durations result in a negative minute value.
|
seconds-from-dayTimeDuration-accumulated(DayAndTime as xs:duration) as xs:integer XP3.1 XQ3.1 Returns the total number of seconds in the duration submitted by the DayAndTime argument (which is of type xs:duration). The seconds in the Day and Time components are added together to give a result that is an integer. Negative durations result in a negative seconds value.
|
Return the weekday from xs:dateTime or xs:date XP3.1 XQ3.1
These functions return the weekday (as an integer) from xs:dateTime or xs:date. The days of the week are numbered (using the American format) from 1 to 7, with Sunday=1. In the European format, the week starts with Monday (=1). The American format, where Sunday=1, can be set by using the integer 0 where an integer is accepted to indicate the format.
weekday-from-dateTime(DateTime as xs:dateTime) as xs:integer XP3.1 XQ3.1 Takes a date-with-time as its single argument and returns the day of the week of this date as an integer. The weekdays are numbered starting with Sunday=1. If the European format is required (where Monday=1), use the other signature of this function (see next signature below).
weekday-from-dateTime(DateTime as xs:dateTime, Format as xs:integer) as xs:integer XP3.1 XQ3.1 Takes a date-with-time as its first argument and returns the day of the week of this date as an integer. If the second (integer) argument is 0, then the weekdays are numbered 1 to 7 starting with Sunday=1. If the second argument is an integer other than 0, then Monday=1. If there is no second argument, the function is read as having the other signature of this function (see previous signature).
|
weekday-from-date(Date as xs:date) as xs:integer XP3.1 XQ3.1 Takes a date as its single argument and returns the day of the week of this date as an integer. The weekdays are numbered starting with Sunday=1. If the European format is required (where Monday=1), use the other signature of this function (see next signature below).
weekday-from-date(Date as xs:date, Format as xs:integer) as xs:integer XP3.1 XQ3.1 Takes a date as its first argument and returns the day of the week of this date as an integer. If the second (Format) argument is 0, then the weekdays are numbered 1 to 7 starting with Sunday=1. If the second argument is an integer other than 0, then Monday=1. If there is no second argument, the function is read as having the other signature of this function (see previous signature).
|
[ Top ]
Return the week number from xs:dateTime or xs:date XP2 XQ1 XP3.1 XQ3.1
These functions return the week number (as an integer) from xs:dateTime or xs:date. Week-numbering is available in the US, ISO/European, and Islamic calendar formats. Week-numbering is different in these calendar formats because the week is considered to start on different days (on Sunday in the US format, Monday in the ISO/European format, and Saturday in the Islamic format).
weeknumber-from-date(Date as xs:date, Calendar as xs:integer) as xs:integer XP2 XQ1 XP3.1 XQ3.1 Returns the week number of the submitted Date argument as an integer. The second argument (Calendar) specifies the calendar system to follow. Supported Calendar values are:
• 0 = US calendar (week starts Sunday) • 1 = ISO standard, European calendar (week starts Monday) • 2 = Islamic calendar (week starts Saturday)
Default is 0.
|
weeknumber-from-dateTime(DateTime as xs:dateTime, Calendar as xs:integer) as xs:integer XP2 XQ1 XP3.1 XQ3.1 Returns the week number of the submitted DateTime argument as an integer. The second argument (Calendar) specifies the calendar system to follow. Supported Calendar values are:
• 0 = US calendar (week starts Sunday) • 1 = ISO standard, European calendar (week starts Monday) • 2 = Islamic calendar (week starts Saturday)
Default is 0.
|
[ Top ]
Build date, time, and duration datatypes from their lexical components XP3.1 XQ3.1
The functions take the lexical components of the xs:date, xs:time, or xs:duration datatype as input arguments and combine them to build the respective datatype.
build-date(Year as xs:integer, Month as xs:integer, Date as xs:integer) as xs:date XP3.1 XQ3.1 The first, second, and third arguments are, respectively, the year, month, and date. They are combined to build a value of xs:date type. The values of the integers must be within the correct range of that particular date part. For example, the second argument (for the month part) should not be greater than 12.
|
build-time(Hours as xs:integer, Minutes as xs:integer, Seconds as xs:integer) as xs:time XP3.1 XQ3.1 The first, second, and third arguments are, respectively, the hour (0 to 23), minutes (0 to 59), and seconds (0 to 59) values. They are combined to build a value of xs:time type. The values of the integers must be within the correct range of that particular time part. For example, the second (Minutes) argument should not be greater than 59. To add a timezone part to the value, use the other signature of this function (see next signature).
build-time(Hours as xs:integer, Minutes as xs:integer, Seconds as xs:integer, TimeZone as xs:string) as xs:time XP3.1 XQ3.1 The first, second, and third arguments are, respectively, the hour (0 to 23), minutes (0 to 59), and seconds (0 to 59) values. The fourth argument is a string that provides the timezone part of the value. The four arguments are combined to build a value of xs:time type. The values of the integers must be within the correct range of that particular time part. For example, the second (Minutes) argument should not be greater than 59.
|
build-duration(Years as xs:integer, Months as xs:integer) as xs:yearMonthDuration XP3.1 XQ3.1 Takes two arguments to build a value of type xs:yearMonthDuration. The first argument provides the Years part of the duration value, while the second argument provides the Months part. If the second (Months) argument is greater than or equal to 12, then the integer is divided by 12; the quotient is added to the first argument to provide the Years part of the duration value while the remainder (of the division) provides the Months part. To build a duration of type xs:dayTimeDuration., see the next signature.
build-duration(Days as xs:integer, Hours as xs:integer, Minutes as xs:integer, Seconds as xs:integer) as xs:dayTimeDuration XP3.1 XQ3.1 Takes four arguments and combines them to build a value of type xs:dayTimeDuration. The first argument provides the Days part of the duration value, the second, third, and fourth arguments provide, respectively, the Hours, Minutes, and Seconds parts of the duration value. Each of the three Time arguments is converted to an equivalent value in terms of the next higher unit and the result is used for calculation of the total duration value. For example, 72 seconds is converted to 1M+12S (1 minute and 12 seconds), and this value is used for calculation of the total duration value. To build a duration of type xs:yearMonthDuration., see the previous signature.
|
[ Top ]
Construct date, dateTime, and time datatypes from string input XP2 XQ1 XP3.1 XQ3.1
These functions take strings as arguments and construct xs:date, xs:dateTime, or xs:time datatypes. The string is analyzed for components of the datatype based on a submitted pattern argument.
parse-date(Date as xs:string, DatePattern as xs:string) as xs:date XP2 XQ1 XP3.1 XQ3.1 Returns the input string Date as an xs:date value. The second argument DatePattern specifies the pattern (sequence of components) of the input string. DatePattern is described with the component specifiers listed below and with component separators that can be any character. See the examples below.
The pattern in DatePattern must match the pattern in Date. Since the output is of type xs:date, the output will always have the lexical format YYYY-MM-DD.
|
parse-dateTime(DateTime as xs:string, DateTimePattern as xs:string) as xs:dateTime XP2 XQ1 XP3.1 XQ3.1 Returns the input string DateTime as an xs:dateTime value.The second argument DateTimePattern specifies the pattern (sequence of components) of the input string. DateTimePattern is described with the component specifiers listed below and with component separators that can be any character. See the examples below.
The pattern in DateTimePattern must match the pattern in DateTime. Since the output is of type xs:dateTime, the output will always have the lexical format YYYY-MM-DDTHH:mm:ss.
|
parse-time(Time as xs:string, TimePattern as xs:string) as xs:time XP2 XQ1 XP3.1 XQ3.1 Returns the input string Time as an xs:time value.The second argument TimePattern specifies the pattern (sequence of components) of the input string. TimePattern is described with the component specifiers listed below and with component separators that can be any character. See the examples below.
The pattern in TimePattern must match the pattern in Time. Since the output is of type xs:time, the output will always have the lexical format HH:mm:ss.
|
[ Top ]
Age-related functions XP3.1 XQ3.1
These functions return the age as calculated (i) between one input argument date and the current date, or (ii) between two input argument dates. The altova:age function returns the age in terms of years, the altova:age-details function returns the age as a sequence of three integers giving the years, months, and days of the age.
age(StartDate as xs:date) as xs:integer XP3.1 XQ3.1 Returns an integer that is the age in years of some object, counting from a start-date submitted as the argument and ending with the current date (taken from the system clock). If the input argument is a date anything greater than or equal to one year in the future, the return value will be negative.
age(StartDate as xs:date, EndDate as xs:date) as xs:integer XP3.1 XQ3.1 Returns an integer that is the age in years of some object, counting from a start-date that is submitted as the first argument up to an end-date that is the second argument. The return value will be negative if the first argument is one year or more later than the second argument.
|
age-details(InputDate as xs:date) as (xs:integer)* XP3.1 XQ3.1 Returns three integers that are, respectively, the years, months, and days between the date that is submitted as the argument and the current date (taken from the system clock). The sum of the returned years+months+days together gives the total time difference between the two dates (the input date and the current date). The input date may have a value earlier or later than the current date, but whether the input date is earlier or later is not indicated by the sign of the return values; the return values are always positive.
age-details(Date-1 as xs:date, Date-2 as xs:date) as (xs:integer)* XP3.1 XQ3.1 Returns three integers that are, respectively, the years, months, and days between the two argument dates. The sum of the returned years+months+days together gives the total time difference between the two input dates; it does not matter whether the earlier or later of the two dates is submitted as the first argument. The return values do not indicate whether the input date occurs earlier or later than the current date. Return values are always positive.
|
[ Top ]
Epoch time (Unix time) functions XP3.1 XQ3.1
Epoch time is a time system used on Unix systems. It defines any given point in time as being the number of seconds that have elapsed since 00:00:00 UTC on 1 January 1970. Altova's Epoch time extension functions convert xs:dateTime values to Epoch time values and vice versa.
dateTime-from-epoch(Epoch as xs:decimal as xs:dateTime XP3.1 XQ3.1 Epoch time is a time system used on Unix systems. It defines any given point in time as being the number of seconds that have elapsed since 00:00:00 UTC on 1 January 1970. The dateTime-from-epoch function returns the xs:dateTime equivalent of an Epoch time, adjusts it for the local timezone, and includes the timezone information in the result.
The function takes an xs:decimal argument and returns an xs:dateTime value that includes a TZ (timezone) part. The result is obtained by calculating the UTC dateTime equivalet of the Epoch time, and adding to it the local timezone (taken from the system clock). For example, if the function is executed on a machine that has been set to be in a timezone of +01:00 (relative to UTC), then after the UTC dateTime equivalent has been calculated, one hour will be added to the result. The timezone information, which is an optional lexical part of the xs:dateTime result, is also reported in the dateTime result. Compare this result with that of dateTime-from-epoch-no-TZ, and also see the function epoch-from-dateTime.
|
dateTime-from-epoch-no-TZ(Epoch as xs:decimal as xs:dateTime XP3.1 XQ3.1 Epoch time is a time system used on Unix systems. It defines any given point in time as being the number of seconds that have elapsed since 00:00:00 UTC on 1 January 1970. The dateTime-from-epoch-no-TZ function returns the xs:dateTime equivalent of an Epoch time, adjusts it for the local timezone, but does not include the timezone information in the result.
The function takes an xs:decimal argument and returns an xs:dateTime value that does not includes a TZ (timezone) part. The result is obtained by calculating the UTC dateTime equivalet of the Epoch time, and adding to it the local timezone (taken from the system clock). For example, if the function is executed on a machine that has been set to be in a timezone of +01:00 (relative to UTC), then after the UTC dateTime equivalent has been calculated, one hour will be added to the result. The timezone information, which is an optional lexical part of the xs:dateTime result, is not reported in the dateTime result. Compare this result with that of dateTime-from-epoch, and also see the function epoch-from-dateTime.
|
epoch-from-dateTime(dateTimeValue as xs:dateTime) as xs:decimal XP3.1 XQ3.1 Epoch time is a time system used on Unix systems. It defines any given point in time as being the number of seconds that have elapsed since 00:00:00 UTC on 1 January 1970. The epoch-from-dateTime function returns the Epoch time equivalent of the xs:dateTime that is submitted as the argument of the function. Note that you might have to explicitly construct the xs:dateTime value. The submitted xs:dateTime value may or may not contain the optional TZ (timezone) part.
Whether the timezone part is submitted as part of the argument or not, the local timezone offset (taken from the system clock) is subtracted from the submitted dateTimeValue argument. This produces the equivalent UTC time, from which the equivalent Epoch time is calculated. For example, if the function is executed on a machine that has been set to be in a timezone of +01:00 (relative to UTC), then one hour is subtracted from the submitted dateTimeValue before the Epoch value is calculated. Also see the function dateTime-from-epoch.
|
[ Top ]