Allowed coercions

list with one item

string

Syntax

set dateVar to date "January 1, 2000"

Description

You can use strings to express several different forms of date expressions. But AppleScript will not store the value as a date object unless you precede the string with the date keyword:

set theDate to date "1/1/2000"

It is very easy to forget to include the date keyword; if you leave it out, the variable will be set to a string and will not contain any of the date object's properties (e.g., Time String).

This example uses the current date scripting addition to return a date object. The script shows the code's return value within comment characters ("(* *)"):

set theDate to current date

(*date "Friday, November 12, 1999 8:22:11 AM" *)

Once you have a valid date object, then you can obtain the values of several properties from it:

Class

date

Date String

The date not including the time value ("Friday, November 12, 1999")

Day

An integer that represents the day of the month, as in 12 for "November 12"

Month

Represents one of the following constants:

January	July
February	August
March	September
April	October
May	November
June	December

Time

An integer representing the number of seconds since midnight

Time String

Gets the time from the date object in string form ("8:22:11 AM")

Weekday

Stored in one of the following constants:

Monday	Tuesday
Wednesday	Thursday
Friday	Saturday
Sunday

Year

An integer representing the year

If you create a date object from a literal string, then AppleScript will always fill in a default property value (such as for the Time property) if the literal string does not provide one. Here's an example of a bare-bones date value and what the object actually looks like under the surface after AppleScript has filled in the default values:

set myDate to date "1/1/2000"

return myDate -- looks like date "Saturday, January 1, 2000 12:00:00 AM"

If you do not supply a time value, then AppleScript will set the time as midnight for that day ("12:00 AM"). If you create a date object but supply only a time value, but not the date:

set myDate to date "17:00"

then AppleScript will set the date of the object to the date when the script was compiled. In other words, the date object always has a property value for the date or time, even if you have not provided one upon object creation.

AppleScript allows you to use the following constants in date calculations:

days

Equals 24 * hours

hours

Equals 60 * minutes

minutes

Equals 60 * seconds

weeks

Equals 7 * days

AppleScript Pivot Dates As everyone learned from the Y2K furor, it is not a good idea for an application to accept the year portion of dates as two digits (e.g., "01") instead of four ("2001"). Always use four digits when you create AppleScript date objects. However, imagine that you are using an AppleScript to pull date strings from an old text or database file that represents dates such as "09/09/87." What is "87"—1987" or "2087"? Here is how AppleScript handles the so-called pivot dates, where the two-digit century is interpreted relative to the current year: If the current date is between and 10 (as it is now, 2001), a two-digit date with a year value between 00 and 90 is considered in the current century. A date with a year value from 91 to 99 is represented as in the previous century. So the year portion of "1/1/10" is represented as "2010," and the year of "1/1/95" is considered "1995." If the current two-digit year falls between 11 and 90 (as in 2011), then any year in the 00 to 99 range is considered in the current century. In 2011, then, the year part of the date string "1/20/45" would evaluate to "2045." If the current year is late in the century, as in "1999," then any two-year dates from 00 to 10 are considered in the next century. All the other two-year dates are represented as in the current century.

Examples

If you compiled and saved the expression:

set myDate to date "17:00"

on January 20, 2000, then the myDate date object would look like this:

date "Thursday, January 20, 2000 5:00:00 PM"

Scripters work a lot with date objects. You can perform addition and subtraction with dates, for instance. The following example tells you when a project with a six-month deadline is due, based on the date when you signed the project contract:

set userInput to (display dialog "When did you sign the contract?"¬ 

default answer ((current date) as string))

set contractDate to date (text returned of userInput)

set projectDue to date (contractDate + (180 * days))

set amessage to "Brace yourself, your project is due on " & projectDue

display dialog amessage

It first asks the user for the contract-signing date by using the display dialog scripting addition. The code then displays a text field to request user input. In this case, I use a date string returned from the current date scripting addition (the return value is coerced to a string) as the default answer. For the sake of clarity and keeping the example short, I have not tested what the user has entered into the text field to make sure that the value is a valid date string. Any final program should test the input value for validity. The contractDate variable takes the string returned from the display dialog window (text returned of userInput) and coerces it to a date object. Then the script roughly calculates six months as: 180 * days (days is a constant that equals 24 * hours). This calculated value is added to the contractDate date object to get a date representing six months from the contract date. It stores this value in the projectDue date variable. The final two lines create and display a message dialog box notifying the user when their project is due. The following segment:

set amessage to "Brace yourself, your project is due on " & projectDue

shows how the scripter can concatenate a date object to a string, and AppleScript will coerce the date object to a string for you.

A scripter can also use the Time property of a date object to calculate elapsed time in seconds. The next example uses the Time property to calculate how long it takes the prior example to run (including how long the user takes to fill in and dismiss the dialog box). A code-timing function using the Time property of date objects is a useful addition to a scripter's function library:

set codeStart to (time of (current date))

set userInput to (display dialog "When did you sign the contract?"¬ 

default answer ((current date) as string))

set contractDate to date (text returned of userInput)

set projectDue to date (contractDate + (180 * days))

set amessage to "Brace yourself, your project is due on " & projectDue

display dialog amessage

set codeEnd to (time of (current date))

set timeDif to (codeEnd - codeStart) as string

display dialog ("This code took " & timeDif & " seconds to run.")

Here are more examples of creating date objects:

set myDate to date "12/1/2000"

set myDate to date "December 1, 2000"

set myDate to date "12/1/2000 5:00 PM"

set myDate to date "12/1/2000 17:00"

set myDate to date "17:00"