REBOL 3 Datatypes: Date!

Concept

Around the world, dates are written in a variety of formats. However, most countries use the day-month-year format. One of the few exceptions is the United States, which commonly uses a month-day-year format. For example, a date written numerically as 2/1/1999 is ambiguous. The month could be interpreted as either February or January. Some countries use a dash (-), some use a forward slash (/), and others use a period (.) as a separator. Finally, computer people often prefer dates in the year-month-day (ISO) format so they can be easily sorted.

Format

The REBOL language is flexible, allowing date! datatypes to be expressed in a variety of formats. For example, the first day of March can be expressed in any of the following formats:

probe 1/3/1999
1-Mar-1999

probe 1-3-1999
1-Mar-1999

probe 1999-3-1  ;ISO format
1-Mar-1999

The year can span up to 9999 and down to 1. Leap days (February 29) can only be written for leap years:

probe 29-2-2000
29-Feb-2000

The fields of dates can be separated with forward slashes (/) or dashes (-). Dates can be written in either a year-month-day format or a day-month-year format:

probe 1999-10-5
5-Oct-1999

probe 1999/10/5
5-Oct-1999

probe 5-10-1999
5-Oct-1999

probe 5/10/1999
5-Oct-1999

Because the international date formats that are not widely used in the USA, a month name or month abbreviation can also be used:

probe 5/Oct/1999
5-Oct-1999

probe 5-October-1999
5-Oct-1999

probe 1999/oct/5
5-Oct-1999

When the year is the last field, it can be written as either a four digit or two digit number:

probe 5/oct/99
5-Oct-1999

probe 5/oct/1999
5-Oct-1999

However, it is preferred to write the year in full. Otherwise, problems occur with date comparison and sorting operations. While two digits can be used to express a year, the interpretation of a two-digit year is relative to the current year and is only valid for 50 years in the future or in the past:

probe 28-2-66   ; refers to 1966
28-Feb-1966

probe 12-Mar-20 ; refers to 2020
12-Mar-2020

probe 11==45   ; refers to 2045, not 1945
11-Mar-2045

It is recommended to use a four-digit year to avoid potential problems.

To represent dates in the first century (which is rarely done because the Gregorian calendar did not exist), use leading zeros to represent the century (as in 9-4-0029).

Dates can also include an optional time field and an optional time zone. The time is separated from the date with a forward slash (/). The time zone is appended using a plus (+) or minus (-), and no spaces are allowed. Time zones are written as a time shift (plus or minus) from GMT. The resolution of the time zone is to the half hour. If the time shift is an integer, it is assumed to be hours:

probe 4/Apr/2000/6:00+8:00
4-Apr-2000/6:00+8:00

probe 1999-10-2/2:00-4:00
2-Oct-1999/2:00-4:00

probe 1/1/1990/12:20:25-6
1-Jan-1990/12:20:25

There can be no spaces within the date. For example:

10 - 5 - 99

would be interpreted as a subtraction expression, not a date.

Access

Refinements can be used with a date value to get any of its defined fields:

Refinement	Description
/day	Gets the day.
/month	Gets the month.
/year	Gets the year.
/yearday	Gets the day of the year.
/weekday	Gets the weekday (1 for Mon, 7 for Sun).
/time	Gets the time (if present).
/hour	Gets the time's hour (if present)
/minute	Gets the time's minute (if present).
/second	Gets the time's second (if present).
/zone	Gets the time zone (if present).
/utc	Returns the UTC (universal) time.

Here's how these refinements work:

some-date: 29-Feb-2000
probe some-date/day
29

probe some-date/month
2

probe some-date/year
2000

days: ["Mon" "Tue" "Wed" "Thu" "Fri" "Sat" "Sun"]
probe pick days some-date/weekday
Tue

When a time is present, the time related refinements can be used. The /hour, /minute and /second refinements are used with the /time refinement that isolates the time segment of the date value for them to work on, but they can also be used alone:

lost-time: 29-Feb-2000/11:33:22.14-8:00
probe lost-time/time
11:33:22.14

probe lost-time/time/hour
11

probe lost-time/hour
11

probe lost-time/minute
33

probe lost-time/second
22.14

probe lost-time/zone
-8:00

Note that dates are normalized when any field of their time values is set. The date will be adjusted accordingly to make the time a valid 24 hour value.

print d: now
23-Oct-2009/3:34:45-4:00

d/time: 50:00
print d
25-Oct-2009/2:00-4:00

Creation

Use the to-date function to convert values to a date!:

probe to-date "5-10-1999"
5-Oct-1999

probe to-date "5 10 1999 10:30"
5-Oct-1999/10:30

probe to-date [1999 10 5]
5-Oct-1999

probe to-date [5 10 1999 10:30 -8:00]
5-Oct-1999/10:30-8:00

[!Note When converting to a date!, the year must be specified as four digits.

Conversions can be applied to various math operations on dates:

probe 5-Oct-1999 + 1
6-Oct-1999

probe 5-10-1999 - 10
25-Sep-1999

probe 5-Oct-1999/23:00 + 5:00
6-Oct-1999/4:00

Disabling timezone or using UTC

To disable the timezone, just set it to none! :

date/zone: none

However, since this normally indicates a UTC datestamp, it is better to use the /utc refinement. You can write:

date: date/utc

For example:

date: now
19-Sep-2009/20:04:26-7:00

date: date/utc
20-Sep-2009/3:04:26

Note that the timezone is gone.

A REBOL 2 compatible way to do this is:

date: now
19-Sep-2009/20:04:26-7:00

date: date - date/zone
20-Sep-2009/3:04:26-7:00

date/zone: none
none

date
20-Sep-2009/3:04:26

Use date? to determine whether a value is a date! datatype.

probe date? 5/1/1999
true

The related function [bad-link:functions/to-idate.txt] returns a standard Internet date string. The Internet date format is day, date, month, year, time (24-hour clock), and time zone offset from GMT.

probe to-idate now
Fri, 30 Jun 2000 14:42:26 -0700

The now function returns the current date and time in full format including the time zone offset:

probe now
30-Jun-2000/14:42:26-7:00