13.3 Date

A date is a date-time. For the practical limits on the range of dates that can be expressed, see the year property later in this section. AppleScript knows nothing of time zones, and assumes the Gregorian calendar even for dates before its invention.

A literal date is an object string specifier (see Chapter 10). 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 the string makes sense in terms of your date and time format settings in the International pane of System Preferences. AppleScript will supply 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).

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

date "5/25/2003" -- rewritten: date "Sunday, May 25, 2003 12:00:00 AM"

If the expression "5/25/2003" isn't a date according to your International preferences, this code won't compile. For example, if you have UK settings, you'd need to type date "25/5/2003".

Having obtained a date one way or another, you can then derive a new date from it in two ways. One is by date arithmetic, which involves adding and subtracting seconds. (See Chapter 15 and Chapter 17 for some constants that can help you calculate the desired number of seconds.) The other is to combine a new time part or date part with the existing date; this is done by an odd syntax that treats a date specifier as a property of another date:

date dateOrTimeString of date

For example:

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

Again, notice that this code will compile but not run on a machine with UK settings. Scripts that form dates dynamically by coercing from a string are thus not very portable.

You can also alter a date in place by changing one of its properties. AppleScript (or more probably the System) will compensate when you change a property in a calendrically impossible way:

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

When you use set (as opposed to copy) to set a variable to a value which 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. (See Section 8.4 and Section 9.5.1.)

For example:

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

13.3.1 Date Properties

The following are the properties of a date value:

year

A positive integer. You can't express BCE dates. The mathematical range limit on the year seems to be 100-9999.

month

A constant (not a string!): January, February, and so on.

day

A positive integer.

time

An integer; the number of seconds since midnight represented by the date's time part.

weekday

A constant (not a string!): Monday, Tuesday, and so on. In practice this property is read-only; there's no penalty for setting it, but trying to set a date's weekday to a weekday that isn't accurate for that date 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 preference pane settings.

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

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