Tinderbox's date parser accepts the following expressions as placeholders for calculated dates:
All provide a date/time, with the seconds element of time coerced to '00'. today and now return exactly the same value. The alternate designators can make for more intuitive use in code in different contexts.
The following designators can be used to modify the above. However, if simply used on their own, rather than as a modifier they do not return a valid date/time:
There is a further special case:
- never. No date, and regarded as earlier or later than any real date.
Treat usage for the above placeholders as case sensitive.
Day of week placeholders—Sunday, Monday, etc.—may also be used. Tinderbox recognises the day of the week (in English, currently) and interprets it as the day after today with that week day. Thus on Sunday June 1, the date "Sunday" refers to Sunday, June 8. The date parser recognises the day of the week in the current locale, not only in English. Recognised forms include the full day (Sunday), the short day (Sun), and the very short day (S). Note though, that the very short day is ambiguous in many languages, including English.
In other respects, days of the week act like today and can be modified similarly, e.g. "Monday - 1" week is the previous Monday.
Dates may be modified by adding and subtracting "minutes", 'hours", "days", "weeks" and "years":
Explicit (24-hour clock) time can be used, in which case it comes at the end of the string:
date("today+7 days 00:00")
The latter is useful to ensure that a base like 'today' or 'now' that take system clock time are set to to an exact known time, as may be needed for accurate date comparison.
Normally time is input is the form consistent with the users short date(/time) form such as "09:30" or "9:30 AM"but more flexibility is offered for import making it easier to set times as part of date/time designators, such as:
The first two before half-past nine in the morning, The latter will be interpreted as 11 AM (11:00): the lack of minutes implies to set them as 00.
Note that the date() arguments are written as quoted strings which my include addition/subtraction signs. This format is deprecated:
date("today" +" 65 minutes")
If using Attribute values in a date expression simple use the $-prefixed attribute name outside the quoted string:
If modifying a date and the expression part of code can not be parsed as a date modified, the unmodified date is returned; this avoids unintentional creation of undefined ('never') dates.
Date parsing: the date "tomorrow 8" is treated as 8 o'clock tomorrow. Note in that older versions it was interpreted as 8 days from tomorrow. "Tomorrow+8" continues to denote 8 days from tomorrow.
Beware that any Date-type attributes initialised using using year, month & day without a time element will use current system time as opposed to a 00:00:00 which might otherwise be assumed.