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.

note

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:

• The Time Function
• The Seconds Function
• the timeFormat Global Property

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:

• TimeZoneOffset Property

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:

• The Date Function
• The Time Function
• The Ticks Function

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:

• The Seconds Function

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

Tech Talk

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:

• The Date Function
• The Seconds Function

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 hour
• the 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:

• The Date Function
• The Year Function
• The Month Function
• The Day Function
• The WeekdayName Function

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:

• The Time Function
• The Minute Function
• The Second Function
• The Seconds Function

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:

• The Time Function
• The Hour Function
• The Second Function
• The Seconds Function

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

note

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 and Microsecond 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:

• The Time Function
• The Hour Function
• The Second Function
• The Seconds Function

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

note

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:

• Convert Command
• The TimeFormat Global Property
• SenseTalk Date and Time Formats

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:

• The FormattedTime Function
• The Convert Command
• The MonthName Function
• The WeekdayName Function

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.

note

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
• Time, AsTime Functions

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.

note

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:

• AvailableTimeZoneNames Function
• Time, AsTime Functions

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:

• SenseTalk Date and Time Formats

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:

• TimeZoneOffset Function