Date Functions

The statement performs a wide variety of date related functions.

All text fields may contain any of the escape sequences described in Escape Sequences.

The result of the statement will be stored into a specified track or named variable. If either the source or destination is a named variable, the statement will only be performed once if executing stepwise.

Note that date strings in Yate are oblivious to timezones. All dates are assumed to be in the system's timezone. The millisecond conversions do the necessary manipulations between UTC and the system time zone.

Yate date formats are based on the Gregorian calendar. If your system is configured to use a Gregorian calendar, this calendar and its current settings will be used in all calculations. If your system calendar is not a Gregorian calendar, one will be provided.

The first step is to provide the primary function:

Extract Value: Primarily used to extract a single component of a date. Typically a numeric value is returned.
Offset Date: Primarily used to offset a date component by a supplied value. Typically a formatted date is returned
Format Date: The supplied source date is reformatted and returned.

Certain date operations require knowledge of the day representing the first day of the week. By default the value used is the current System value. However, if your system calendar is not a Gregorian calendar, or if you wish to override your system value, you can force the first day to be Sunday (typically the default) or Monday.

Date Input Formatting

A source date may be in a track or named variable. Yate parses a variety of date formats. The most standard format is the one described in timestamps. No attempt is made to automatically determine the component order. The supplied date format is always used.

In all formats, the month component can be numeric or symbolic (English). The date and year components are always numeric. The number of digits in a numeric component are irrelevant as long as the value is appropriate. A symbolic month is case insensitive and can be the full name, a three character abbreviation or Sept. Components can be separated by a single dash (-), period (.), space or slash (/).

In the case that dates are being extracted from text copied from the web, the source is folded.

The following date formats may be specified:

Y M D: The month or month and date may be omitted if the year is a 4 digit year. Omitted components are considered to be 1.
D M Y: All components must be specified.
M D Y: All components must be specified. If the month is symbolic and separated from the date by a space, the date component may be separated from the year component by a comma (,) followed by any number of spaces. In the case the date component can also optionally be followed by the correct suffix: st, nd, rd, th.

Years can be specified in full or abbreviated. A year of 0 through 99 is interpreted dependent on named variable Date Function Two Digit 1900 Start. The process is as follows:

If Date Function Two Digit 1900 Start is undefined, its value is assumed to be 50, otherwise it is interpreted as an integer value.
If the two digit year value is greater than or equal to Date Function Two Digit 1900 Start the year is interpreted as 19xx, otherwise 20xx.

The date portion of the source may be followed by a time specification. The date and time specification may be delimited by a T or one or more spaces. The time specification can include hours, minutes and seconds separated by a colon (:). The time specification can be presented in 24 hour format or may optionally be followed by am or pm (case insensitive). Seconds are always optional. In order to enable accurate parsing when a date is followed by an integer, a trailing time component of hours (no minutes) will only be processed if one or more of the following holds:

a T separator was specified
the hours value is followed by a colon
AM or PM is specified

Omitted hours, minutes and seconds are assumed to be 0.

At runtime, if the effective source field is empty, either the current date or 0 will be assumed (depending on which operation is being performed).

Result Formatting

When a date is the result of the specified function, you have access to various settings which control the format. The five formatting options are displayed under the result destination field. The options from left to right are:

Date & Time | Date Only | Time Only

Determines which components are displayed. This setting controls which of the others are available. When any value other than Time Only is chosen a date component order control is displayed to the right of the result destination field. You can choose YMD, DMY or MDY.

- | / | .

Chooses the separator to be used between the year, month and day components. This setting is not available when Time Only is chosen.

T

When enabled a T is used to separate the date and time components. When not enabled, a space is used. This setting is only available when Date & Time is chosen.

12 Hour | 24 Hour

Determines if the time specification should use a 12 or 24 hour format. When 12 Hour is selected, the time will be followed by AM or PM. This setting is not available when Date Only is chosen.

HH:MM:{SS} | HH:MM:SS | HH:MM

Controls the display of seconds in the time representation. This setting is not available when Date Only is chosen. The values are interpreted as follows:

HH:MM:{SS}: Seconds are only displayed when the value is non zero.
HH:MM:SS: Seconds are always displayed.
HH:MM: Seconds are never displayed.

The effective display of the chosen result format is displayed in the representation in the list of statements at the top right of the window.

Extract Value Mode

Unless otherwise specified all of the Extract Value functions return an integer value as the result. You can request the following items:

Year: The value of the year component of the supplied date will be extracted.
Month: The value of the month component (1 - 12) of the supplied date will be extracted.
Day: The value of the day component (1 - 31) of the supplied date will be extracted.
Week of Year: Extracts the week number (ordinal 1) in which the supplied date falls. Weeks start on a Sunday or Monday and the first day in a year may not be the first day in a given week.
Week of Year (Relative): Similar to Week of Year except it is not based on a week starting on a particular day. In this mode Jan 1 of any given year, is the first day of the first week.
First Day of Week: Extracts a number representing the first day of the week. Sunday is 1, Monday is 2, etc.
Day of Week: Extracts a number representing the day in the source date. Sunday is 1, Monday is 2, etc.
Days in Month: Extracts a number representing the number of days in the source date's month.
Days in Year: Extracts a number representing the number of days in the source date's year.
Hours: The value of the hour component of the supplied date will be extracted. The number returned is always in 24 hour format (0-23).
Minutes: The value of the minutes component of the supplied date will be extracted. (0-59)
Seconds: The value of the seconds component (0-59) of the supplied date will be extracted.
Duration from ms: The value in the source field is treated as a number of milliseconds, not a date. If you are accumulating durations and you want a visual representation you can use this function. The returned representation may include days and hours and will always return minutes and seconds. A day component is returned as part of the duration string: eg. in 5:06:30:20, 5 is the days, 06 is the hours, 30 is the minutes and 20 is the seconds.
Duration from ms (Symbolic): The value in the source field is treated as a number of milliseconds, not a date. If you are accumulating durations and you want a visual representation you can use this function. The returned representation may include days and hours and will always return minutes and seconds. A day component is returned symbolically. eg. 3 days, 1:30:25
ms from Duration: The number of milliseconds representing the duration in the source field is returned. The duration can be any of the following:
n day{s}{,} {h:}{m:}{s}
{d:}{h:}{m:}s
Note that the n, d, h, m and s values can be any non negative integer value.
Date from ms: This extract function returns a date as opposed to a numeric value. The value in the source field is treated as a number of milliseconds from the reference date of 1970-01-01T00:00:00.
ms from Date: The source date is converted to a number of milliseconds fron the reference date of 1970-01-01T00:00:00

Offset Date Mode

When offsetting to a date component, unless otherwise mentioned, you are adding a signed integer value to the component. A date specification is returned. Offsetting the Day, Week, Month, Year, Hours, Minutes or Seconds component is as you would expect. There are two Offset Date Modes which are slightly different:

YYYY-01-01: Sets the month, day to 1 and the hours, minutes and seconds to 0.
YYYY-MM-01: Sets the month to 1 and the hours, minutes and seconds to 0.

Format Date Mode

This mode is used to apply a specific date format to the source date. It can be used to reformat a date or to remove the date or time components.

The Action Test State

If the statement fails for any reason, the action test state will be set to false and the destination will be emptied. When running stepwise and multiple functions are performed, a test state of false implies that at least one failed. Upon success the action test state is set to true.

Using this Statement When Scanning

This statement can be used in conjunction with Scanner statements. However, you can only do so when a named variable or a single file is being processed. ie. not when execution is grouped and more than one file is available. If the action test state returned is true, the Date Function Scan Offset named variable will contain the offset of the first character not processed. This offset can be used with a Substring statement to extract the remainder of a string to be processed.