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)
Example:
put TimeZoneOffset("March 4, 2001", "Denver") --> -7 hours
put UTCOffset("Paris", "2023-07-10") --> 2 hours
Related:
Seconds
Function
Behavior: Returns the current number of seconds since the beginning of January 1, 2001. The long seconds
function returns a more precise version of the seconds, including the current fraction of a second. Abbreviated seconds
and short seconds
variants are also available, which provide values rounded to the microsecond (6 decimal places) and millisecond (3 decimal places), respectively. If a dateTimeValue is given, the number returned will be the number of seconds since the beginning of January 1, 2001, until the given time (a negative number if the given time is earlier than 2001).
Syntax:
the { [ long | short | abbr{ev{iated}} ] } seconds
the seconds {of dateTimeValue}
seconds( {dateTimeValue} )
Example:
put the seconds --> 62899676
Example:
put the long seconds --> 62899676.90865231
put abbreviated seconds --> 62899676.908652
put the short seconds --> 62899676.908
Related:
Ticks
Function
Behavior: Returns the number of ticks (1/60 second) since the SenseTalk engine was started.
Syntax:
the ticks
ticks()
Example:
if the ticks is greater than 36000 then
put "SenseTalk was started more than 10 minutes ago."
end if
Related:
Time
, AsTime
Functions
Behavior: Returns the current time of day, or the time value of a given expression. The long time
function returns a longer version of the time, including the seconds. Abbreviated time
and short time
variants provide the time in other formats.
The asTime function also converts the value given in timeExpr to a time, but instead of assigning it the standard time format, the asTime function will derive the format from the way timeExpr itself is formatted. The asTime function can also be called using the as {a} time
operator.
Syntax:
the { [ long | short | abbr{ev{iated}} ] } time {of timeExpr}
time( {timeExpr} )
asTime( {timeExpr} )
Example:
put the time --> 02:38 PM
put the short time --> 02:38
put the abbrev time --> 02:38:32
put the long time --> 02:38:32 PM
Example:
put time("7:35:42")--> 07:35 AM
Example:
put asTime("7:35:42") --> 07:35:42
The value returned by the time
function, when converted to text, will automatically display a formatted time, 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 (or the exact date and time represented by its parameter), for use in date/time calculations or comparisons.
If the clockFormat
global property is set to "24 hour", the format used by all of the time functions will not include "AM" or "PM" but instead will indicate hours between 00 and 23.
When timeExpr is given, that value is evaluated and returned as an internal time representation.
The asTime
function also converts the value given in timeExpr to a time, but instead of assigning it the standard time format, the asTime
function will derive the format from the way timeExpr itself is formatted. The asTime function can also be called using the as {a} time
operator.
Related:
Date or Time Components
The following functions provide individual components of a given date or time. Or, when called without a parameter, each function returns a specific component of the current date or time. For example:
the hour
returns the current hourthe hour of "8.45 AM"
returns the hour component of the given time. In this case,8
.
Year
Function
Behavior: Returns the year number of a given date, or the current year.
Syntax:
the year {of dateTimeValue}
year( {dateTimeValue} )
Example:
put the year into currentYear
Example:
put year("4 July 1776") --> 1776
Related:
- The
Date
Function - The
Month
Function - The
MonthName
Function - The
Day
Function - The
WeekdayName
Function - The
DayOfYear
Function
Month
Function
Behavior: Returns the month number (from 1 to 12) of a given date, or the current month.
Syntax:
the month {of dateTimeValue}
month( {dateTimeValue} )
Example:
put the month into monthNum
Example:
put month("4 July 1776") --> 7
Related:
- The
Date
Function - The
Year
Function - The
MonthName
Function - The
Day
Function - The
WeekdayName
Function
MonthName
Function
Behavior: Returns the month name of a given date, or the current month.
Syntax:
the monthName {of dateTimeValue}
monthName( {dateTimeValue} )
Example:
put monthName() into monthName
Example:
put the monthName of "27 April 2022" --> April
Related:
Day
Function
Behavior: Returns the day number (from 1 to 31) of a given date, or of the current date.
Syntax:
the day {of dateTimeValue}
day( {dateTimeValue} )
Example:
put day() into dayNum
Example:
put the day of "4 July 1776" --> 4
Related:
- The
Date
Function - The
Year
Function - The
Month
Function - The
MonthName
Function - The
WeekdayName
Function - The
DayOfWeek
Function - The
DayOfYear
Function - The
DayOfCommonEra
Function
WeekdayName
Function
Behavior: Returns the day name of a given date, or of the current date.
Syntax:
the weekdayName {of dateTimeValue}
weekdayName( {dateTimeValue} )
Example:
put weekdayName() into dayName
Example:
put the weekdayName of "27 April 2022" --> Wednesday
Related:
- The
Date
Function - The
Year
Function - The
Month
Function - The
MonthName
Function - The
DayOfYear
Function - The
DayOfCommonEra
Function
DayOfWeek
Function
Behavior: Returns the weekday number (from 1 to 7) of a given date, or of the current date. The first day of the week, number 1, is determined by your system settings.
Syntax:
the dayOfWeek {of dateTimeValue}
dayOfWeek( {dateTimeValue} )
Example:
put dayOfWeek() into weekdayNum
Example:
put the dayOfWeek of "4 July 1776" --> 5 (Thursday)
Related:
- The
Date
Function - The
Year
Function - The
Month
Function - The
MonthName
Function - The
Day
Function - The
DayOfYear
Function - The
DayOfCommonEra
Function
DayOfYear
Function
Behavior: Returns the day number within a year (from 1 to 366) of a given date, or the current date.
Syntax:
the dayOfYear {of dateTimeValue}
dayOfYear( {dateTimeValue} )
Example:
put dayOfYear() into dayNum
Example:
put the dayOfYear of "4 July 1776" --> 186 (the 186th day of the year)
Related:
- The
Date
Function - The
Year
Function - The
Month
Function - The
MonthName
Function - The
Day
Function - The
DayOfWeek
Function - The
WeekdayName
Function - The
DayOfCommonEra
Function
DayOfCommonEra
Function
Behavior: Returns the day number of a given date, or of the current date, since the beginning of the Common Era (January 1 of the year 1). This function can be useful for calculating the number of elapsed days between any two dates.
Syntax:
the dayOfCommonEra {of dateTimeValue}
dayOfCommonEra( {dateTimeValue} )
Example:
put the dayOfCommonEra into todayNum
Example:
put dayOfCommonEra("4 July 1776") --> 648491
Example:
put "The U.S. has been independent for "& \
dayOfCommonEra() - dayOfCommonEra("4 July 1776") &" days"
Related:
- The
Date
Function - The
Year
Function - The
Month
Function - The
MonthName
Function - The
Day
Function - The
DayOfWeek
Function - The
WeekdayName
Function - The
DayOfYear
Function
Hour
Function
Behavior: Returns the hour number (from 0 to 23) of a given time value, or of the current time.
Syntax:
the hour {of dateTimeValue}
hour( {dateTimeValue} )
Example:
put the hour into hourNum
Example:
put hour("5:37:22 PM") --> 17
Related:
Minute
Function
Behavior: Returns the minute number (from 0 to 59) of a given time value, or of the current time.
Syntax:
the minute {of dateTimeValue}
minute( {dateTimeValue} )
Example:
put minute() into minutesPastTheHour
Example:
put the minute of "5:37:22 PM" --> 37
Related:
Second
Function
Behavior: Returns the second number (from 0 to 59) of a given time, or of the current time.
Syntax:
the second {of dateTimeValue}
second( {dateTimeValue} )
Example:
put the second into currentSecondNumber
Example:
put second("5:37:22 PM") --> 22
The value returned by the second()
function will always be a number from 0 to 59. This is quite different from the seconds()
function, which returns the number of seconds since the beginning of January 1, 2001.
Related:
- The
Time
Function - The
Hour
Function - The
Minute
Function - The
Ticks
Function - The
Millisecond
andMicrosecond
Functions - The
Seconds
Function
Millisecond
, Microsecond
Functions
Behavior:
- The
millisecond
function: Returns the millisecond number (from 0 to 999) of a given time, or of the current time. A millisecond is one thousandth of a second. - The
microsecond
function: Returns the microsecond number (from 0 to 999999) of a given time, or of the current time. A microsecond is one millionth of a second.
Syntax:
the millisecond {of dateTimeValue}
millisecond( {dateTimeValue} )
the microsecond {of dateTimeValue}
microsecond( {dateTimeValue} )
Example:
put millisecond() into currentMillisecond
Example:
put the millisecond of startTime
Example:
set tempName to the hour & the minute & the second & the microsecond
Example:
put microsecond(previousTime)
Related:
Date and Time Formats
SenseTalk can represent dates and times in many different formats. The commands and functions in this section work with these different formats.
Convert
Command
Behavior: The convert
command converts a date/time value to different date/time formats. If the source value being converted is a container, the contents of the container are replaced with the converted value. Otherwise, the result is placed in the variable it
.
In either case (except when converting to one of the seconds formats), the resulting value internally is a date/time value with the requested format. This format allows you to add or subtract time intervals from the result while retaining the same format.
The actual formats used are defined in the timeFormat
global property and can be changed if desired. The seconds formats have no corresponding value in the timeFormat
, so converting to seconds, long seconds, and so forth, results in a fixed string rather than a formatted time value.
Syntax:
convert source to formatName {and formatName}
The possible values you can use for formatName are shown in the Format Name column in the following table.
Format Name | Format | Example Value |
---|---|---|
date | [mo]/[da]/[yr] | 11/09/04 |
short date | [m]/[d]/[yr] | 11/9/04 |
long date | [weekday], [monthName] [day], [year] | Tuesday, November 9, 2004 |
abbreviated date | [wkday], [mon] [day], [year] | Tue, Nov 9, 2004 |
time | [hr12]:[mi] [pm] | 03:17 PM |
short time | [hr12]:[mi] | 03:17 |
long time | [hr12]:[mi]:[se] [pm] | 03:17:25 PM |
abbreviated time | [hr12]:[mi]:[se] | 03:17:25 |
local time | [hr12]:[mi] [pm] [timeZoneID] | 03:17 PM America/Denver |
short local time | [hr12]:[mi] [pm] [timeZone] | 03:17 PM -0700 |
long local time | [hr12]:[mi]:[se] [pm] [timeZoneID] | 03:17:25 PM America/Denver |
abbreviated local time | [hr12]:[mi]:[se] [pm] [timeZone] | 03:17:25 PM -0700 |
dateitems | [year],[mo],[da],[hr24],[mi],[se],[dayOfWeek] | 2004,11,09,15,17,25,2 |
short dateitems | [year],[mo],[da],[hr24],[mi],[se] | 2004,11,09,15,17,25 |
long dateitems | [year],[mo],[da],[hr24],[mi],[se],[dayOfWeek],[timeZoneID] | 2004,11,09,15,17,25,2, America/Denver |
abbreviated dateitems | [year],[mo],[da],[hr24],[mi],[se],[dayOfWeek],[timeZone] | 2004,11,09,15,17,25,2,-0700 |
simple date | [mo]/[da] | 11/09 |
short simple date | [m]/[d] | 11/9 |
long simple date | [monthName] [day] | November 9 |
abbreviated simple date | [mon] [day] | Nov 9 |
basic date | [mon] [day], [year] | Nov 9, 2004 |
short basic date | [mon] [day] [yr] | Nov 9 04 |
long basic date | [monthName] [day], [year] | November 9, 2004 |
abbreviated basic date | [monthName] [day] [yr] | November 9 04 |
basic time | [mon] [day], [year] [hr12]:[mi] [pm] | Nov 9, 2004 03:20 PM |
short basic time | [mon] [day] [yr] [hour12]:[mi] [pm] | Nov 9 04 3:20 PM |
long basic time | [monthName] [day], [year] [hr12]:[mi]:[se] [pm] | November 9, 2004 03:20:26 PM |
abbreviated basic time | [monthName] [day] [yr] [hr12]:[mi]:[se] [pm] | November 9 04 03:20:26 PM |
common date | [d] [mon] [year] | 9 Nov 2004 |
short common date | [d] [mon] [yr] | 9 Nov 04 |
long common date | [da] [monthName] [year] | 09 November 2004 |
abbreviated common date | [da] [mon] [year] | 09 Nov 2004 |
common time | [d] [mon] [year] [hr12]:[mi] [pm] | 9 Nov 2004 08:29 AM |
short common time | [d] [mon] [yr] [hour12]:[mi] [pm] | 9 Nov 04 08:29 AM |
long common time | [da] [monthName] [year] [hr12]:[mi]:[se] [pm] | 09 November 2004 08:29 AM |
abbreviated common time | [da] [mon] [year] [hr12]:[mi]:[se] [pm] | 09 Nov 2004 08:29 AM |
C time | [wkday] [mon] [day] [hr24]:[mi]:[se] [year] | Tue Nov 9 15:32:28 2004 |
short C time | [mon] [day] [hr24]:[mi] [year] | Nov 9 15:32 2004 |
long C time | [weekday] [monthName] [day] [hr24]:[mi]:[se] [year] | Tuesday November 9 15:32:28 2004 |
abbreviated C time | [mon] [day] [hr24]:[mi]:[se] [year] | Nov 9 15:32:28 2004 |
international date | [year]-[mo]-[da] | 2004-11-09 |
short international date | [year]-[mo] | 2004-11 |
long international date | [year]-[mo]-[da] | 2004-11-09 |
abbreviated international date | [year]-[mo] | 2004-11 |
international time | [year]-[mo]-[da]T[hr24]:[mi]:[se][timeZone] | 2004-11-09T08:29:25-0700 |
short international time | [year]-[mo]-[da]T[hr24]:[mi][timeZone] | 2004-11-09T08:29-0700 |
long international time | [year]-[mo]-[da]T[hr24]:[mi]:[se].[millisecond][timeZone] | 2004-11-09T08:29:25.894-0700 |
abbreviated international time | [year]-[mo]-[da] [hr24]:[mi]:[se] [timeZone] | 2004-11-09 08:29:25 -0700 |
internet date | [wkday], [day] [mon] [year] [hr24]:[mi]:[se] [timeZone] | Tue, 9 Nov 2004 08:29:25 -0700 |
short internet date | [day] [mon] [year] [hr24]:[mi] [timeZone] | 9 Nov 2004 08:29 -0700 |
long internet date | [day] [mon] [year] [hr24]:[mi] [timeZone] | Tuesday, 9 November 2004 08:29:25 -0700 |
abbreviated internet date | [day] [mon] [year] [hr24]:[mi]:[se] [timeZone] | 9 Nov 2004 08:29:25 -0700 |
UTC time or zulu time | [year]-[mo]-[da] [hr24]:[mi]:[se] [timeZone] | 2004-11-09 15:29:25 +0000 |
short UTC time or short zulu time | [hr24]:[mi] [timeZone] | 15:29 +0000 |
long UTC time or long zulu time | [year]-[mo]-[da] [hr24]:[mi]:[se].[millisecond] [timeZone] | 2004-11-09 15:29:25.000 +0000 |
abbreviated UTC time or abbreviated zulu time | [hr24]:[mi]:[se] [timeZone] | 15:29:25 +0000 |
military time | [da] [hr24][mi][timeZoneISO] [mon] [yr] | 09 1529Z Nov 04 |
short military time | [hr24][mi][timeZoneISO] | 1529Z |
long military time | [da] [hr24][mi][se][timeZoneISO] [mon] [yr] | 09 152925Z Nov 04 |
abbreviated military time | [da] [hr24][mi][timeZoneISO] | 09 1529Z |
seconds | fixed string, described above | 121732349 |
long seconds | fixed string, described above | 121732348.572803789 |
abbreviated seconds | fixed string, described above | 121732348.572804 |
short seconds | fixed string, described above | 121732348.573 |
Converting to any of the UTC
, zulu
, or military
time formats will also set the resulting value's time zone to UTC.
For complete information about how date/time formats are defined in SenseTalk, see SenseTalk Date and Time Formats.
Example:
convert "8/14/02" to long date // "8/14/02" is not a container, so this sets the value of 'it'
put it --> Wednesday, August 14, 2002
Example:
convert the time to short date and time // sets value of 'it'
put it --> 7/10/23 04:55 PM
Example:
convert expirationDate to date // changes expirationDate to use the standard date format
Example:
convert line 2 of file "/tmp/resultLog" to abbreviated local time
If the clockFormat
global property is set to 24 hour
, all time formats will use a 24-hour clock format (e.g., 15:17) instead of using AM or PM (e.g., 3:17 PM). For more information about this property, see Local and Global Properties for Working with Values.
The dateitems
formats can be especially useful for working with calendar dates. A date/time represented in dateitems
format consists of 7 numbers delimited by commas, representing the year, month, day, hour, minute, second, and day of the week (with 1 representing Sunday, and 7 representing Saturday). The long dateitems
and abbreviated dateitems
formats also include time zone information. The short dateitems
omits the day of the week.
Here is an example that uses dateitems
—a calculateAge function similar to one presented in the discussion of Helpers. This version takes advantage of dateitems
to handle leap years:
function calculateAge birthDate -- Calculate age in years for a given birthDate
convert birthDate to dateItems -- Change it to yr,mon,day,hr,min,sec
split birthDate by comma -- Convert to a list
convert the date to dateItems -- Today's date in 'it' as dateItems
split it by comma -- Convert to a list
subtract birthDate from it -- Subtract one list of values from the other
// If today's day of month is less than birthDate's, then subtract a month:
if item 3 of it < 0 then subtract 1 from item 2 of it
// Then if today's month is less than birthDate's, subtract a year:
if item 2 of it < 0 then subtract 1 from item 1 of it
return item 1 of it -- The difference in years
end calculateAge
The exact format of all of the date and time formats can be customized within a script by setting the appropriate properties within the timeFormat
global property, described in Global and Local Properties for Working with Values.
Basic Date
, Basic Time
Functions, Common Date
, Common Time
Functions, DateItems
Function, International Date
, International Time
Functions, Internet Date
Functions, Local Time
Functions, Simple Date
Functions, C Time
Functions, UTC Time
, Zulu Time
Functions, Military Time
Functions
Behavior: Each of these functions returns a formatted value representing either the current moment in time or a given moment in time, using a format that is unique to the particular function used. There are four variations of each function, using the function name alone, or preceded by one of the adjectives long
, short
, or abbreviated
(which can be shortened to abbrev
or abbr
). All of the different formats are shown in the table for the convert
command, above.
The basic date
formats begin with the month name (or abbreviated name) followed by the day, then the year. The basic time
formats add the time of day.
The common date
and common time
formats are similar to the basic
formats, but show the day before the month name rather than after it.
The dateItems
format presents a date and time as a comma-separated text list. The short dateItems
returns six items: the year, month, day, hour, minute, and second. The dateItems
(without an adjective) returns seven items, with the seventh being the day of the week (1-7, where Sunday is 1). The abbreviated dateItems
adds the timezone offset in HHMM format, and the long dateItems
returns that same information, but with the timezone name rather than offset. The value returned by the dateItems
function, when converted to text, will automatically display a formatted date. 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.
The international date
and international time
formats present the full date, the year and month, or the full date and time, in a manner that complies with the international ISO 8601 standard (see http://www.ietf.org/rfc/rfc3339.txt) except for the abbreviatedinternationaltime
, which presents a format used widely on the internet that varies slightly from the standard.
The internet date
formats present a date and time in a manner that complies with the date and time specification of the internet message format as defined in RFC 2822 (http://www.ietf.org/rfc/rfc2822.txt), except that the longinternetdate
shows full weekday and month names.
The local time
formats present the current time of day, including time zone information.
The simple date
formats present the date in a very simple format that includes only the month and day but omits the year.
The C time
(or CTime
) formats present the date and time in a format used by some C-based systems (including Python).
The UTC time
(or zulu time
) formats present the date and time in a standard format like the international time
formats. However, these functions specifically return the value in the UTC time zone.
The military time
formats are based on the US military's Date Time Group formats. These functions always return the value in the UTC time zone.
Syntax:
the { [ long | short | abbr{ev{iated}} ] } basic [date | time] {of dateExpr}
the { [ long | short | abbr{ev{iated}} ] } common [date | time] {of dateExpr}
the { [ long | short | abbr{ev{iated}} ] } dateItems {of dateExpr}
the { [ long | short | abbr{ev{iated}} ] } international [date | time] {of dateExpr}
the { [ long | short | abbr{ev{iated}} ] } internet date {of dateExpr}
the { [ long | short | abbr{ev{iated}} ] } local time {of dateExpr}
the { [ long | short | abbr{ev{iated}} ] } simple date {of dateExpr}
the { [ long | short | abbr{ev{iated}} ] } [c time | ctime] {of dateExpr}
the { [ long | short | abbr{ev{iated}} ] } [utc | zulu] time {of dateExpr}
the { [ long | short | abbr{ev{iated}} ] } military time {of dateExpr}
Example:
put the basic date --> Jan 4, 2008
put the basic date of "10/2/1869" --> Oct 2, 1869
put the long basic date --> January 4, 2008
put the basic time --> Jan 4, 2008 03:20 PM
Example:
put the common date --> 4 Jan 2008
put the common time --> 4 Jan 2008 03:20 PM
Example:
put the simple date --> 01/04
put the long simple date --> January 4
Example:
put the dateitems --> "1995,10,07,17,50,22,7"
put the short dateitems --> "1995,10,07,17,50,22"
put the abbrev dateitems --> "1995,10,07,17,50,22,6,-0600"
put the long dateitems --> "1995,10,07,17,50,22,6,America/Denver"
put dateitems("May 14, 1942") --> "1942,05,14,12,00,00,5"
Example:
put the international date --> 2005-10-19
put the short international date --> 2005-10
put the international time --> 2005-10-19T18:32:31-0600
put the abbrev international time --> 2005-10-19 18:32:31 -0600
Example:
put the internet date --> Wed, 19 Oct 2005 18:21:47 -0600
put the short internet date --> 19 Oct 2005 18:21 -0600
put the long internet date --> Wednesday, 19 October 2005 18:21:47 -0600
Example:
put the local time --> 05:42 PM -0700
put the short local time --> 05:42 PM US/Mountain
put the long local time --> 05:42:12 PM US/Mountain
Example:
put the C time --> Fri Sep 17 13:38:17 2010
put the long CTime --> Friday September 17 13:39:48 2010
Example:
put the UTC time --> 2022-04-11 15:18:29 +0000
put the long UTC time --> 2022-04-11 15:18:29.312 +0000
put the short Zulu time --> 15:18 +0000
put the abbrev UTC time --> 15:18:29 +0000
Example:
put the military time --> 11 1518Z Apr 22
put the long military time --> 11 151829Z Apr 22
put the short military time --> 1518Z
put the abbrev military time --> 11 1518Z
The value returned by each of these functions contains both a number and a format. When used as text, it will automatically be presented in the format shown in the table for the convert
command, above. The returned value may also be treated as a number, for use in date/time calculations. When called without a parameter, the numeric value represents noon on the current date (for the date
functions), or the exact date and time when the function was called (for the time
functions).
When a dateExpr is given, that expression is evaluated as a date and/or time, and the value returned will represent that date and time (or noon on that date, for the date
functions).
Related:
- The
Date
Function - The
Time
Function - The
DateItems
Function - The
FormattedTime
Function The TimeFormat
Global Property
FormattedTime
Function
Behavior: The formattedTime
function returns a date/time value using a custom format that you supply. An optional second parameter is the date/time that you would like to format. If a date/time value is not given, the result is the current time, using the supplied format.
For complete information about how to write date/time formats in SenseTalk, see SenseTalk Date and Time Formats.
Syntax:
the formattedTime of customFormat
formattedTime( customFormat {,dateTimeValue} )
Example:
put formattedTime("Calendar for [year]") into calendarTitle
Example:
put the formattedTime of "It is now day [day of year] of [year]!"
Example:
put formattedTime(the timeFormat's longDate, sentDt) into dateSent
Example:
put formattedTime("%Y%m%d_%H%M%S", logTime) into logFileName
Related:
Other Date and Time Functions
MonthNames
and WeekDayNames
Functions
**Behavior:**Use both functions when formatting dates:
- The
monthNames
function: Returns a list of all month names. - The
weekDayNames
function: Returns a list of the names of days of the week.
Both functions can be called using the adjectives long
, short
, and abbreviated
to return variations on these. In each case, the long form is the same as not specifying any adjective, the abbreviated form returns a list of three-letter abbreviations rather than the full name, and the short form returns numeric representations.
Syntax:
the { [ long | short | abbr{ev{iated}} ] } monthNames
monthNames()
the { [ long | short | abbr{ev{iated}} ] } weekDayNames
weekDayNames()
Example:
put monthNames() into monthList
Example:
put the abbreviated monthNames
Example:
put item dayNum of weekDayNames() into dayName
Example:
put the short weekDayNames -- displays the numbers 0 to 6
Related:
AvailableTimeZoneNames
Function
Behavior: The availableTimeZoneNames
function returns a list of time zone names known by the local operating system. These names are what SenseTalk recognizes within date/time strings wherever a time zone name is expected.
Because this function relies on information from the local system, you might see different results when you use it on different operating systems or OS versions.
Syntax:
the availableTimeZoneNames
availableTimeZoneNames()
Example:
Log the availableTimeZoneNames // Logs all time zone names known by the local operating system
Example:
Logs all time zones in the Americas:
put the availableTimeZoneNames into tznames
repeat with each item zone of tznames
if zone contains "America"
insert zone after AmerZones
end if
end repeat
log AmerZones.archive
Related:
AvailableTimeZoneAbbreviations
Function
Behavior: The availableTimeZoneAbbreviations
function returns a property list whose keys are time zone abbreviations. The corresponding value for each abbreviation is the name of the time zone that the abbreviation represents. The abbreviations are recognized within date/time strings wherever a time zone name is expected.
The availableTimeZoneAbbreviations
function returns information from the local operating system. However, not every time zone recognized by the OS necessarily has a corresponding abbreviation. Therefore, the availableTimeZoneAbbreviations
function might not include all time zones returned by the availableTimeZoneNames
function.
Syntax:
the availableTimeZoneAbbreviations
availableTimeZoneAbbreviations()
Example:
put availableTimeZoneAbbreviations() // Returns a property list whose keys are the recognized time zone abbreviations
Example:
Logs the key and name of all time zones in the Americas:
put availableTimeZoneAbbreviations() into TimeZoneAbbrev
repeat with each item x of keys(TimeZoneAbbrev)
put x & ": " & property (x) of TimeZoneAbbrev into timeZonesAmericas
If timeZonesAmericas contains "America"
log timeZonesAmericas
End If
end repeat
Related:
Date and Time Properties
Each date/time value has a display format associated with it. It is also associated with a specific time zone (normally the local time zone when the date/time value was created). These aspects of a date/time value can be accessed and changed using the following properties.
Format
Property
Behavior: The display format of a date/time value can be accessed directly by using the format
property of the value. If the value is stored in a variable, the format property can also be set.
Syntax:
the format of dateTimeValue
dateTimeValue.format
dateTimeValue's format
Example:
put date().format --> [mo]/[da]/[yr]
Example:
put (long date).format --> [weekday], [monthName] [day], [year]
Example:
set the format of dueDate to the timeFormat.InternationalDate
Related:
TimeZone
, TimeZoneAbbreviation
, TimeZoneOffset
Properties
Behavior: The time zone of a date/time value can be accessed using the TimeZone
, TimeZoneAbbreviation
(also TimeZoneAbbrev
or TimeZoneAbbr
), or TimeZoneOffset
property of the value. If the value is stored in a variable, these properties can also be set, to convert the value to a different time zone.
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 [ TimeZone | TimeZoneAbbreviation | TimeZoneOffset ] of dateTimeValue
dateTimeValue.[ TimeZone | TimeZoneAbbreviation | TimeZoneOffset ]
dateTimeValue's [ TimeZone | TimeZoneAbbreviation | TimeZoneOffset ]
Example:
put date().timeZone --> America/Denver
put date().timeZoneAbbreviation --> MDT
put date()'s timeZoneOffset--> -6 hours
Example:
put now into aTime // store the current time into a variable
put aTime --> 2022-04-12 17:41:58 -0600
put aTime's timeZone --> America/Denver
put aTime's timeZoneOffset --> -6 hours
set aTime's timeZoneOffset to -2 hours // change to a different time zone
put aTime --> 2022-04-12 21:41:58 -0200 (the same point in time, shown in the new time zone)
set aTime.timeZoneAbbreviation to "GMT" // a different way to change the time zone
put aTime --> 2022-04-12 23:41:58 +0000
set aTime's timeZone to "athens"
put aTime.timeZone --> Europe/Athens
put aTime's timeZoneOffset --> 3 hours
put aTime --> 2022-04-13 02:41:58 +0300 (note the date change)
set aTime's timeZone to "denver" // return to the original time zone
put aTime --> 2022-04-12 17:41:58 -0600 (note the actual moment in time has never changed)
Related: