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:
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.
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.
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:
Unless Yate can determine that the supplied date format is incorrect, it will used. For example if you specify Y M D and the date is Jan 1, 2004, the supplied date format will be ignored.
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:
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:
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).
A compressed format will also be parsed. A consecutive sequence of exactly 8, 12 or 14 numeric digits will interpreted as follows:
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.
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:
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.
You can optionally specify that the result should be compressed. When compressed, all characters which are not decimal digits are removed. This typically only makes sense with the Y M D and 24 Hour format settings.
Unless otherwise specified all of the Extract Value functions return an integer value as the result. You can request the following items:
n day{s}{,} {h:}{m:}{s}Note that the n, d, h, m and s values can be any non negative integer value.
{d:}{h:}{m:}s
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:
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.
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.
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 by the statement. 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.