Date/Time Functions

Functions for date/time parsing and manipulation.

`current-time`

current-time()➡String

Returns the current system date and time in Stroom’s standard date-time format.

Return Value:

Type	Description
String	The current date and time.

`current-unixTime`

current-unixTime()➡Integer

Returns the current system time as milliseconds since the Unix epoch.

Return Value:

Type	Description
Integer	The current time in milliseconds since the Unix epoch.

`format-date`

Parses a date and formats it as a string. A single argument is interpreted as milliseconds since the Unix epoch; other forms parse an input pattern and may specify input and output time zones.

format-date(epochMillis)➡String

Formats milliseconds since the Unix epoch in Stroom’s standard date-time format.

Function Arguments:

Param	Type	Mandatory	Default Value	Allowed Values	Multiple	Min Count	Description
`epochMillis`	Integer		-	-		-	The number of milliseconds since the Unix epoch.

Return Value:

Type	Description
String	The formatted date string, or an empty sequence if parsing or formatting fails.

format-date(inputDate, inputPattern, [inputTimeZone])➡String

Parses a date string and returns Stroom’s standard date-time format.

Function Arguments:

Param	Type	Default Value	Allowed Values	Min Count	Description
`inputDate`	String	-	-	-	The date string to parse.
`inputPattern`	String	-	-	-	The pattern describing the input date.
`inputTimeZone`	String	-	-	-	The input time zone; defaults to UTC. `GMT/BST` handles British Summer Time.

Return Value:

Type	Description
String	The formatted date string, or an empty sequence if parsing or formatting fails.

format-date(inputDate, inputPattern, inputTimeZone, outputPattern, [outputTimeZone])➡String

Parses a date string and formats it with a custom output pattern.

Function Arguments:

Param	Type	Default Value	Allowed Values	Min Count	Description
`inputDate`	String	-	-	-	The date string to parse.
`inputPattern`	String	-	-	-	The pattern describing the input date.
`inputTimeZone`	String	-	-	-	The input time zone; defaults to UTC.
`outputPattern`	String	-	-	-	The pattern for the output string.
`outputTimeZone`	String	-	-	-	The output time zone; defaults to UTC.

Return Value:

Type	Description
String	The formatted date string, or an empty sequence if parsing or formatting fails.

Date Formats

For details of date format syntax, as used by the inputPattern and outputPattern arguments, see Custom Date Formats.

Time Zones

The following is a list of some common time zone values:

Values	Zone Name
`GMT/BST`	A Stroom specific value for UK daylight saving time (see below)
`UTC`, `UCT`, `Zulu`, `Universal`, `+00:00`, `-00:00`, `+00`, `+0`	Coordinated Universal Time (UTC)
`GMT`, `GMT0`, `Greenwich`	Greenwich Mean Time (GMT)
`GB`, `GB-Eire`, `Europe/London`	British Time
`NZ`, `Pacific/Auckland`	New Zealand Time
`Australia/Canberra`, `Australia/Sydney`	Eastern Australia Time
`CET`	Central European Time
`EET`	Eastern European Time
`Canada/Atlantic`	Atlantic Time
`Canada/Central`	Central Time
`Canada/Pacific`	Pacific Time
`US/Central`	Central Time
`US/Eastern`	Eastern Time
`US/Mountain`	Mountain Time
`US/Pacific`	Pacific Time
`+02:00`, `+02`, `+2`	UTC +2hrs
`-03:00`, `-03`, `-3`	UTC -3hrs

A special time zone value of GMT/BST can be used when the inputDate is in local wall clock time with time zone information. In this case, the date/time will be used to determine whether the date is in British Summer Time or in GMT and adjust the output accordingly. See the examples below.

Parsing Examples

The following table shows various examples of calls to stroom:format-date() with their output. The stroom:format-date part has been omitted for brevity.

<!-- Date in millis since UNIX epoch -->
stroom:format-date('1269270011640')
-> '2010-03-22T15:00:11.640Z'

<!-- Simple date UK style date -->
stroom:format-date('29/08/24', 'dd/MM/yy')
-> '2024-08-29T00:00:00.000Z'

<!-- Simple date US style date -->
stroom:format-date('08/29/24', 'MM/dd/yy')
-> '2024-08-29T00:00:00.000Z'

<!-- ISO date with no delimiters -->
stroom:format-date('20010801184559', 'yyyyMMddHHmmss')
-> '2001-08-01T18:45:59.000Z'

<!-- Standard output, no TZ -->
stroom:format-date('2001/08/01 18:45:59', 'yyyy/MM/dd HH:mm:ss')
-> '2001-08-01T18:45:59.000Z'

<!-- Standard output, date only, with TZ -->
stroom:format-date('2001/08/01', 'yyyy/MM/dd', '-07:00')
-> '2001-08-01T07:00:00.000Z'

<!-- Standard output, with TZ -->
stroom:format-date('2001/08/01 01:00:00', 'yyyy/MM/dd HH:mm:ss', '-08:00')
-> '2001-08-01T09:00:00.000Z'

<!-- Standard output, with TZ -->
stroom:format-date('2001/08/01 01:00:00', 'yyyy/MM/dd HH:mm:ss', '+01:00')
-> '2001-08-01T00:00:00.000Z'

<!-- Single digit day and month, no padding -->
stroom:format-date('2001 8 1', 'yyyy MM dd')
-> '2001-08-01T00:00:00.000Z'

<!-- Double digit day and month, no padding -->
stroom:format-date('2001 12 28', 'yyyy MM dd')
-> '2001-12-28T00:00:00.000Z'

<!-- Single digit day and month, with optional padding -->
stroom:format-date('2001  8  1', 'yyyy ppMM ppdd')
-> '2001-08-01T00:00:00.000Z'

<!-- Double digit day and month, with optional padding -->
stroom:format-date('2001 12 31', 'yyyy ppMM ppdd')
-> '2001-12-31T00:00:00.000Z'

<!-- With abbreviated day of week month -->
stroom:format-date('Wed Aug 14 2024', 'EEE MMM dd yyyy')
-> '2024-08-14T00:00:00.000Z'

<!-- With long form day of week and month -->
stroom:format-date('Wednesday August 14 2024', 'EEEE MMMM dd yyyy')
-> '2024-08-14T00:00:00.000Z'

<!-- With 12 hour clock, AM -->
stroom:format-date('Wed Aug 14 2024 10:32:58 AM', 'E MMM dd yyyy hh:mm:ss a')
-> '2024-08-14T10:32:58.000Z'

<!-- With 12 hour clock, PM (lower case) -->
stroom:format-date('Wed Aug 14 2024 10:32:58 pm', 'E MMM dd yyyy hh:mm:ss a')
-> '2024-08-14T22:32:58.000Z'

<!-- Using minimal symbols -->
stroom:format-date('2001 12 31 22:58:32.123', 'y M d H:m:s.S')
-> '2001-12-31T22:58:32.123Z'

<!-- Optional time portion, with time -->
stroom:format-date('2001/12/31 22:58:32.123', 'yyyy/MM/dd[ HH:mm:ss.SSS]')
-> '2001-12-31T22:58:32.123Z'

<!-- Optional time portion, without time -->
stroom:format-date('2001/12/31', 'yyyy/MM/dd[ HH:mm:ss.SSS]')
-> '2001-12-31T00:00:00.000Z'

<!-- Optional millis portion, with millis -->
stroom:format-date('2001/12/31 22:58:32.123', 'yyyy/MM/dd HH:mm:ss[.SSS]')
-> '2001-12-31T22:58:32.123Z'

<!-- Optional millis portion, without millis -->
stroom:format-date('2001/12/31 22:58:32', 'yyyy/MM/dd HH:mm:ss[.SSS]')
-> '2001-12-31T22:58:32.000Z'

<!-- Optional millis/nanos portion, with nanos -->
stroom:format-date('2001/12/31 22:58:32.123456', 'yyyy/MM/dd HH:mm:ss[.SSS]')
-> '2001-12-31T22:58:32.123Z'

<!-- Fixed text -->
stroom:format-date('Date: 2001/12/31 Time: 22:58:32.123', ''Date: 'yyyy/MM/dd 'Time: 'HH:mm:ss.SSS')
-> '2001-12-31T22:58:32.123Z'

<!-- GMT/BST date that is BST -->
stroom:format-date('2009/06/01 12:34:11', 'yyyy/MM/dd HH:mm:ss', 'GMT/BST')
-> '2009-06-01T11:34:11.000Z'

<!-- GMT/BST date that is GMT -->
stroom:format-date('2009/02/01 12:34:11', 'yyyy/MM/dd HH:mm:ss', 'GMT/BST')
-> '2009-02-01T12:34:11.000Z'

<!-- Time zone offset -->
stroom:format-date('2009/02/01 12:34:11', 'yyyy/MM/dd HH:mm:ss', '+01:00')
-> '2009-02-01T11:34:11.000Z'

<!-- Named time zone -->
stroom:format-date('2009/02/01 23:34:11', 'yyyy/MM/dd HH:mm:ss', 'US/Eastern')
-> '2009-02-02T04:34:11.000Z'

Note

Parsing is done in lenient mode so, the count of each symbol is not critical, e.g. you can parse the year 2024 with y, yy, yyy or yyyy. Despite this, it is advisable to use a pattern that matches the known format of the input dates, e.g. in this example yyyy, to avoid confusing with anyone else reading your XSLT.

The count of each symbol is however critical when it comes to formatting.

Formatting Examples

<!-- Specific output, no input or output TZ -->
stroom:format-date('2001/08/01 14:30:59', 'yyyy/MM/dd HH:mm:ss', null, 'E dd MMM yyyy HH:mm (s 'secs')')
-> 'Wed 01 Aug 2001 14:30 (59 secs)'

<!-- Specific output, UTC input, no output TZ -->
stroom:format-date('2001/08/01 14:30:59', 'yyyy/MM/dd HH:mm:ss', 'UTC', 'E dd MMM yyyy HH:mm (s 'secs')')
-> 'Wed 01 Aug 2001 14:30 (59 secs)'

<!-- Specific output, no output TZ -->
stroom:format-date('2001/08/01 14:30:59', 'yyyy/MM/dd HH:mm:ss', '+01:00', 'E dd MMM yyyy HH:mm (s 'secs')')
-> 'Wed 01 Aug 2001 13:30 (59 secs)'

<!-- Specific output, with input and output TZ -->
stroom:format-date('2001/08/01 14:30:59', 'yyyy/MM/dd HH:mm:ss', '+01:00', 'E dd MMM yyyy HH:mm', '+02:00')
-> 'Wed 01 Aug 2001 15:30'

<!-- Padded 12 hour clock output -->
stroom:format-date('2001/08/01 14:07:05.123', 'yyyy/MM/dd HH:mm:ss.SSS', 'UTC', 'E dd MMM yyyy pph:ppm:pps a')
-> 'Wed 01 Aug 2001  2: 7: 5 PM'

<!-- Padded 12 hour clock output -->
stroom:format-date('2001/08/01 22:27:25.123', 'yyyy/MM/dd HH:mm:ss.SSS', 'UTC', 'E dd MMM yyyy pph:ppm:pps a')
-> 'Wed 01 Aug 2001 10:27:25 PM'

<!-- Non-Padded 12 hour clock output -->
stroom:format-date('2001/08/01 14:07:05.123', 'yyyy/MM/dd HH:mm:ss.SSS', 'UTC', 'E dd MMM yyyy h:m:s a')
-> 'Wed 01 Aug 2001 2:7:5 PM'

<!-- Long form text -->
stroom:format-date('2001/08/01 14:07:05.123', 'yyyy/MM/dd HH:mm:ss.SSS', 'UTC', 'EEEE d MMMM yyyy HH:mm:ss')
-> 'Wednesday 1 August 2001 14:07:05'

Reference Time

When parsing a date string that does not contain a full zoned date and time, certain assumptions will be made.

If there is no time zone in inputDate and no inputTimeZone argument has been passed then the time zone of the input date will be assumed to be in the UTC time zone.

If any of the date parts are not present, e.g. an input of 28 Oct then Stroom will use a reference date to fill in the gaps. The reference date is the first of these values that is non-null

The create time of the stream being processed by the XSLT.
The current time, i.e. now().

For example for a call of stroom:format-date('28 Oct', 'dd MMM') and a stream create time of 2024, it will return 2024-10-28T00:00:00.000Z.

`format-dateTime`

format-dateTime(dateTime, [pattern], [timeZone])➡String

Formats an XPath date-time value using an optional output pattern and time zone. Without a pattern it uses Stroom’s standard date-time format; the default time zone is UTC.

Function Arguments:

Param	Type	Default Value	Allowed Values	Min Count	Description
`dateTime`	Date-Time	-	-	-	The XPath date-time value to format.
`pattern`	String	-	-	-	The output pattern. Omit for Stroom’s standard date-time format.
`timeZone`	String	-	-	-	The output time zone; defaults to UTC.

Return Value:

Type	Description
String	The formatted date-time string, or an empty sequence if formatting fails.

Date Formats

For details of date format syntax, as used by the pattern argument, see Custom Date Formats.

Examples

<!-- Default format -->
stroom:format-dateTime(xs:dateTime('2024-08-29T00:00:00Z'))
-> '2024-08-29T00:00:00.000Z'

<!-- Default format +2hr zone offset -->
stroom:format-dateTime(xs:dateTime('2001-08-01T18:45:59.123+02:00'))
-> '2001-08-01T16:45:59.123Z'

<!-- Default format +2hr30min zone offset -->
stroom:format-dateTime(xs:dateTime('2001-08-01T18:45:59.123+02:30'))
-> '2001-08-01T16:15:59.123Z'

<!-- Default format -3hr zone offset -->
stroom:format-dateTime(xs:dateTime('2001-08-01T18:45:59.123-03:00'))
-> '2001-08-01T21:45:59.123Z'

<!-- Simple date format UK style date -->
stroom:format-dateTime(xs:dateTime('2024-08-29T00:00:00Z'), 'dd/MM/yy')
-> '29/08/24'

<!-- Simple date format US style date -->
stroom:format-dateTime(xs:dateTime('2024-08-29T00:00:00Z'), 'MM/dd/yy')
-> '08/29/24'

<!-- With no delimiters -->
stroom:format-dateTime(xs:dateTime('2001-08-01T18:45:59Z'), 'yyyyMMddHHmmss')
-> '20010801184559'

<!-- Standard output, no TZ -->
stroom:format-dateTime(xs:dateTime('2001-08-01T18:45:59Z'), 'yyyy/MM/dd HH:mm:ss')
-> '2001/08/01 18:45:59'

<!-- Format with nanos -->
stroom:format-dateTime(xs:dateTime('2010-01-01T23:59:59.123456Z'), 'yyyy-MM-dd'T'HH:mm:ss.SSSSSSXX')
-> '2010-01-01T23:59:59.123456Z'

<!-- Standard output, with TZ -->
stroom:format-dateTime(xs:dateTime('2001-08-01T09:00:00Z'), 'yyyy/MM/dd HH:mm:ss', '-08:00')
-> '2001/08/01 01:00:00'

<!-- Standard output, with TZ -->
stroom:format-dateTime(xs:dateTime('2001-08-01T00:00:00Z'), 'yyyy/MM/dd HH:mm:ss', '+01:00')
-> '2001/08/01 01:00:00'

<!-- GMT/BST date that is BST -->
stroom:format-dateTime(xs:dateTime('2009-06-01T11:34:11Z'), 'yyyy/MM/dd HH:mm:ss', 'GMT/BST')
-> '2009/06/01 12:34:11'

<!-- GMT/BST date that is GMT -->
stroom:format-dateTime(xs:dateTime('2009-02-01T12:34:11Z'), 'yyyy/MM/dd HH:mm:ss', 'GMT/BST')
-> '2009/02/01 12:34:11'

<!-- Named time zone -->
stroom:format-dateTime(xs:dateTime('2009-02-02T04:34:11Z'), 'yyyy/MM/dd HH:mm:ss', 'US/Eastern')
-> '2009/02/01 23:34:11'

`from-unixTime`

from-unixTime(milliseconds)➡Date-Time

Converts milliseconds since the Unix epoch to an XPath date-time value.

Function Arguments:

Param	Type	Mandatory	Default Value	Allowed Values	Multiple	Min Count	Description
`milliseconds`	Integer		-	-		-	Milliseconds since the Unix epoch.

Return Value:

Type	Description
Date-Time	The corresponding date-time value.

`parse-dateTime`

parse-dateTime(inputDate, [pattern], [timeZone])➡Date-Time

Parses a date string to an XPath date-time value. Without a pattern it expects Stroom’s standard date-time format; the default time zone is UTC.

Function Arguments:

Param	Type	Default Value	Allowed Values	Min Count	Description
`inputDate`	String	-	-	-	The date string to parse.
`pattern`	String	-	-	-	Optional input date pattern.
`timeZone`	String	-	-	-	The input time zone; defaults to UTC.

Return Value:

Type	Description
Date-Time	The parsed date-time value, or an empty sequence if parsing fails.

Examples

<!-- ISO 8061 -->
stroom:parse-dateTime('2024-08-29T00:00:00Z')
-> '2024-08-29T00:00:00Z'

<!-- ISO 8061 with nanos -->
stroom:parse-dateTime('2010-01-01T23:59:59.123456Z')
-> '2010-01-01T23:59:59.123456Z'

<!-- ISO 8061 with millis -->
stroom:parse-dateTime('2010-01-01T23:59:59.123Z')
-> '2010-01-01T23:59:59.123Z'

<!-- ISO 8061 Zulu/UTC -->
stroom:parse-dateTime('2001-08-01T18:45:59.123+00:00')
-> '2001-08-01T18:45:59.123Z'

<!-- ISO 8061 +2hr zone offset -->
stroom:parse-dateTime('2001-08-01T18:45:59.123+02')
-> '2001-08-01T16:45:59.123Z'

<!-- ISO 8061 +2hr zone offset -->
stroom:parse-dateTime('2001-08-01T18:45:59.123+02:00')
-> '2001-08-01T16:45:59.123Z'

<!-- ISO 8061 +2hr30min zone offset -->
stroom:parse-dateTime('2001-08-01T18:45:59.123+02:30')
-> '2001-08-01T16:15:59.123Z'

<!-- ISO 8061 -3hr zone offset -->
stroom:parse-dateTime('2001-08-01T18:45:59.123-03:00')
-> '2001-08-01T21:45:59.123Z'

<!-- Simple date UK style date -->
stroom:parse-dateTime('29/08/24', 'dd/MM/yy')
-> '2024-08-29T00:00:00Z'

<!-- Simple date US style date -->
stroom:parse-dateTime('08/29/24', 'MM/dd/yy')
-> '2024-08-29T00:00:00Z'

<!-- ISO date with no delimiters -->
stroom:parse-dateTime('20010801184559', 'yyyyMMddHHmmss')
-> '2001-08-01T18:45:59Z'

<!-- Standard output, no TZ -->
stroom:parse-dateTime('2001/08/01 18:45:59', 'yyyy/MM/dd HH:mm:ss')
-> '2001-08-01T18:45:59Z'

<!-- Standard output, date only, with TZ -->
stroom:parse-dateTime('2001/08/01', 'yyyy/MM/dd', '-07:00')
-> '2001-08-01T07:00:00Z'

<!-- Standard output, with TZ -->
stroom:parse-dateTime('2001/08/01 01:00:00', 'yyyy/MM/dd HH:mm:ss', '-08:00')
-> '2001-08-01T09:00:00Z'

<!-- Standard output, with TZ -->
stroom:parse-dateTime('2001/08/01 01:00:00', 'yyyy/MM/dd HH:mm:ss', '+01:00')
-> '2001-08-01T00:00:00Z'

`to-unixTime`

to-unixTime(dateTime)➡Integer

Converts an XPath date-time value to milliseconds since the Unix epoch.

Function Arguments:

Param	Type	Mandatory	Default Value	Allowed Values	Multiple	Min Count	Description
`dateTime`	Date-Time		-	-		-	The date-time value to convert.

Return Value:

Type	Description
Integer	The corresponding milliseconds since the Unix epoch.

Last modified October 20, 2026: Merge pull request #144 from gchq/add-7.14-rel-notes (2c6fb22)