Date and Time Values in SenseTalk
SenseTalk includes commands and functions for working with dates and times. One date or time can be subtracted from another by using the minus ( - ) operator, to get their difference in seconds. A time interval can also be added to a date or time to obtain a new date/time value (see Adding and Subtracting Time Intervals).
Dates, Times, and Time Intervals
SenseTalk makes no fundamental distinction between a "date" and a "time"—both are treated as precise instants in the flow of time, or points along a timeline whose origin (zero value) was at the stroke of midnight at the beginning of January 1, 2001, Coordinated Universal Time. Any date or time before that instant is treated internally as a negative value, and later times as a positive value indicating the number of seconds since the origin.
SenseTalk can recognize dates and times expressed in a wide variety of formats such as "4/22/67" or "1967-04-22 18:00." See the timeInputFormat
global property for details. The Natural
format allows even more variations, such as "May 15, 2004 10:57 PM", or even "yesterday", "today", or "next Tuesday in the afternoon." The words today
and now
(without enclosing quotes) can be used to indicate the current date or the current date and time (unless they are used as variables and assigned some other value). See Natural
Format for more information about this format.
Whenever a date value is supplied without a time of day, it is taken to mean noon of that day. When a time is given without a date, it is assumed to mean the indicated time on the current date (today). All dates and times are assumed to be in the local time zone, as currently set on the machine where the script is running.
A time interval or duration is a length of time. When dealing with time intervals, SenseTalk assumes durations measured in seconds if no specific unit is given, but also allows many other units to be used including weeks, days, hours, milliseconds, etc. (see Time Intervals in Values).
In addition to durations that can be precisely measured in seconds, SenseTalk also supports calendar durations measured in months, including months, calendarQuarters, calendarYears, etc. To see the full list of calendarDuration units that are available, use this command:
put (each item of the unitNames whose unitType is calendarDuration) sorted
See Calendar Durations for more information.
Both time intervals and calendar durations can be used with the ago
and hence
operators to produce a time value that is a length of time in the past or future.
Because there is no real difference between dates and times, this document sometimes refers to either a date or a time as "a date/time value."
Related Global and Local Properties
SenseTalk includes several global or local properties that you can use to affect the behavior of date and time values in your scripts. You will see these properties mentioned in the descriptions of concepts below. Full definitions of each property can be found on Local and Global Properties for Working with Values. The specific properties are:
The ClockFormat
The TimeFormat
The TimeInputFormat
The CenturyCutoff
The LastDayOfMonthCalculation
Date/Time Arithmetic
Adding and Subtracting Time Intervals
Starting from any date (or time), you can obtain a different date/time by simply adding or subtracting a time interval.
Example:
put today + 2 weeks into dueDate
Example:
subtract 3 hours 14 minutes 22 seconds from timer
Calculating Date or Time Differences
By subtracting one date or time value from another, you can easily calculate the number of days between dates or the elapsed time for some process. The difference is always a time interval expressed in seconds, but you can convert it to a different unit (such as days) by dividing it by the number of seconds in that unit (which can be expressed using a time interval expression such as 1 day
, for example). Or you can use the as
operator to convert it to a different duration unit.
Example:
put (expirationDate - "today") / 1 day into daysRemaining -- results in a pure number
put (expirationDate - "today") as days into daysRemaining -- results in a number with units of days
Example:
put the time into startTime -- Start timing here
run somethingTimeConsuming -- Whatever you want to time
put the time - startTime into secondsElapsed
Date or Time Comparisons
The SenseTalk comparison operators (is
, =
, comes before
, <
, and the like) ordinarily treat the two values being compared as text, unless they are both numbers or it "knows" they are both date or time values. Because comparisons usually treat values as text, the following will not produce the desired result:
if the date is between "Sep 21" and "Dec 21" then put "Happy Autumn"
To persuade SenseTalk to perform date or time comparisons, use the date()
or time()
functions or the as date
or as time
operators to convert the text to an internal date/time representation. This will work (note that when the year isn’t specified, the current year is assumed, so this example will work in any year):
if the date is between date ("Sep 21") and "Dec 21" as a date then
put "Happy Autumn!"
end if
Commands and Functions for Working with Dates and Times
Below are the specific commands and functions you can use to manipulate date and time values in SenseTalk.
Date
, AsDate
Functions
Behavior: Returns the current date, or the date value for a given expression. The long date
function returns a verbose version of the date, including the current day of the week and the full name of the month. Abbreviated date
and short date
variants provide the date in other formats. The value returned by the date
function, when converted to text, will automatically display a formatted date, as shown in the Examples. Its value may also be treated as a number, representing the exact date and time when the function was called, for use in date/time calculations. When dateExpr is given, returns a value representing noon on the given day (if dateExpr includes a time of day, it is ignored).
The asDate
function also converts the value given in dateExpr to a date, but instead of assigning it the standard date format, the asDate
function will derive the format from the way dateExpr itself is formatted. The asDate function can also be called using the as {a} date
operator.
Syntax:
the { [ long | short | abbr{ev{iated}} ] } date {of dateExpr}
date( {dateExpr} )
asDate( dateExpr )
Example:
put the date --> "10/07/95"
put the short date --> "10/7/95"
put the abbrev date --> "Sat, Oct 7, 1995"
put the long date --> "Saturday, October 7, 1995"
Example:
put date("May 14, 1942") --> "05/14/42"
Example:
put asDate("May 14, 1942") --> "May 14, 1942"
Related:
TimeZoneOffset
, UTCOffset
, SecondsFromGMT
Functions
Behavior: The TimeZoneOffset
function (or its synonym UTCOffset
) returns the difference between the current local time and Coordinated Universal Time or UTC, expressed in units of hours. The SecondsFromGMT
function (referring to the historical term Greenwich Mean Time or GMT) returns the same value expressed as the plain number of seconds (without units).
These functions can be called with one or two optional parameters. If called with one parameter which is a date, they return the local difference from UTC on that given date (which may vary depending on whether or not daylight savings is in effect on that date). If called with one parameter which is a time zone, they return the difference between that time zone and UTC on the current date. If called with both a date and a time zone (in either order), these functions return the difference between the specified time zone and UTC, on the given date.
When specifying a time zone you may use its official id name (e.g. "America/Los_Angeles"), the time zone abbreviation ("PDT"), or any unique part of the name, ignoring spaces and special characters (e.g. "los angeles").
Syntax:
the [ TimeZoneOffset | UTCOffset | SecondsFromGMT ] {of aDateOrTimeZone } [ TimeZoneOffset | UTCOffset | SecondsFromGMT ]( {aDateOrTimeZone} ) [ TimeZoneOffset | UTCOffset | SecondsFromGMT ]( aDate , aTimeZone ) [ TimeZoneOffset | UTCOffset | SecondsFromGMT ]( aTimeZone , aDate )
Example:
put the TimeZoneOffset --> -7 hours (example shown in Mountain Standard Time)
put the SecondsFromGMT --> -25200 (the same value as a plain number of seconds)
put the TimeZoneOffset of "July 1" --> -6 hours (July is in Mountain Daylight Time)