All Tinderbox Date-type data includes a time component in hours and minutes (no seconds or smaller). The time can be a confusing factor when comparing dates as often in the mind of the user whole days are being compared. Also, when using date designators, like "today" or "tomorrow + 1 month", the Date object created takes the OS' current clock time.
Thus at local time 13:00 on 28 November 2012, 'today' will return a value of 28 November 2012 13:00. A minute later it will return a value of 28 November 2012 13:01.
The time element is often overlooked when doing date-based arithmetic, especially for jobs like agents designed to find something like "all unfinished tasks in the next week". The natural tendency is to use a date (part of the) query like so:
$DueDate > date("today + 7 days") & $DueDate < date("today + 14 days")
However, for > and < the time element is counted. Thus, if 'today' were 28 November 2012 12:00, any items with a $DueDate before 12:00 on that day would not match the query. This is likely not what a new user would intend. To avoid the time issue with > and < comparisons where the time element is to be ignored there are two strategies:
- adjust the number of offset days and use >= or <= instead.
- ensure the reference date ('today' or whatever) has its time element correctly set.
Alternatively, to find past (or future dates) that only coincide (or not!) with the current calendar day, a two-part query is needed. Equality test operators (== and !=) and those including an equality test component (>= and <=) ignore the time element and test only for the whole calendar day. The latter effectively combine the less/greater test and an equality test, e.g. ((A > B) | (A ==)), the first of which is time sensitive and latter not. So, if the tested date time is 12:00 on 15 Jan 2013, >= will find all date-times before 00:00 on 16 Jan 2013; <= will find all dates after 00: on 15 Jan 2013. Neither of these is likely what the user intended. To find overdue $DueDate that are only on the current calendar day:
$DueDate < date("today") & $DueDate == date("today ")
Conversely to get the same but where the overdue notes are not on the current calendar day:
$DueDate < date("today") & $DueDate != date("today ")
Setting the time element of a date is discussed in more detail here.