13.6. Date

A date is a date-time. A literal date is an object string specifier . In constructing a date, you may use any string value that can be interpreted as a date, a time, or a date-time; AppleScript (or more probably the system) is quite liberal in what it will accept, provided that the string makes sense in terms of the date and time format settings in your International System Preferences . AppleScript supplies missing values such as today's date (if you give only a time) or this year (if you don't give a year) or midnight (if you give only a date). To form a date object for the current date-time, use the current date scripting addition command (see Chapter 21).

AppleScript presents a literal date specifier in long date-time format in accordance with your International preferences. It does this even within your script, on decompilation, if you use a literal string in a date specifier:

date "5/25/2005" -- rewritten: date "Wednesday, May 25, 2005 12:00:00 AM"

If the expression "5/25/2005" isn't a date according to your International preferences, this code won't compile. For example, if you have U.K. settings, you'd need to type date "25/5/2005". Scripts that form dates dynamically by coercing from a string, like most of the examples in this section, are subject to the same caveat (and are thus not very portable).

AppleScript knows nothing of time zones , and assumes the Gregorian calendar even for dates before its invention. An attempt to form a date specifier earlier than the start of 1000 AD will fail:

set s to "December 25, 800"
date s -- date "Monday, December 25, 2800 12:00:00 AM"

Confusingly, however, you can obtain such a date by calculation:

set s to "December 25, 1000"
set d to date s
set year of d to 800
d -- date "Monday, December 25, 0800 12:00:00 AM"

Internally, a date is stored as a number of seconds; precision higher than a second is thrown away during calculation. There are three ways to do calculations with dates:

Date arithmetic

You can derive one date from another by adding or subtracting a number representing seconds. (Chapter 16 lists some global properties that can help you calculate the desired number of seconds.) One date may also be subtracted from another to obtain the number of seconds between them. For example:

set s to "8/10/2005 4:45 PM"
(date s) + 56845 -- date "Thursday, August 11, 2005 8:32:25 AM"

Date specifier property

By a curious syntax, a new time part or date part may be combined with an existing date by treating a date specifer as a property of another date. The result is a new date object. For example:

set s to "2/25"
set d to date s -- date "Friday, February 25, 2005 12:00:00 AM"
set d2 to date "10:30" of d -- date "Friday, February 25, 2005 10:30:00 AM"
set d3 to date "1/24" of d2 -- date "Monday, January 24, 2005 10:30:00 AM"

Date properties

Setting a property of a date mutates the date in place. You can change a property in a calendrically impossible way, and AppleScript will compensate:

set s to "May 31"
set d to date s
set month of d to June
d -- date "Friday, July 1, 2005 12:00:00 AM"

Now that a date has hours , minutes , and seconds properties (new in Tiger), this technique is actually useful for date calculations:

set s to "8/10/2005 10:00 PM"
set d to date s
set hours of d to ((hours of d) + 100)
d -- date "Monday, August 15, 2005 2:00:00 AM"

When you use set (as opposed to copy) to set a variable to a value that is a date, you set the variable by reference. This means that the date is not copied; the variable's name becomes a new name for the date, in addition to any names for the date that may already exist. The same is true when a date is passed as a parameter to a handler. This special treatment is in common between lists, records, dates, and script objects, the four datatypes that can be mutated in place. (See "Set by Reference" in Chapter 7 and "Pass by Reference" in Chapter 9.)

For example:

set s to "May 31"
set d to date s
set d2 to d
set month 
 of d2 to June
d -- date "Friday, July 1, 2005 12:00:00 AM"

13.6.1. Date Properties

The following are the properties of a date value:

year

The year number. A positive integer.

month

The month. A constant (not a string!): January, February, and so on. However, you can set a date's month using an integer (this is new in Tiger).

day

The day of the month. A positive integer.

hours

Whole hours since the start of the day (at midnight). A positive integer.

minutes

Whole minutes since the start of the hour. A positive integer.

seconds

Seconds since the start of the minute. A positive integer (hours, minutes, and seconds are new in Tiger).

time

Seconds since the start of the day (at midnight). A positive integer.

weekday

A constant (not a string!): Monday, Tuesday, and so on. In practice this property is read-only; setting it is not an error, but it has no effect.

date string

short date string

time string

A string consisting of just the date or time part of the date-time. In practice these properties are read-only; setting them results in a stack overflow (I'd have to call that a bug). They are formatted in accordance with your International preferences.

The time string and date string are suitable for combining with an existing date to form a new date, using the syntax described earlier. For example:

set s to "5/25/2005"
set d1 to date s
set t to "4PM"
set d2 to date t
set d3 to date (time string of d2) of d1 -- date "Wednesday, May 25, 2005 4:00:00 PM"