|
Building Queries and Data Views
|
Date and Time Functions
Date and Time functions extract all or part of a dateTime expression and use it in a query. The following date and time functions are available:
xf:add-days
Adds the number of days specified by Parameter2 to the date specified by Parameter1. The value of Parameter2 may be negative.
Data Types
- Parameter1 data type: xs:date?
- Parameter2 data type: xs:decimal?
- Returned data type: xs:date?
Notes
If Parameter1 has a timezone, it remains unchanged. The returned value is always normalized into a correct Gregorian calendar date. If either parameter is an empty list, the function returns an empty list.
XQuery Specification Compliance
Conforms to the current specification.
Examples
- xf:add-days(xf:date("2002-07-15"), -3) returns a date value corresponding to July 12, 2002.
- xf:add-days(xf:date("2002-07-15"), 0) returns a date value corresponding to July 15, 2002.
- xf:add-days(xf:date("2002-07-15"), 2) returns a date value corresponding to July 17, 2002.
- xf:add-days("2002-07-15", 2) generates a compile-time error because the first parameter is a string and not a date value.
xf:current-dateTime
Returns the current date and time.
Data Types
No parameters required.
Returned data type: xs:dateTime
Notes
The function returns the current date and time in the current timezone.
If the function is called multiple times during the execution of a query, it returns the same value each time.
XQuery Specification Compliance
Liquid Data returns the time zone where the Liquid Data Server is running.
Example
xf:current-dateTime() can return a dateTime value such as 2002-07-25T01:00:38.812-08:00, which represents July 25th, 2002 at 1:00:38 and 812 thousandths of a second in a time zone that is offset by -8 hours from GMT (UTC).
xf:date
Returns a date from a source value, which must contain a date in one of these formats:
- YYYY-MM-DD
- YYYY-MM-DDZ
- YYYY-MM-DD+hh:mm
- YYYY-MM-DD-hh:mm
where:
- YYYY represents the year
- MM represents the month (as a number)
- DD represents the day
- Plus (+) or minus (-) is a positive or negative time zone offset
- hh represents the hours
- mm represents the number minutes that the time zone differs from GMT (UTC)
- Z indicates that the time is in the GMT time zone
Data Types
- Input data type: xs:string?
- Returned data type: xs:date?
Notes
The representation for date is the leftmost representation for dateTime: YYYY-MM-DD+hh:mm with an optional following time zone indicator (Z).
Liquid Data supports this year range: 0000-9999.
XQuery Specification Compliance
Conforms to the current specification.
Examples
- xf:date("2002-07-15") returns a date value corresponding to July 15th, 2002 in the current time zone.
- xf:date("2002-07-15-08:00") returns a date value corresponding to July 15th, 2002 in a timezone that is offset by -8 hours from GMT (UTC).
- xf:date("2002-7-15") generates a runtime error because the month is not specified with two digits.
- xf:date("2002-07-15Z") returns a date value corresponding to July 15th, 2002 in the GMT time zone.
- xf:date("2002-02-31") generates a runtime error because the string (02-31) does not represent a valid date.
xfext:date-from-dateTime
Returns the leftmost date portion of a dateTime value.
Data Types
- Input data type: xs:dateTime?
- Returned data type: xs:date?
Notes
This is an extended function. It has an xfext: prefix identifier (namespace), which is the extension to the standard XQuery function namespace (xf:). For more information about extended functions, see Naming Conventions. For more information about valid formats for dateTime, see xf:dateTime.
XQuery Specification Compliance
Liquid Data supports date-from-dateTime as an extended function.
Examples
- xfext:date-from-dateTime(xf:dateTime("2002-07-15T21:09:44")) returns a date value corresponding to July 15th, 2002 in the current time zone.
- xfext:date-from-dateTime(()) returns an empty list ().
xfext:date-from-string-with-format
Returns the right-most date portion of a dateTime value according to the pattern specified by Parameter1. For more information, see Date and Time Patterns.
Data Types
- Parameter1 data type: xs:string?
- Parameter2 data type: xs:string?
- Returned data type: xs:date?
Notes
This is an extended function. It has an xfext: prefix identifier (namespace), which is the extension to the standard XQuery function namespace (xf:). For more information about extended functions, see Naming Conventions.
XQuery Specification Compliance
Liquid Data supports date-from-string-with-format as an extended function.
Examples
- xfext:date-from-string-with-format("yyyy-MM-dd G", "2002-06-22 AD") returns the specified date in the current time zone.
- xfext:date-from-string-with-format("yyyy-MM-dd", "2002-July-22") generates an error because the date string does not match the specified format.
- xfext:date-from-string-with-format("yyyy-MMM-dd", "2002-July-22") returns the specified date in the current time zone.
xf:dateTime
Returns a dateTime value from a source value, which must contain a date and time in one of these formats:
- YYYY-MM-DDThh:mm:ss
- YYYY-MM-DDThh:mm:ssZ
- YYYY-MM-DDThh:mm:ss+hh:mm
- YYYY-MM-DDThh:mm:ss-hh:mm
where the following is true:
- YYYY represents the year
- MM represents the month (as a number)
- DD represents the day
- T is the date and time separator
- hh represents the number of hours
- mm represents the number of minutes
- ss represents the number of seconds
- Plus (+) or minus (-) is a positive or negative time zone offset
- hh represents the hours
- mm represents the number minutes that the time zone differs from GMT (UTC)
- Z indicates that the time is in the GMT time zone
Data Types
- Input data type: xs:string?
- Returned data type: xs:dateTime?
Notes
Returns a date and time in YYYY-MM-DDT+hh:mm:ss format.
This expression can be preceded by an optional leading minus (-) sign to indicate a negative number. If the sign is omitted, positive (+) is assumed.
Use additional digits to increase the precision of fractional seconds if desired. The format ss.ss... with any number of digits after the decimal point is supported. Fractional seconds are optional.
Liquid Data supports this year range: 0000-9999.
XQuery Specification Compliance
Conforms to the current specification.
Examples
- xf:dateTime("2002-07-15T21:09:44") returns a date value corresponding to July 15th, 2002 at 9:09PM and 44 seconds in the current time zone.
- xf:dateTime("2002-07-15T21:09:44.566") returns a date value corresponding to July 15th, 2002 at 9:09PM and 44.566 seconds in the current time zone
- xf:dateTime("2002-07-15T21:09:44-08:00") returns a date value corresponding to July 15th, 2002 at 9:09PM and 44 seconds, in a time zone that is offset by -8 hours from GMT (UTC).
- xf:dateTime("2002-7-15T21:09:44") generates a runtime error because the month is not specified using two digits
- xf:dateTime("2002-07-15T21:09:44Z") returns a date value corresponding to July 15th, 2002 at 9:09PM and 44 seconds, in the GMT timezone
xfext:dateTime-from-string-with-format
Returns a new dateTime value from a string source value according to the pattern specified by Parameter1.
Data Types
- Parameter1 data type: xs:string?
- Parameter2 data type: xs:string?
- Returned data type: xs:dateTime?
Notes
This is an extended function. It has an xfext: prefix identifier (namespace), which is the extension to the standard XQuery function namespace (xf:).
For more information about extended functions, see Naming Conventions, and see Date and Time Patterns.
XQuery Specification Compliance
Liquid Data supports dateTime-from-string-with-format as an extended function.
Examples
- xfext:dateTime-from-string-with-format("yyyy-MM-dd G", "2002-06-22 AD") returns the specified date, 12:00:00AM in the current time zone.
- xfext:dateTime-from-string-with-format("yyyy-MM-dd 'at' hh:mm", "2002-06-22 at 11:04") returns the specified date, 11:04:00AM in the current time zone.
- xfext:dateTime-from-string-with-format("yyyy-MM-dd", "2002-July-22") generates an error because the date string does not match the specified format.
- xfext:dateTime-from-string-with-format("yyyy-MMM-dd", "2002-July-22") returns 12:00:00AM in the current time zone.
xf:get-hours-from-dateTime
Returns an integer value representing the hour identified in dateTime.
Data Types
- Input data type: xs:dateTime?
- Returned data type: xs:integer?
Notes
The hour value ranges from 0 to 23.
If the source value is an empty list, the function returns an empty list.
XQuery Specification Compliance
Conforms to the current specification.
Examples
- xf:get-hours-from-dateTime(xf:dateTime("2002-07-15T21:09:44")) returns the integer value 21.
- xf:get-hours-from-dateTime(()) returns an empty list ().
xf:get-hours-from-time
Returns an integer representing the hour identified in time.
Data Types
- Input data type: xs:time?
- Returned data type: xs:integer?
Notes
The hour value ranges from 0 to 23, inclusive.
If the source value is an empty list, the function returns an empty list.
XQuery Specification Compliance
Conforms to the current specification.
Examples
- xf:get-hours-from-time(xf:time("21:09:44")) returns the integer value 21.
- xf:get-hours-from-time(()) returns an empty list ().
xf:get-minutes-from-dateTime
Returns an integer value representing the minutes identified in dateTime.
Data Types
- Input data type: xs:dateTime?
- Returned data type: xs:integer?
Notes
Returns an integer value representing the minute identified in the source value. The minute value ranges from 0 to 59, inclusive.
If the source value is an empty list, the function returns the empty list.
XQuery Specification Compliance
Conforms to the current specification.
Examples
- xf:get-minutes-from-dateTime(xf:dateTime("2002-07-15T21:09:44")) returns the integer value 9.
- xf:get-minutes-from-dateTime(()) returns an empty list ().
xf:get-minutes-from-time
Returns an integer value representing the minutes identified in time.
Data Types
- Input data type: xs:time?
- Returned data type: xs:integer?
Notes
The minute value ranges from 0 to 59.
If the source value is an empty list, the function returns an empty list.
XQuery Specification Compliance
Conforms to the current specification.
Examples
- xf:get-minutes-from-time(xf:time("21:09:44")) returns the integer value 9.
- xf:get-minutes-from-time(()) returns an empty list ().
xf:get-seconds-from-dateTime
Returns an integer value representing the seconds identified in dateTime.
Data Types
- Input data type: xs:dateTime?
- Returned data type: xs:integer?
Notes
The seconds value ranges from 0 to 60.999. The precision (number of digits) of fractional seconds depends on the relevant facet of the argument.
The value can be greater than 60 seconds to accommodate occasional leap seconds used to keep human time synchronized with the rotation of the planet.
If the source value is an empty list, the function returns an empty list.
XQuery Specification Compliance
Conforms to the current specification.
Examples
- xf:get-seconds-from-dateTime(xf:dateTime("2002-07-15T21:09:44")) returns the integer value 44.
- xf:get-seconds-from-dateTime(()) returns an empty list ().
xf:get-seconds-from-time
Returns an integer value representing the seconds identified in time.
Data Types:
- Input data type: xs:time?
- Returned data type: xs:integer?
Notes
The seconds value ranges from 0 to 60.999. The precision (number of digits) of fractional seconds depends on the relevant facet of the argument.
The value can be greater than 60 seconds to accommodate occasional leap seconds used to keep human time synchronized with the rotation of the planet.
If the source value is an empty list, the function returns an empty list.
XQuery Specification Compliance
Conforms to the current specification.
Examples
- xf:get-seconds-from-time(xf:time("21:09:44")) returns the integer value 44.
- xf:get-seconds-from-time(()) returns an empty list ().
xf:time
Returns a tine from a source value, which must contain the time in one of these formats:
- hh:mm:ss
- hh:mm:ssZ
- hh:mm:ss+hh:mm
- hh:mm:ss-hh:mm
where the following is true:
- hh represents the number of hours
- mm represents the number of minutes
- ss represents the number of seconds
- Plus (+) or minus (-) is a positive or negative time zone offset
- hh represents the number of hours that the time zone differs from GMT (UTC)
- mm represents the number of minutes that the time zone differs from GMT (UTC)
- Z indicates that the time is in the GMT time zone
Data Types
- Input data type: xs:string?
- Returned data type: xs:time?
Notes
Liquid Data generates an error if it cannot parse the string successfully.
XQuery Specification Compliance
Conforms to the current specification.
Examples
- xf:time("22:04:22") returns a time value corresponding to 10:04PM and 22 seconds in the current time zone.
- xf:time("22:04:22.343") returns a time value corresponding to 10:04PM and 22.343 seconds, in the current time zone.
- xf:time("22:04:22-08:00") returns a time value corresponding to 10:04PM and 22 seconds in a time zone that is offset by -8 hours from GMT (UTC).
- xf:time("22:4:22") generates a runtime error because the minutes are not specified with two digits.
- xf:time("22:04:22Z") returns a time value corresponding to 10:04PM and 22 seconds in the GMT time zone.
xfext:time-from-dateTime
Returns the time from dateTime.
Data Types
- Input data type: xs:dateTime?
- Returned data type: xs:time?
Notes
This is an extended function. It has an xfext: prefix identifier (namespace), which is the extension to the standard XQuery function namespace (xf:). For more information about extended functions, see Naming Conventions. For more information about valid formats for dateTime, see xf:dateTime.
XQuery Specification Compliance
Liquid Data supports time-from-dateTime as an extended function.
Examples
- xfext:time-from-dateTime(xf:dateTime("2002-07-15T21:09:44")) returns a date value corresponding to 9:09:44PM in the current time zone.
- xfext:time-from-dateTime(()) returns an empty list ().
xfext:time-from-string-with-format
Returns a new time value from a string source value according to the pattern specified by Parameter1.
Data Types
- Parameter1 data type: xs:string?
- Parameter2 data type: xs:string?
- Returned data type: xs:time?
Notes
This is an extended function. It has an xfext: prefix identifier (namespace), which is the extension to the standard XQuery function namespace (xf:).
For more information about extended functions, see Naming Conventions, and see Date and Time Patterns.
XQuery Specification Compliance
Liquid Data supports time-from-string-with-format as an extended function.
Examples
- xfext:time-from-string-with-format("HH.mm.ss", "21.45.22") returns the time 9:45:22PM in the current time zone.
- xfext:time-from-string-with-format("hh:mm:ss a", "8:07:22 PM") returns the time 8:07:22PM in the current time zone.
- xfext:time-from-string-with-format("hh:mm:ss z", "8:07:22 EST") returns the time 8:07:22AM in the EST time zone.
