3.12. Dates

Dates are instances of a special class |DATE| . This facility is built on top of various system functions which are themselves based on a count of seconds since January 1st, 1970. Most systems are able to handle a date between 1910 and 2030.

Date are stored using several formats depending of their accuracy. Each format is defined as a range over various components of a date: year , month , day , hour , minute , second .

For instance, a date `` year to day '' identifies any single day between 1910 and 2030.
Similarly, a date `` year to second '' identifies any single second in the same interval.
A date `` hour to minute '' identifies any single minute within a day.

Finally we have defined a standard way to numerically encode dates: The possibly fractional number of days (daynumber) since January 1st, 1970 at zero hour local.

3.12.0. (date-to-day date)

[DX]

Returns the possibly fractional number of days between January 1st, 1970 and the specified date .

? (date-to-day (string-to-date "1993-12-04" 'year 'day))
= 8738

? (date-to-day (now))
= 15015.9551

3.12.1. (day-to-date daynumber)

[DX]

Builds a date string from a possibly fractional day number.

? (day-to-date 8738)
= ::DATE:year-second:(1993-12-04 00:00:00)

? (day-to-date 8738.23)
= ::DATE:year-second:(1993-12-04 05:31:11)

3.12.2. (today)

[DX]

Returns today's date at zero hour as a date `` year to day ''

? (today)
= ::DATE:year-day:(2011-02-10)

3.12.3. (now)

[DX]

Returns today's date and now's time as a date `` year to second ''

? (now)
= ::DATE:year-second:(2011-02-10 22:55:23)

3.12.4. (split-date date)

[DX]

Returns an alist contaning all the components of a date date . Each component can be accessed using function assoc . The following components are provided:

  <year>:       The year (minus 1900).
  <month>:       The month number (0..11).
  <day>:       The day of the month (1..31).
  <hour>:       The hour (0..23).
  <minute>:       The number of minutes (0..59).
  <second>:       The number of seconds.
  <wday>:       The day of the week (0..6).
  <yday>:       The day of the year (1..366).

These items are present if the resolution of the date object allows it. The last two items require at least a date `` year to day ''

? (split-date (now))
= ((year . 111) (month . 2) (day . 10) (hour . 22) (minute . 55) (second . 23)
    (wday . 4) (yday . 40) )

? (split-date (today))
= ((year . 111) (month . 2) (day . 10) (wday . 4) (yday . 40))

3.12.5. (date-type date)

[DX]

This function returns a string describing the current resolution of a date date as a list of two symbols chosen in year , month , day , hour , minute , second .

? (date-type (today))
= (year day)

? (date-type (now))
= (year second)

3.12.6. (date-extend date from to)

[DX]

This function returns a new date equivalent to date with the resolution specified by the two symbols from and to which may be any of year , month , day , hour , minute , second .

Reducing the resolution of a date is achieved by truncating unneeded components. Extending the resolution of a date towards more accuracy is achieved by inserting zeroes. Extending the resolution of a date towards fields of larger magnitude is achieved by inserting the current year, month, day, etc...

? (date-extend (now) 'year 'minute)
= ::DATE:year-minute:(2011-02-10 22:55)

? (date-extend (date-extend (now) 'year 'minute) 'hour 'second)
= ::DATE:hour-second:(22:55:00)

3.12.7. (date-to-string date [format])

[DX]

Format a date date according to format .

Argument format is a format string reminiscent of printf . When argument format is omitted, a regular ANSI string is produced.

       YYYY-MM-DD HH:MM:SS              for <year> to <second>
       YYYY-MM-DD                     for <year> to <day>
       MM-DD HH:MM                     for <month> to <minute>

The format for date-to-string is a character string that consists of field descriptors and text characters, reminiscent of printf . Each field descriptor consists of a % character followd by another character that specifies the replacement for the field descriptor. All other characters are copied from fmt into the result. The following field descriptors are supported:

%%: Same as %.
%a: Day of week, using locale's abbreviated weekday names.
%A: Day of week, using locale's full weekday names.
%b,%h: Month, using locale's abbreviated month names.
%B: Month, using locale's full month names.
%c: Date and time as %x %X.
%C: Date and time, in locale's long-format date and time representation.
%d: Day of month (01-31).
%D: Date as %m/%d/%y.
%e: Day of month (1-31; single digits are preceded by a blank).
%H: Hour (00-23).
%I: Hour (00-12).
%j: Day number of year (001-366).
%k: Hour (0-23; single digits are preceded by a blank).
%l: Hour (1-12; single digits are preceded by a blank).
%m: Month number (01-12).
%M: Minute (00-59).
%n: Same as \n.
%p: Locale's equivalent of AM or PM.
%r: Time as %I:%M:%S %p.
%R: Time as %H:%M.
%S: Seconds (00-59).
%t: Same as \t.
%T: Time as %H:%M:%S.
%U: Week number of year (01-52), Sunday is the first day of the week.
%w: Day of week; Sunday is day 0.
%W: Week number of year (01-52), Monday is the first day of the week.
%x: Date, using locale's date format.
%X: Time, using locale's time format.
%y: Year within century (00-99).
%Y: Year, including century (for example, 1988).

The difference between %U and %W lies in which day is counted as the first day of the week. Week number 01 is the first week with four or more January days in it.

? (date-to-string (today))
= "2011-02-10"

? (date-to-string (now))
= "2011-02-10 22:55:23"

? (date-to-string (now) "%C %X")
= "20 10:55:23 PM"

3.12.8. (string-to-date string [from to])

[DX]

Function string-to-date converts the ansi date string string to a date using the resolution specified by from and to .

Argument from and to are symbols specifying the resolution of the target date. They may be any of the following symbols: year , month , day , hour , minute , second . When these arguments are ommited, a date `` year to second '' is assumed.

Abbreviated dates are handled by filling the leftmost fields with the current date and the rightmost fields with zeroes.

? (string-to-date "1993-12-12 8:30" 'year 'minute)
= ::DATE:year-minute:(1993-12-12 08:30)

3.12.9. (date-add-second date count)

[DX]

This function adds count seconds to date date .

? (date-add-second (now) 67)
= ::DATE:year-second:(2011-02-10 22:56:30)

3.12.10. (date-add-minute date count)

[DX]

This function adds count minutes to date date .

? (date-add-minute (now) 67)
= ::DATE:year-second:(2011-02-11 00:02:23)

3.12.11. (date-add-hour date count)

[DX]

This function adds count hours to date date .

? (date-add-hour (now) 67)
= ::DATE:year-second:(2011-02-13 17:55:23)

3.12.12. (date-add-day date count)

[DX]

This function adds count days to date date .

? (date-add-day (now) 67)
= ::DATE:year-second:(2011-04-18 22:55:23)

3.12.13. (date-add-month date count [opt])

[DX]

This function adds count months to date date .

This is tricky because months have different lengths. Adding an integral number of month to certain dates may produce an illegal day number for the target month. (eg. (date-add-month "1996-05-31" 1) ). The behavior of this function is therefore further specified by the value of optional argument opt .

When opt is nil or omitted, this function generates a Lush error whenever the answer would be an illegal date.
When opt is 'no-error , this function returns the empty list () whenever the answer would be an illegal date.
When opt is 'end-of-month , this function always returns the last day of the target month regardless of the specified day number.
When opt takes any other value (eg. 'loosely or t ) this function always returns a legal date. Answers with oversized day numbers are corrected by returning the last day of the target month.

? (date-add-month (now) -2 t)
= ::DATE:year-second:(2010-12-10 22:55:23)

3.12.14. (date-add-year date count [opt])

[DX]

This function adds count months to date date .

This is tricky because adding an integral number of years to february 29th dates may produce an illegal date. The behavior of this function is therefore further specified by the value of optional argument opt .

When opt is nil or omitted, this function generates a Lush error whenever the answer would be an illegal date.
When opt is 'no-error , this function returns the empty list () whenever the answer would be an illegal date.
When opt takes any other value (eg. 'loosely or t ) this function always returns a legal date. The day number is changed to 28 whenever the answer would be the february 29th during a non leap year.

? (date-add-year (now) 2 t)
= ::DATE:year-second:(2013-02-10 22:55:23)

3.12.15. (date-code date flags)

[DX]

This function returns a list of numbers encoding a date date suitably for a statistical analysis. Argument flag is an integer composed by oring (using bitor for instance) the following constants controlling which values to generate:

1: One value representing the number of days since January 1st, 1970.
16: Two values encoding a point moving on the unit circle once a day.
8: Two values encoding a point moving on the unit circle once a week.
4: Two values encoding a point moving on the unit circle once a month.
2: Two values encoding a point moving on the unit circle once a year.

These components are generated only if they make sense with the resolution of the date date .

? (date-code (now) 24)
= (0.9605 -0.2782 -0.2616 -0.9652)

? (date-code (today) 31)
= (15015 Nan Nan -0.901 -0.4339 -0.4339 0.901 0.7722 0.6354)