Date Formatters

Version 23.4.8839


Date Formatters


Common Date Formatters

The following formatters are the most common date formatters. An example for each formatter is provided for reference.

Additional examples of date format syntax are provided in Sample Date Formats.

now([outputformat])

Returns the current system datetime according to the specified outputformat (default format is: yyyy-MM-dd’T’hh:mm:sszzz).

This formatter is unusual in that it does not modify the input attribute (variable), so no such input attribute is required.

Example

<arc:set attr="timestamp" value="[now()]" />

todate([outputformat][, inputformat][, strictInputFormat])

Formats the input attribute as a date in the format specified by outputformat (the default output format is: yyyy-MM-dd’T’hh:mm:sszzz). For examples of date formats and how they are expressed, see Sample Date Formats.

The formatter attempts to auto-detect the format of the input value, but you can specify the inputformat parameter if the formatter is unable to determine the input format.

Use the strictInputFormat argument to check whether the incoming date value matches the input format: if it does not the task throws an error instead of converting the date to a standard date format. The default is not to check. To force the check, add true to the formatter.

Example

<arc:set attr="simpleDate" value="01-30-2020" />
<arc:set attr="reformattedDate" value="[simpleDate | todate('yyyyMMdd', 'dd-MM-yyyy')]" />

dateadd(intervaltype, value[, outputformat][, inputformat])

Adds a specified amount of time to the input date and returns the result. The intervaltype parameter specifies the unit of time to add (e.g. ‘year’, ‘month’, ‘day’, ‘hour’, ‘minute’, ‘second’, ‘millisecond’) and the value parameter specifies how many of these units to add.

The formatter will attempt to auto-detect the format of the input value, but the inputformat parameter can be specified if the formatter is otherwise unable to determine the datetime format of the input attribute. The result will be returned in the format specified by outputformat (default output format is: yyyy-MM-dd’T’hh:mm:sszzz).

Example

<arc:set attr="shipdate" value="2020-03-15" />
<arc:set attr="estmArrivalDate" value="[shipdate | dateadd('day', 2)]" />

More Date Formatters

Below is the list of less-common formatters not included in the previous section.

compare([value][, inputformat])

Returns a signed number indicating the relative values of dates represented by the attribute value and parameter value.

  • value: The optional string representation of the date that will be compared with the attribute value. Default is now.
  • inputformat: The optional input format specifier. Default is autodetected.

date([outputformat])

Note: This formatter is an alias for the now() formatter described in the previous section.

Returns the current system date and time in the format specified by the parameter if one was provided.

  • outputformat: The optional format specifier. Valid specifiers include d (short date pattern), D (long date pattern), f (long date/short time pattern), F (long date/time pattern), g (general short date/time pattern), G (general short date/long time pattern), r or R (RFC1123 pattern), s (sortable date/time pattern), t (short time pattern), T long time pattern), file (Windows file time), MM/dd/yy, etc.

datediff([interval][, value][, inputformat])

Returns the difference (in units specified by the first parameter) between now and the date specified by the second parameter.

  • interval: The optional interval you want the result in. Specify day, hour, minute, second, or millisecond.
  • value: The optional string representation of the date to compare with attribute value. Default is now.
  • inputformat: The optional input format specifier. Default is autodetected.

day([inputformat])

Returns the day component, expressed as a value between 1 and 31, of the date represented by the attribute value.

  • inputformat: The optional input format specifier. Default is autodetected.

dayofweek([inputformat])

Returns the day of week for the date represented by the attribute value.

  • inputformat: The optional input format specifier. Default is autodetected.

dayofyear([inputformat])

Returns the day of year expressed as a value between 1 and 366 for the date represented by the attribute value.

  • inputformat: The optional input format specifier. Default is autodetected.

filetimenow()

Returns the date and time for the current system file time.

fromfiletime([outputformat])

Converts a valid file time to a valid datetime value formatted as specified by the parameter if one was provided.

  • outputformat: The optional output format specifier. Valid specifiers include d (short date pattern), D (long date pattern), f (long date/short time pattern), F (long date/time pattern), g (general short date/time pattern), G (general short date/long time pattern), r or R (RFC1123 pattern), s (sortable date/time pattern), t (short time pattern), T (long time pattern), file (Windows file time), MM/dd/yy, etc.

isleap([ifleap][, ifnotleap])

Returns true (or ifleap) if the 4-digit year represented by the attribute value is a leap year, false (or ifnotleap) otherwise.

  • ifleap: The optional value returned if the attribute value is a leap year.
  • ifnotleap: The optional value returned if the attribute value is not a leap year.

month([inputformat])

Returns the month component expressed as a value between 1 and 12 of the date represented by the attribute value.

  • inputformat: The optional input format specifier. Default is autodetected.

tofiletime([inputformat])

Converts a valid datetime to a valid file time value.

  • inputformat: The optional input format specifier. Default is autodetected.

toutc([outputformat][, inputformat])

Returns the date specified by the attribute value converted to UTC and formatted as specified by the outputformat parameter if one was provided.

  • outputformat: The optional format specifier. Valid specifiers include d (short date pattern), D (long date pattern), f (long date/short time pattern), F (long date/time pattern), g (general short date/time pattern), G (general short date/long time pattern), r or R (RFC1123 pattern), s (sortable date/time pattern), t (short time pattern), T (long time pattern), and file (Windows file time), MM/dd/yy, etc.

utcnow([outputformat])

Returns the current system UTC date and time.

  • outputformat: The optional format specifier. Valid specifiers include d (short date pattern), D (long date pattern), f (long date/short time pattern), F (long date/time pattern), g(general short date/time pattern), G (general short date/long time pattern), r or R (RFC1123 pattern), s (sortable date/time pattern), t (short time pattern), T (long time pattern), file (Windows file time), MM/dd/yy, etc.

weekday([inputformat])

Returns the day of the week as an integer where Monday is 0 and Sunday is 6.

  • inputformat: The optional input format specifier. Default is autodetected.

year([inputformat])

Returns the year component of the date represented by the attribute value.

  • inputformat: The optional input format specifier. Default is autodetected.

Sample Date Formats

Following are sample date format strings for reference. Use them to customize the date formatters to fit your use case. Because there are differences between what is supported in each edition, this section includes results for both the Cross-Platform and .NET editions.

For each example in the following table, the day is March 5th, 2024. The time is 12 hours, 31 minutes, 5 seconds, and 336 milliseconds after midnight in the Eastern Standard time zone (UTC-5).

Date Format String Cross-Platform Result .NET Result
MM-dd-yy 03-05-24 03-05-24
MM/dd/yyyy HH:mm 03/05/2024 12:31 03/05/2024 12:31
yyyy-MM-dd HH:mm:ss 2024-03-05 12:31:05 2024-03-05 12:31:05
yyyy-MM-dd HH:mm:ss.SSS 2024-03-05 12:31:05.336 Not applicable for .NET
yyyy-MM-dd HH:mm:ss.fff 2024-03-05 12:31:05.336 2024-03-05 12:31:05.336
yyyy-MM-dd HH:mm:ss X 2024-03-05 17:31:05 -05 Not applicable for .NET
ddd dd MMM yyyy HH:mm:ss zzz Tue 05 Mar 2024 12:31:05 -05:00 Tue 05 Mar 2024 12:31:05 -05:00
ddd dd MMM yyyy HH:mm:ss z Tue 05 Mar 2024 12:31:05 -0500 Tue 05 Mar 2024 12:31:05 -5

Date Formats With Literal Characters

When working with literals (like ‘T’) in DateTime strings, pay careful attention to the quote characters that might be used outside of the formatter. For example, if the formatter is used in a value XML attribute to assign a value to an ArcScript attribute, you might need to use different quote styles or escape sequences to avoid terminating the string too early.

For example, if you are creating a datetime value for an item’s attribute in a custom script and you need a literal, you might choose to define the value for the attribute between the opening and closing arc:set tags. Notice that value="" is not set.

<arc:set attr="out.data">[_ | now("yyyy-MM-dd'T'HH:mm:ss")]</arc:set>