The function can be used to extract values from a date or to offset a date.
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.
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.
The source date may be in a variable or named variable. The date must be formatted as described in timestamps. If the day, or month and day components are omitted a value of 1 is assumed for each missing component. 0 is assumed for any missing time components. If the named variable field is empty, the current date/time is used.
The result of the function will be stored into a specified variable or named variable. If either the source or destination is a named variable, the function will only be performed once if executing stepwise.
When extracting a date component an integer value will be returned in the destination. You can extract the Year, Month, Day, Day of Year, Week of Year, Week of Year (Relative), First Day of Week, Day of Week, Days in Month, Days in Year, Hours, Minutes and Seconds. With the exception of Days in Month and Days in Year, all date components are ordinal 1. (January and Sunday are both 1). The time components are ordinal 0.
The Duration extraction method is special. The value in the source variable or named variable is a number of milliseconds, not a date. This is what is returned by the Time (ms) property. 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.
The Week of Year component returns the week number 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. The Week of Year component is not available on Snow Leopard (OS X 10.6). On Snow Leopard, Week of Year will return Week of Year (Relative). Week of Year (Relative) 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.
When offsetting to Day, Week, Month Year, Hours, Minutes or Seconds, you specify a number of units (positive or negative) to be added to the component in the supplied date. The destination is set to the modified date.
When offsetting to YYYY-01-01 or YY-MM-01, you are setting the day and month, or just the day to 1. The time components are set to 0. The destination is set to the modified date.
The date representation returned after offsetting is typically one of:
- yyyy-mm-ddThh:mm:ss
- if the seconds component is non zero
- yyyy-mm-ddThh:mm
- if the hours or minutes components are non zero
- yyyy-mm-dd
- for all other dates
If the Full option is selected, the returned date is always yyyy-mm-ddThh:mm:ss. When extracting components, the Full option is ignored.
All text fields may contain any of the escape sequences described in Escape Sequences.
If the function 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.