ToC | DocOverview | CGDoc | RelNotes | FAQ | Index | PermutedIndex
| Allegro CL version 11.0

# add-duration

Generic Function, util.date-time package

Arguments: date-timespec durationspec

Returns a new date-time object obtained by adding the duration specified by durationspec to the date-time specified by date-timespec.

The default method does not add two durations.

    (require :datetime)
    (use-package :util.date-time)

     > (add-duration (date-time "1985-04-10T10:30:40") (duration "1MT1H4S"))
     #<date-time "1985-05-10T11:30:44" @ ...>

See date-time.html for information on support in Allegro CL for parsing and generating time expressions using the ISO 8601 standard. See particularly the section Adding/Subtracting Durations, where it is pointed out (with examples) that adding and subtracting durations are not inverse operations and adding durations is not associative.

# complete-date-time

Function, util.date-time package

Arguments: date-time

This function is called automatically by date-time when date-time's complete keyword argument is true.

This function updates its argument. If the datetime specifies one of Calendar date, a Week date, or an Ordinal date, then the other date types are calculated and stored in the argument. If the argument specifies a time, then the `hourf`, `minutef`, and `secondf` slots of the argument are calculated and stored in the argument.

Note that the function does not modify the conceptual date-time value of the argument. It merely computes the equivalent representations.

One may not want to call this function if one wants to maintain the slots in the argument as being a representation from the parser of the date-time function. In this case, the complete keyword argument to date-time (the function that does the parsing) should be `nil` to prevent this function from being called.

#### Examples

    (require :datetime)
    (use-package :util.date-time)

     (setq d (date-time "1985-04-12" :complete nil))
      => #<date-time "1985-04-12" @ ...>

     (date-time-ymd-day d) => 12

     ;; The date-time was not completed, so the following accessor returns nil.
     (date-time-yd-day d) => nil

     ;; Update the date-time instance.
     (complete-date-time d) =>  #<date-time "1985-04-12" @ ...>

     (date-time-yd-day d) => 102

See date-time.html for information on support in Allegro CL for parsing and generating time expressions using the ISO 8601 standard.

# date-time

Generic Function, util.date-time package

Arguments: date-timespec &key expanded-digits fraction-digits date start end complete

This function returns the date-time object denoted by the ISO-8601 date-timespec. Note that this function does not check the validity of its input. It is an error to pass invalid input to this function and the behavior in that case is undefined.

If date is false, then date-timespec is assumed only to represent a time of the day.

If expanded-digits is not `nil`, then the year is assumed to be expanded-digits + 4 digits long. Also, if expanded-digits is specified, then the year must be preceded by a plus-sign (+) or minus-sign (-). This is an ISO-8601 requirement.

If fraction-digits is not `nil`, then if a fraction is found in the time section, it is assumed to have exactly fraction-digits digits past the decimal point (either #, or #.).

If complete is false, then complete-date-time is not called. If complete is true, then the return value is the of calling complete-date-time on the parsed result.

The following ISO 8601 patterns are recognized:

For the date (Y indicates extra year digits, the number of which are specified by the expanded-digits argument):

    YYYYMMDD, YYYY-MM-DD, YYYY-MM, YYYY, YY, YYYYDDD, YYYY-DDD, YYYYWwwD,
    YYYY-Www-D, YYYYWww, YYYY-Www, YYMMDD, YY-MM-DD, -YYMM, -YY-MM, -YY,
    --MMDD, --MM-DD, --MM, ---DD, YYDDD, YY-DDD, -DDD, YYWwwD, YY-Www-D,
    YYWww, YY-Www, -YWwwD, -Y-Www-D, -YWww, -Y-Www, -WwwD, -Www-D, -Www,
    -W-D, +<Y>YYYY-MM-DD, -<Y>YYYY-MM-DD, +<Y>YYYY-DDD,
    -<Y>YYYY-DDD, +<Y>YYYY-Www-D, -<Y>YYYY-Www-D,
    +<Y>YYYY-Www, -<Y>YYYY-Www, +<Y>YYYY-MM,
    -<Y>YYYY-MM

For the time (s indicates extra digits, the number of which are specified by the fraction-digits argument):

    hhmmss, hh:mm:ss, hhmm, hh:mm, hh, hhmmss,s<s>, hh:mm:ss,s<s>,
    hhmm,m<m>, hh:mm,m<m>, hh,h<h>, -mmss, -mm:ss, -mm, --ss,
    -mmss,<s>, -mm:ss,<s>, -mm,<m>, --ss,<s>

For the zone: `hhmm, hh, hh:mm, Z` (`Z` stands for `Zulu`, an older designation of Greenwich Mean Time.)

Combinations:

    <Date>T<Time>+<Zone>  ;; except <Date>T<Time>Z for Z timezone designator
    <Date>T<Time>-<Zone>  ;; except <Date>T<Time>Z for Z timezone designator

A space (#\Space) can be substituted for T (#\T) in Date Time combination expressions.

### date-time slots

When the date-time object with fully specified date and time is initially created by this function, all slots are filled in as long as the complete keyword argument has its initial value, which is true. If complete is specified nil, only those slots whose values are in the ISO 8601 string are typically filled in and the remaining slot values are left as `nil`. Thus for the string "2003-017T10:10:10" (the seventeenth day of 2003 -- i.e. January 17 -- 10:10:10 AM), this call:

    (util.date-time:date-time "2003-017T10:10:10" :complete nil)

results in only the `ymd-yd-century`, `ymd-yd-year-in-century`, and `yd-day` having non-`nil` values among the date slots, along with `hour`, `minute`, and `second` among the time slots. The other slot values are all `nil`. Accessing those slots (by, say, calling date-time-ywd-day or date-time-hourf) does not cause the value to be calculated: `nil` is returned. Applying complete-date-time to an uncompleted date-time object (where all information is available) causes values to be calculated for unfilled slots.

Whether the date or the time is incompletely specified, then not all slots are filled even if the complete argument is called. Examples of incomplete ISO 8601 string include "03-017T10:10:10", where the year is incomplete, and "03-017T10:10", where the year is incomplete and the second value is not specified. The slots where information is specified have non-`nil` value. Many other slots do not have non-`nil` values even if one might determine the value in theory. Thus for the string, "03-017T10:10:10", the `ymd-month` slot is not filled in even though it must be 1 (= January). (Note that the ymd-month slot of "00-060" is not determined: it could be March 1, as in 1900, not a leap year, or February 29, as in 2000, a leap year.) The general rule is that most slots will be `nil` when the date or time specification is incomplete. Slots in an incomplete date-time object can be

### Examples

    (require :datetime)
    (use-package :util.date-time)

    ;; The following all return valid date-time instances

    (date-time "2005-09-13T15:01:20-07:00") -> #<date-time
                                                    "2005-09-13T15:01:20-07:00"
                                                    @
                                                    #x7145782>
    (date-time "2005-09-13 15:01:20-07:00") -> #<date-time
                                                    "2005-09-13T15:01:20-07:00"
                                                    @
                                                    #x714ad32>
    (date-time "19850412") -> #<date-time "1985-04-12" @ #x71502e2>
    (date-time "1985-04-12") -> #<date-time "1985-04-12" @ #x7151dfa>
    (date-time "1985-04") -> #<date-time "1985-04" @ #x71539a2>
    (date-time "1985") -> #<date-time "1985" @ #x7154fba>
    (date-time "19") -> #<date-time "19" @ #x715636a>
    (date-time "850412") -> #<date-time "85-04-12" @ #x71575f2>
    (date-time "85-04-12") -> #<date-time "85-04-12" @ #x7158d72>
    (date-time "-8504") -> #<date-time "-85-04" @ #x715a582>
    (date-time "-85-04") -> #<date-time "-85-04" @ #x715baca>
    (date-time "-85") -> #<date-time "-85" @ #x715d05a>
    (date-time "--0412") -> #<date-time "--04-12" @ #x715e37a>
    (date-time "--04-12") -> #<date-time "--04-12" @ #x715f952>
    (date-time "--04") -> #<date-time "--04" @ #x7160f72>
    (date-time "---12") -> #<date-time "---12" @ #x7162322>
    (date-time "+0019850412"
      :expanded-digits 2) -> #<date-time "1985-04-12" @ #x716376a>
    (date-time "-0019850412"
      :expanded-digits 2) -> #<date-time "-1985-04-12" @ #x7165a1a>
    (date-time "+0219850412"
      :expanded-digits 2) -> #<date-time "+21985-04-12" @ #x7167d22>
    (date-time "-0219850412"
      :expanded-digits 2) -> #<date-time "-21985-04-12" @ #x716a152>
    (date-time "+001985-04-12"
      :expanded-digits 2) -> #<date-time "1985-04-12" @ #x716c4a2>
    (date-time "-001985-04-12"
      :expanded-digits 2) -> #<date-time "-1985-04-12" @ #x716e7e2>
    (date-time "+021985-04-12"
      :expanded-digits 2) -> #<date-time "+21985-04-12" @ #x7170b7a>
    (date-time "-021985-04-12"
      :expanded-digits 2) -> #<date-time "-21985-04-12" @ #x717303a>
    (date-time "+001985-04"
      :expanded-digits 2) -> #<date-time "1985-04" @ #x717541a>
    (date-time "-001985-04"
      :expanded-digits 2) -> #<date-time "-1985-04" @ #x71771ca>
    (date-time "+021985-04"
      :expanded-digits 2) -> #<date-time "+21985-04" @ #x71790da>
    (date-time "-021985-04"
      :expanded-digits 2) -> #<date-time "-21985-04" @ #x717b032>
    (date-time "+001985" :expanded-digits 2) -> #<date-time "1985" @ #x717cf8a>
    (date-time "-001985" :expanded-digits 2) -> #<date-time "-1985" @ #x717e96a>
    (date-time "+021985"
      :expanded-digits 2) -> #<date-time "+21985" @ #x71805f2>
    (date-time "-021985"
      :expanded-digits 2) -> #<date-time "-21985" @ #x7182262>
    (date-time "+0019" :expanded-digits 2) -> #<date-time "19" @ #x7183ed2>
    (date-time "-0019" :expanded-digits 2) -> #<date-time "-19" @ #x718578a>
    (date-time "+0219" :expanded-digits 2) -> #<date-time "+219" @ #x7187122>
    (date-time "-0219" :expanded-digits 2) -> #<date-time "-219" @ #x7188b02>
    (date-time "1985102") -> #<date-time "1985-04-12" @ #x718a4e2>
    (date-time "1985-102") -> #<date-time "1985-04-12" @ #x718bfe2>
    (date-time "85102") -> #<date-time "85-102" @ #x718db2a>
    (date-time "85-102") -> #<date-time "85-102" @ #x718f06a>
    (date-time "-102") -> #<date-time "-102" @ #x71905f2>
    (date-time "+001985102"
      :expanded-digits 2) -> #<date-time "1985-04-12" @ #x71919a2>
    (date-time "-001985102"
      :expanded-digits 2) -> #<date-time "-1985-04-12" @ #x7193c3a>
    (date-time "+021985102"
      :expanded-digits 2) -> #<date-time "+21985-04-12" @ #x7195f02>
    (date-time "-021985102"
      :expanded-digits 2) -> #<date-time "-21985-04-12" @ #x719834a>
    (date-time "+001985-102"
      :expanded-digits 2) -> #<date-time "1985-04-12" @ #x719a65a>
    (date-time "-001985-102"
      :expanded-digits 2) -> #<date-time "-1985-04-12" @ #x719c93a>
    (date-time "+021985-102"
      :expanded-digits 2) -> #<date-time "+21985-04-12" @ #x719ec4a>
    (date-time "-021985-102"
      :expanded-digits 2) -> #<date-time "-21985-04-12" @ #x71a10da>
    (date-time "1985W155") -> #<date-time "1985-04-12" @ #x71a3432>
    (date-time "1985-W15-5") -> #<date-time "1985-04-12" @ #x71a4f22>
    (date-time "1985W15") -> #<date-time "1985-W15" @ #x71a6aa2>
    (date-time "1985-W15") -> #<date-time "1985-W15" @ #x71a80b2>
    (date-time "85W155") -> #<date-time "85-W15-5" @ #x71a970a>
    (date-time "85-W15-5") -> #<date-time "85-W15-5" @ #x71aade2>
    (date-time "85W15") -> #<date-time "85-W15" @ #x72e5e32>
    (date-time "85-W15") -> #<date-time "85-W15" @ #x72ea9c2>
    (date-time "-5W155") -> #<date-time "-5-W15-5" @ #x72ebef2>
    (date-time "-5-W15-5") -> #<date-time "-5-W15-5" @ #x72ed57a>
    (date-time "-5W15") -> #<date-time "-5-W15" @ #x72eec92>
    (date-time "-5-W15") -> #<date-time "-5-W15" @ #x72f012a>
    (date-time "-W155") -> #<date-time "-W15-5" @ #x72f160a>
    (date-time "-W15-5") -> #<date-time "-W15-5" @ #x72f2aa2>
    (date-time "-W15") -> #<date-time "-W15" @ #x72f3f82>
    (date-time "-W-5") -> #<date-time "-W-5" @ #x72f52e2>
    (date-time "+001985W155"
      :expanded-digits 2) -> #<date-time "1985-04-12" @ #x72f6642>
    (date-time "-001985W155"
      :expanded-digits 2) -> #<date-time "-1985-04-10" @ #x72f88ca>
    (date-time "+021985W155"
      :expanded-digits 2) -> #<date-time "+21985-04-12" @ #x72fabaa>
    (date-time "-021985W155"
      :expanded-digits 2) -> #<date-time "-21985-04-10" @ #x72fcfaa>
    (date-time "+001985-W15-5"
      :expanded-digits 2) -> #<date-time "1985-04-12" @ #x72ff2d2>
    (date-time "-001985-W15-5"
      :expanded-digits 2) -> #<date-time "-1985-04-10" @ #x73015ea>
    (date-time "+021985-W15-5"
      :expanded-digits 2) -> #<date-time "+21985-04-12" @ #x730395a>
    (date-time "-021985-W15-5"
      :expanded-digits 2) -> #<date-time "-21985-04-10" @ #x7305dea>
    (date-time "+001985W15"
      :expanded-digits 2) -> #<date-time "1985-W15" @ #x73081a2>
    (date-time "-001985W15"
      :expanded-digits 2) -> #<date-time "-1985-W15" @ #x7309f4a>
    (date-time "+021985W15"
      :expanded-digits 2) -> #<date-time "+21985-W15" @ #x730be52>
    (date-time "-021985W15"
      :expanded-digits 2) -> #<date-time "-21985-W15" @ #x730dda2>
    (date-time "+001985-W15"
      :expanded-digits 2) -> #<date-time "1985-W15" @ #x730fcf2>
    (date-time "-001985-W15"
      :expanded-digits 2) -> #<date-time "-1985-W15" @ #x7311ae2>
    (date-time "+021985-W15"
      :expanded-digits 2) -> #<date-time "+21985-W15" @ #x7313a32>
    (date-time "-021985-W15"
      :expanded-digits 2) -> #<date-time "-21985-W15" @ #x73159ca>
    (date-time "232050" :date nil) -> #<date-time "T23:20:50" @ #x7317962>
    (date-time "23:20:50" :date nil) -> #<date-time "T23:20:50" @ #x7319442>
    (date-time "2320" :date nil) -> #<date-time "T23:20" @ #x731afb2>
    (date-time "23:20" :date nil) -> #<date-time "T23:20" @ #x731c772>
    (date-time "23" :date nil) -> #<date-time "T23" @ #x731df7a>
    (date-time "232050,5"
      :fraction-digits 1
      :date nil) -> #<date-time "T23:20:50,5" @ #x731f532>
    (date-time "232050,51"
      :fraction-digits 2
      :date nil) -> #<date-time "T23:20:50,51" @ #x732211a>
    (date-time "23:20:50,5"
      :fraction-digits 1
      :date nil) -> #<date-time "T23:20:50,5" @ #x73248fa>
    (date-time "23:20:50,51"
      :fraction-digits 2
      :date nil) -> #<date-time "T23:20:50,51" @ #x73270d2>
    (date-time "2320,8"
      :fraction-digits 1
      :date nil) -> #<date-time "T23:20:48" @ #x7329942>
    (date-time "2320,81"
      :fraction-digits 2
      :date nil) -> #<date-time "T23:20:48,6" @ #x732bc4a>
    (date-time "23:20,8"
      :fraction-digits 1
      :date nil) -> #<date-time "T23:20:48" @ #x732e362>
    (date-time "23:20,81"
      :fraction-digits 2
      :date nil) -> #<date-time "T23:20:48,6" @ #x73306b2>
    (date-time "23,3"
      :fraction-digits 1
      :date nil) -> #<date-time "T23:18:00" @ #x7332e12>
    (date-time "23,31"
      :fraction-digits 2
      :date nil) -> #<date-time "T23:18:36" @ #x733505a>
    (date-time "232050,5" :date nil) -> #<date-time "T23:20:50,5" @ #x7337332>
    (date-time "232050,51" :date nil) -> #<date-time "T23:20:50,51" @ #x7339252>
    (date-time "23:20:50,5" :date nil) -> #<date-time "T23:20:50,5" @ #x733b20a>
    (date-time "23:20:50,51"
      :date nil) -> #<date-time "T23:20:50,51" @ #x733d1ba>
    (date-time "2320,8" :date nil) -> #<date-time "T23:20:48" @ #x733f36a>
    (date-time "2320,81" :date nil) -> #<date-time "T23:20:48,6" @ #x7340e4a>
    (date-time "23:20,8" :date nil) -> #<date-time "T23:20:48" @ #x7342d3a>
    (date-time "23:20,81" :date nil) -> #<date-time "T23:20:48,6" @ #x7344862>
    (date-time "23,3" :date nil) -> #<date-time "T23:18:00" @ #x734679a>
    (date-time "23,31" :date nil) -> #<date-time "T23:18:36" @ #x73481ba>
    (date-time "-2050" :date nil) -> #<date-time "T-20:50" @ #x7349c52>
    (date-time "-20:50" :date nil) -> #<date-time "T-20:50" @ #x734b4ca>
    (date-time "-20" :date nil) -> #<date-time "T-20" @ #x734cd8a>
    (date-time "--50" :date nil) -> #<date-time "T--50," @ #x734e3c2>
    (date-time "-2050,5"
      :fraction-digits 1
      :date nil) -> #<date-time "T-20:50,5" @ #x734faf2>
    (date-time "-2050,51"
      :fraction-digits 2
      :date nil) -> #<date-time "T-20:50,51" @ #x7352072>
    (date-time "-20:50,5"
      :fraction-digits 1
      :date nil) -> #<date-time "T-20:50,5" @ #x735468a>
    (date-time "-20:50,51"
      :fraction-digits 2
      :date nil) -> #<date-time "T-20:50,51" @ #x7356c52>
    (date-time "-20,8"
      :fraction-digits 1
      :date nil) -> #<date-time "T-20:48" @ #x73592b2>
    (date-time "-20,81"
      :fraction-digits 2
      :date nil) -> #<date-time "T-20:48,6" @ #x735b352>
    (date-time "--50,5"
      :fraction-digits 1
      :date nil) -> #<date-time "T--50,5" @ #x735d8a2>
    (date-time "--50,51"
      :fraction-digits 2
      :date nil) -> #<date-time "T--50,51" @ #x735fb3a>
    (date-time "-2050,5" :date nil) -> #<date-time "T-20:50,5" @ #x7361e6a>
    (date-time "-2050,51" :date nil) -> #<date-time "T-20:50,51" @ #x7363bc2>
    (date-time "-20:50,5" :date nil) -> #<date-time "T-20:50,5" @ #x73659b2>
    (date-time "-20:50,51" :date nil) -> #<date-time "T-20:50,51" @ #x7367752>
    (date-time "-20,8" :date nil) -> #<date-time "T-20:48" @ #x736958a>
    (date-time "-20,81" :date nil) -> #<date-time "T-20:48,6" @ #x736ae02>
    (date-time "--50,5" :date nil) -> #<date-time "T--50,5" @ #x736cb2a>
    (date-time "--50,51" :date nil) -> #<date-time "T--50,51" @ #x736e59a>
    (date-time "232030Z" :date nil) -> #<date-time "T23:20:30Z" @ #x737008a>
    (date-time "2320Z" :date nil) -> #<date-time "T23:20Z" @ #x7371c9a>
    (date-time "23Z" :date nil) -> #<date-time "T23Z" @ #x737358a>
    (date-time "23:20:30Z" :date nil) -> #<date-time "T23:20:30Z" @ #x7374c5a>
    (date-time "23:20Z" :date nil) -> #<date-time "T23:20Z" @ #x73768fa>
    (date-time "232030+0100"
      :date nil) -> #<date-time "T23:20:30+01:00" @ #x7378232>
    (date-time "2320+0100" :date nil) -> #<date-time "T23:20+01:00" @ #x737a4b2>
    (date-time "23+0100" :date nil) -> #<date-time "T23+01:00" @ #x737c2aa>
    (date-time "23:20:30+0100"
      :date nil) -> #<date-time "T23:20:30+01:00" @ #x737de82>
    (date-time "23:20+0100"
      :date nil) -> #<date-time "T23:20+01:00" @ #x7380192>
    (date-time "232030+0120"
      :date nil) -> #<date-time "T23:20:30+01:20" @ #x738213a>
    (date-time "2320+0120" :date nil) -> #<date-time "T23:20+01:20" @ #x738441a>
    (date-time "23+0120" :date nil) -> #<date-time "T23+01:20" @ #x7386272>
    (date-time "23:20:30+0120"
      :date nil) -> #<date-time "T23:20:30+01:20" @ #x7387eaa>
    (date-time "23:20+0120"
      :date nil) -> #<date-time "T23:20+01:20" @ #x738a21a>
    (date-time "232030+01" :date nil) -> #<date-time "T23:20:30+01" @ #x738c222>
    (date-time "2320+01" :date nil) -> #<date-time "T23:20+01" @ #x738e06a>
    (date-time "23+01" :date nil) -> #<date-time "T23+01" @ #x738fb92>
    (date-time "23:20:30+01"
      :date nil) -> #<date-time "T23:20:30+01" @ #x739149a>
    (date-time "23:20+01" :date nil) -> #<date-time "T23:20+01" @ #x73934da>
    (date-time "232030+01:00"
      :date nil) -> #<date-time "T23:20:30+01:00" @ #x739504a>
    (date-time "2320+01:00"
      :date nil) -> #<date-time "T23:20+01:00" @ #x7397312>
    (date-time "23+01:00" :date nil) -> #<date-time "T23+01:00" @ #x73992ba>
    (date-time "23:20:30+01:00"
      :date nil) -> #<date-time "T23:20:30+01:00" @ #x739aeda>
    (date-time "23:20+01:00"
      :date nil) -> #<date-time "T23:20+01:00" @ #x739d232>
    (date-time "152746+0100"
      :date nil) -> #<date-time "T15:27:46+01:00" @ #x739f222>
    (date-time "152746-0500"
      :date nil) -> #<date-time "T15:27:46-05:00" @ #x73a14a2>
    (date-time "152746+01" :date nil) -> #<date-time "T15:27:46+01" @ #x73a3722>
    (date-time "152746-05" :date nil) -> #<date-time "T15:27:46-05" @ #x73a556a>
    (date-time "15:27:46+01:00"
      :date nil) -> #<date-time "T15:27:46+01:00" @ #x73a73b2>
    (date-time "15:27:46-05:00"
      :date nil) -> #<date-time "T15:27:46-05:00" @ #x73a970a>
    (date-time "15:27:46+01"
      :date nil) -> #<date-time "T15:27:46+01" @ #x73aba62>
    (date-time "15:27:46-05"
      :date nil) -> #<date-time "T15:27:46-05" @ #x73adaa2>
    (date-time "19850412T101530") -> #<date-time "1985-04-12T10:15:30" @
                                          #x73afae2>
    (date-time "19850412 101530") -> #<date-time "1985-04-12T10:15:30" @
                                          #x73b29c2>
    (date-time "19850412T101530Z") -> #<date-time
                                           "1985-04-12T10:15:30Z"
                                           @
                                           #x73b58a2>
    (date-time "19850412 101530Z") -> #<date-time
                                           "1985-04-12T10:15:30Z"
                                           @
                                           #x73ba09a>
    (date-time "19850412T101530+0400") -> #<date-time
                                               "1985-04-12T10:15:30+04:00"
                                               @
                                               #x73be892>
    (date-time "19850412 101530+0400") -> #<date-time
                                               "1985-04-12T10:15:30+04:00"
                                               @
                                               #x73c38f2>
    (date-time "19850412T101530+04") -> #<date-time
                                             "1985-04-12T10:15:30+04"
                                             @
                                             #x73c8952>
    (date-time "19850412 101530+04") -> #<date-time
                                             "1985-04-12T10:15:30+04"
                                             @
                                             #x73cd532>
    (date-time "1985-04-12T10:15:30") -> #<date-time
                                              "1985-04-12T10:15:30"
                                              @
                                              #x73d2112>
    (date-time "1985-04-12 10:15:30") -> #<date-time
                                              "1985-04-12T10:15:30"
                                              @
                                              #x73d6b82>
    (date-time "1985-04-12T10:15:30Z") -> #<date-time
                                               "1985-04-12T10:15:30Z"
                                               @
                                               #x73db5f2>
    (date-time "1985-04-12 10:15:30Z") -> #<date-time
                                               "1985-04-12T10:15:30Z"
                                               @
                                               #x73e026a>
    (date-time "1985-04-12T10:15:30+04:00") -> #<date-time
                                                    "1985-04-12T10:15:30+04:00"
                                                    @
                                                    #x73e4ee2>
    (date-time "1985-04-12 10:15:30+04:00") -> #<date-time
                                                    "1985-04-12T10:15:30+04:00"
                                                    @
                                                    #x73ea4e2>
    (date-time "1985-04-12T10:15:30+04") -> #<date-time
                                                 "1985-04-12T10:15:30+04"
                                                 @
                                                 #x73efae2>
    (date-time "1985-04-12 10:15:30+04") -> #<date-time
                                                 "1985-04-12T10:15:30+04"
                                                 @
                                                 #x73f4b42>
    (date-time "19850412T1015") -> #<date-time "1985-04-12T10:15" @ #x73f9ba2>
    (date-time "19850412 1015") -> #<date-time "1985-04-12T10:15" @ #x73fbbda>
    (date-time "1985-04-12T10:15") -> #<date-time
                                           "1985-04-12T10:15"
                                           @
                                           #x73fdc12>
    (date-time "1985-04-12 10:15") -> #<date-time
                                           "1985-04-12T10:15"
                                           @
                                           #x7402092>
    (date-time "1985102T1015Z") -> #<date-time "1985-04-12T10:15Z" @ #x7406512>
    (date-time "1985102 1015Z") -> #<date-time "1985-04-12T10:15Z" @ #x7408662>
    (date-time "1985-102T10:15Z") -> #<date-time "1985-04-12T10:15Z" @
                                          #x740a7b2>
    (date-time "1985-102 10:15Z") -> #<date-time "1985-04-12T10:15Z" @
                                          #x740d51a>
    (date-time "1985W155T1015+0400") -> #<date-time
                                             "1985-04-12T10:15+04:00"
                                             @
                                             #x7410282>
    (date-time "1985W155 1015+0400") -> #<date-time
                                             "1985-04-12T10:15+04:00"
                                             @
                                             #x7414dea>
    (date-time "1985-W15-5T10:15+04") -> #<date-time
                                              "1985-04-12T10:15+04"
                                              @
                                              #x7419952>
    (date-time "1985-W15-5 10:15+04") -> #<date-time
                                              "1985-04-12T10:15+04"
                                              @
                                              #x741e39a>
    (date-time "19850412") -> #<date-time "1985-04-12" @ #x7422de2>
    (date-time "1985-04-12") -> #<date-time "1985-04-12" @ #x74248fa>
    (date-time "850412") -> #<date-time "85-04-12" @ #x74264a2>
    (date-time "85-04-12") -> #<date-time "85-04-12" @ #x7427c22>
    (date-time "1985102") -> #<date-time "1985-04-12" @ #x7429432>
    (date-time "1985-102") -> #<date-time "1985-04-12" @ #x742af32>
    (date-time "85102") -> #<date-time "85-102" @ #x742ca7a>
    (date-time "85-102") -> #<date-time "85-102" @ #x742dfba>
    (date-time "1985W155") -> #<date-time "1985-04-12" @ #x742f542>
    (date-time "1985-W15-5") -> #<date-time "1985-04-12" @ #x7431032>
    (date-time "85W155") -> #<date-time "85-W15-5" @ #x7432bb2>
    (date-time "85-W15-5") -> #<date-time "85-W15-5" @ #x743428a>
    (date-time "1985W15") -> #<date-time "1985-W15" @ #x74359f2>
    (date-time "1985-W15") -> #<date-time "1985-W15" @ #x7437002>
    (date-time "85W15") -> #<date-time "85-W15" @ #x743865a>
    (date-time "85-W15") -> #<date-time "85-W15" @ #x7439b42>
    (date-time "1985-04") -> #<date-time "1985-04" @ #x743b072>
    (date-time "-8504") -> #<date-time "-85-04" @ #x743c68a>
    (date-time "-85-04") -> #<date-time "-85-04" @ #x743dbd2>
    (date-time "1985") -> #<date-time "1985" @ #x743f162>
    (date-time "-85") -> #<date-time "-85" @ #x7440512>
    (date-time "+0119850412"
      :expanded-digits 2) -> #<date-time "+11985-04-12" @ #x7441832>
    (date-time "+011985-04-12"
      :expanded-digits 2) -> #<date-time "+11985-04-12" @ #x7443c62>
    (date-time "-00020412"
      :expanded-digits 0) -> #<date-time "-0002-04-12" @ #x7446122>
    (date-time "-0002-04-12"
      :expanded-digits 0) -> #<date-time "-0002-04-12" @ #x74483e2>
    (date-time "152746" :date nil) -> #<date-time "T15:27:46" @ #x744a732>
    (date-time "15:27:46" :date nil) -> #<date-time "T15:27:46" @ #x744c212>
    (date-time "-2746" :date nil) -> #<date-time "T-27:46" @ #x744dd82>
    (date-time "-27:46" :date nil) -> #<date-time "T-27:46" @ #x744f5fa>
    (date-time "1528" :date nil) -> #<date-time "T15:28" @ #x7450eba>
    (date-time "15:28" :date nil) -> #<date-time "T15:28" @ #x745267a>
    (date-time "-28" :date nil) -> #<date-time "T-28" @ #x7453e82>
    (date-time "15" :date nil) -> #<date-time "T15" @ #x74554ba>
    (date-time "152735,5"
      :date nil
      :fraction-digits 1) -> #<date-time "T15:27:35,5" @ #x7456a72>
    (date-time "15:27:35,5"
      :date nil
      :fraction-digits 1) -> #<date-time "T15:27:35,5" @ #x74591ba>
    (date-time "-2735,5"
      :date nil
      :fraction-digits 1) -> #<date-time "T-27:35,5" @ #x745b992>
    (date-time "-27:35,5"
      :date nil
      :fraction-digits 1) -> #<date-time "T-27:35,5" @ #x745df12>
    (date-time "152735,5" :date nil) -> #<date-time "T15:27:35,5" @ #x74604da>
    (date-time "15:27:35,5" :date nil) -> #<date-time "T15:27:35,5" @ #x74623fa>
    (date-time "-2735,5" :date nil) -> #<date-time "T-27:35,5" @ #x74643aa>
    (date-time "-27:35,5" :date nil) -> #<date-time "T-27:35,5" @ #x7466102>
    (date-time "000000" :date nil) -> #<date-time "T00:00:00" @ #x7467e8a>
    (date-time "00:00:00" :date nil) -> #<date-time "T00:00:00" @ #x7469922>
    (date-time "0000" :date nil) -> #<date-time "T00:00" @ #x746b44a>
    (date-time "00:00" :date nil) -> #<date-time "T00:00" @ #x746cc0a>
    (date-time "240000" :date nil) -> #<date-time "T24:00:00" @ #x746e412>
    (date-time "24:00:00" :date nil) -> #<date-time "T24:00:00" @ #x746feaa>
    (date-time "2400" :date nil) -> #<date-time "T24:00" @ #x74719d2>
    (date-time "24:00" :date nil) -> #<date-time "T24:00" @ #x7473192>
    (date-time "232030Z" :date nil) -> #<date-time "T23:20:30Z" @ #x747499a>
    (date-time "23:20:30Z" :date nil) -> #<date-time "T23:20:30Z" @ #x74765aa>
    (date-time "2320Z" :date nil) -> #<date-time "T23:20Z" @ #x747824a>
    (date-time "23:20Z" :date nil) -> #<date-time "T23:20Z" @ #x7479b3a>
    (date-time "23Z" :date nil) -> #<date-time "T23Z" @ #x747b472>
    (date-time "152746+0100"
      :date nil) -> #<date-time "T15:27:46+01:00" @ #x747cb42>
    (date-time "15:27:46+01:00"
      :date nil) -> #<date-time "T15:27:46+01:00" @ #x747edc2>
    (date-time "152746+01" :date nil) -> #<date-time "T15:27:46+01" @ #x748111a>
    (date-time "15:27:46+01"
      :date nil) -> #<date-time "T15:27:46+01" @ #x7482f62>
    (date-time "152746-0500"
      :date nil) -> #<date-time "T15:27:46-05:00" @ #x7484fa2>
    (date-time "15:27:46-05:00"
      :date nil) -> #<date-time "T15:27:46-05:00" @ #x7487222>
    (date-time "152746-05" :date nil) -> #<date-time "T15:27:46-05" @ #x748957a>
    (date-time "15:27:46-05"
      :date nil) -> #<date-time "T15:27:46-05" @ #x748b3c2>
    (date-time "19850412T101530") -> #<date-time "1985-04-12T10:15:30" @
                                          #x748d402>
    (date-time "19850412 101530") -> #<date-time "1985-04-12T10:15:30" @
                                          #x74902e2>
    (date-time "1985-04-12T10:15:30") -> #<date-time
                                              "1985-04-12T10:15:30"
                                              @
                                              #x74931c2>
    (date-time "1985-04-12 10:15:30") -> #<date-time
                                              "1985-04-12T10:15:30"
                                              @
                                              #x7497c32>
    (date-time "850412T101530") -> #<date-time "85-04-12T10:15:30" @ #x749c6a2>
    (date-time "850412 101530") -> #<date-time "85-04-12T10:15:30" @ #x749e662>
    (date-time "85-04-12T10:15:30") -> #<date-time
                                            "85-04-12T10:15:30"
                                            @
                                            #x74a0622>
    (date-time "85-04-12 10:15:30") -> #<date-time
                                            "85-04-12T10:15:30"
                                            @
                                            #x74a4b4a>
    (date-time "1985102T235030") -> #<date-time "1985-04-12T23:50:30" @
                                         #x74a9072>
    (date-time "1985102 235030") -> #<date-time "1985-04-12T23:50:30" @
                                         #x74abef2>
    (date-time "1985-102T23:50:30") -> #<date-time
                                            "1985-04-12T23:50:30"
                                            @
                                            #x74aed72>
    (date-time "1985-102 23:50:30") -> #<date-time
                                            "1985-04-12T23:50:30"
                                            @
                                            #x74b35d2>
    (date-time "85102T235030") -> #<date-time "85-102T23:50:30" @ #x74b7e32>
    (date-time "85102 235030") -> #<date-time "85-102T23:50:30" @ #x74b9bb2>
    (date-time "85-102T23:50:30") -> #<date-time "85-102T23:50:30" @ #x74bb932>
    (date-time "85-102 23:50:30") -> #<date-time "85-102T23:50:30" @ #x74bd78a>
    (date-time "1985W155T235030") -> #<date-time "1985-04-12T23:50:30" @
                                          #x74bf5e2>
    (date-time "1985W155 235030") -> #<date-time "1985-04-12T23:50:30" @
                                          #x74c249a>
    (date-time "1985-W15-5T23:50:30") -> #<date-time
                                              "1985-04-12T23:50:30"
                                              @
                                              #x74c5352>
    (date-time "1985-W15-5 23:50:30") -> #<date-time
                                              "1985-04-12T23:50:30"
                                              @
                                              #x74c9d9a>
    (date-time "85W155T235030") -> #<date-time "85-W15-5T23:50:30" @ #x74ce7e2>
    (date-time "85W155 235030") -> #<date-time "85-W15-5T23:50:30" @ #x74d06fa>
    (date-time "85-W15-5T23:50:30") -> #<date-time
                                            "85-W15-5T23:50:30"
                                            @
                                            #x74d2612>
    (date-time "85-W15-5 23:50:30") -> #<date-time
                                            "85-W15-5T23:50:30"
                                            @
                                            #x74d6a92>
    (date-time "1865-04-14") -> #<date-time "1865-04-14" @ #x74daf12>

See for information on support in Allegro CL for parsing and generating time expressions using the ISO 8601 standard.

# date-time-hour

Generic Function, util.date-time package

Arguments: date-time

Returns the value in the `hour` slot of date-time, which must be a date-time object. The value is `nil` if the slot is not set. Otherwise it is an integer between 0 and 23 inclusive. This value cannot be changed with setf and this function.

    (require :datetime)
    (use-package :util.date-time)

    ;; date-time is 1985/04/12 10:15:30, that is 15 and a half
    ;; minutes after 10 AM April 12, 1985.
    (setq a (date-time "1985-04-12T10:15:30"))
    (date-time-hour a) -> 10

See date-time.html for information on support in Allegro CL for parsing and generating time expressions using the ISO 8601 standard.

# date-time-hourf

Generic Function, util.date-time package

Arguments: date-time

Returns the value in the `hourf` (fractional hour) slot of date-time, which must be a date-time object. The value is `nil` if the slot is not set. Otherwise it is a non-negative rational less than 1. This value cannot be changed with setf and this function.

    (require :datetime)
    (use-package :util.date-time)

    ;; date-time is 1985/04/12 10:15:30, that is 15 and a half
    ;; minutes after 10 AM April 12, 1985.
    (setq a (date-time "1985-04-12T10:15:30"))
    (date-time-hourf a) -> 31/120  ;; = 15.5 minutes

See date-time.html for information on support in Allegro CL for parsing and generating time expressions using the ISO 8601 standard.

# date-time-minute

Generic Function, util.date-time package

Arguments: date-time

Returns the value in the `minute` slot of date-time, which must be a date-time object. The value is `nil` if the slot is not set. Otherwise it is an integer from 0 to 59. This value cannot be changed with setf and this function.

    (require :datetime)
    (use-package :util.date-time)

    ;; date-time is 1985/04/12 10:15:30, that is 15 and a half
    ;; minutes after 10 AM April 12, 1985.
    (setq a (date-time "1985-04-12T10:15:30"))
    (date-time-minute a) -> 15

See date-time.html for information on support in Allegro CL for parsing and generating time expressions using the ISO 8601 standard.

# date-time-minutef

Generic Function, util.date-time package

Arguments: date-time

Returns the value in the `minutef` (fractional minute) slot of date-time, which must be a date-time object. The value is `nil` if the slot is not set. Otherwise it is a non-negative rational less than 1. This value cannot be changed with setf and this function.

    (require :datetime)
    (use-package :util.date-time)

    ;; date-time is 1985/04/12 10:15:30, that is 15 and a half
    ;; minutes after 10 AM April 12, 1985.
    (setq a (date-time "1985-04-12T10:15:30"))
    (date-time-minutef a) -> 1/2  ;; = 30 seconds

See date-time.html for information on support in Allegro CL for parsing and generating time expressions using the ISO 8601 standard.

# date-time-second

Generic Function, util.date-time package

Arguments: date-time

Returns the value in the `second` slot of date-time, which must be a date-time object. The value is `nil` if the slot is not set. Otherwise it is an integer from 0 to 59. This value cannot be changed with setf and this function.

    (require :datetime)
    (use-package :util.date-time)

    ;; date-time is 1985/04/12 10:15:30, that is 15 and a half
    ;; minutes after 10 AM April 12, 1985.
    (setq a (date-time "1985-04-12T10:15:30"))
    (date-time-second a) -> 30

See date-time.html for information on support in Allegro CL for parsing and generating time expressions using the ISO 8601 standard.

# date-time-secondf

Generic Function, util.date-time package

Arguments: date-time

Returns the value in the `secondf` (fractional second) slot of date-time, which must be a date-time object. The value is `nil` if the slot is not set. Otherwise it is a non-negative rational less than 1. This value cannot be changed with setf and this function.

    (require :datetime)
    (use-package :util.date-time)

    ;; date-time is 1985/04/12 10:15:30, that is 15 and a half
    ;; minutes after 10 AM April 12, 1985.
    (setq a (date-time "1985-04-12T10:15:30"))
    (date-time-secondf a) -> 0 ;; no fraction specified
    (setq b (date-time "1985-04-12T10:15:30,5"))
    (date-time-secondf a) -> 1/2

See date-time.html for information on support in Allegro CL for parsing and generating time expressions using the ISO 8601 standard.

# date-time-to-ut

Function, util.date-time package

Arguments: date-time &key defaults

This function returns multiple value specifying the extended universal time associated with the argument date-time object (modified, as described below, by defaults). This function is universal time' is one that has values for years prior to 1900 (see below for mroe information).

The return values are listed below. The second through seventh are valid argument to encode-universal-time in any Common Lisp because the year is modified by some multiple of 400 in order that it be greater than 1899. The eighth return value (the time zone) is a valid argument to encode-universal-time if it is a number, but not if it is the symbol `:time-zone-not-specified`. The final return value is the number of multiples of 400 needed to add to the date-time year needed to bring the year past 1899.

In detail, the nine return values are:

1. The extended universal time associated with the date-time and defaults arguments.

2. second: value 0-59.

3. minute: value 0-59.

4. hour: value 0-23.

5. ymd-day: the standard universal time specification of the day of the month (value 1-31).

6. ymd-month: the standard universal time specification of the month (value 1-12).

7. extended-year: if the year specified in the date-time argument is before 1900, then this value will be that year plus a multiple of 400 to make the extended-year be beyond 1900.

8. time-zone: the time zone value or the symbol `:time-zone-not-specified`.

9. year-ut-delta: the value added to the year in the date-time argument to calculate the extended-year value, the seventh return value.

#### Extended universal time

The universal-time is actually an extension of the Common Lisp universal-time since ISO 8601 allows for dates/times to be specified outside the range of those representable by universal-time (i.e., dates before 1900, or times containing fractional seconds). This extended universal-time allows for negative values to represent dates before 1900. In addition, extended universal-times can be non-integer rationals representing times with fractional seconds.

#### The defaults argument

There are three special date-time designators: `:now`, `:today`, and `:zero`. `:now` means current time, `:today` means the start (00:00:00) of the current day, and `:zero` means the start of Jan 1, 0000.

    (require :datetime)
    (use-package :util.date-time)

    ;;  You will see different values for :now and :today
    (date-time :now) => #<date-time "2006-07-11T22:28:08" @ #x7185242a>
    (date-time :today) => #<date-time "2006-07-11T00:00:00" @ #x7185ec6a>

    (date-time :zero)  => #<date-time "0000-01-01T00:00:00" @ #x717dcad2>

These special date-time instances can be used as defaults. The default defaults is `:zero`. Thus, the default behavior is to merge the argument date-time with `(date-time :zero)` to get a complete date-time instance that can be converted to universal-time. You can override the default by specifying :today, :now, or any other date-time instance. You can also specify `nil` as the defaults, in which case no merging occurs.

### Examples

    (require :datetime)
    (use-package :util.date-time)

    ;; Here are two examples showing all the return values
     (date-time-to-ut "1865-11-06")

    <b>Returns values:</b>

     -1077724800
     0
     0
     0
     6
     11
     2265
     :time-zone-not-specified
     400

     (date-time-to-ut "1960-04-14T11:20:00+0700")

    <b>Returns values:</b>

     1902370800
     0
     20
     11
     14
     4
     1960
     -7
     0

    ;; In the remaining examples, we show only the first return value
    ;; of DATE-TIME-TO-UT:

     (setq d (date-time "1985-04-12T23:20:50+02:00"))
    => #<date-time "1985-04-12T23:20:50+02:00" @ ...>

     (setq ut (date-time-to-ut d)) => 2691192050

     (setq d (date-time "1885-04-12T23:20:50+02:00"))
    => #<date-time "1885-04-12T23:20:50+02:00" @ ...>

     ;; The following returns a negative number since the date is before 1900.
     ;;
     (setq ut (date-time-to-ut d)) => -464481550

     (ut-to-date-time (date-time-to-ut "1985-04-12"))
       => #<date-time "1985-04-12T00:00:00+08:00" @ #x718bad0a>

     (ut-to-date-time (date-time-to-ut "1985-04"))
       => #<date-time "1985-04-01T00:00:00+08:00" @ #x718c108a>

     (ut-to-date-time (date-time-to-ut "1985"))
       => #<date-time "1985-01-01T00:00:00+08:00" @ #x718c7092>

     ;; Note that the default may not be desirable in the following case:
     ;;
     (ut-to-date-time (date-time-to-ut "85-04-12"))
       => #<date-time "0085-04-12T00:00:00+08:00" @ #x718ebcba>

     ;; The following are ways to specify different defaults:

     (ut-to-date-time (date-time-to-ut "85-04-12"
                                        :defaults (merge-date-times "1900" :zero)))
       => #<date-time "1985-04-12T00:00:00+08:00" @ #x7191cc8a>

     (ut-to-date-time (date-time-to-ut "85-04-12" :defaults :today))
       => #<date-time "2085-04-12T00:00:00+08:00" @ #x71924f5a>

     (ut-to-date-time (date-time-to-ut "85-04-12" :defaults :now))
       => #<date-time "2085-04-12T22:36:32+08:00" @ #x7192cce2>

See also string-to-universal-time, which converts a string specifying a date and time (in a variety of formats including ISO 8601) to a universal time. See date-time.html for information on support in Allegro CL for parsing and generating time expressions using the ISO 8601 standard.

# date-time-yd-day

Generic Function, util.date-time package

Arguments: date-time

Returns the value in the `yd-day` (day in year) slot of date-time, which must be a date-time object. The value is `nil` if the slot is not set. Otherwise it is an integer from 1 to 366. This value cannot be changed with setf and this function.

    (require :datetime)
    (use-package :util.date-time)

    ;; date-time is 1985/04/12 10:15:30, that is 15 and a half
    ;; minutes after 10 AM April 12, 1985.
    (setq a (date-time "1985-04-12T10:15:30"))
    (date-time-yd-day a) -> 102 ;; 31+28+31+12 for April 12

See date-time.html for information on support in Allegro CL for parsing and generating time expressions using the ISO 8601 standard.

# date-time-year

Generic Function, util.date-time package

Arguments: date-time

Returns the year (an integer) of the date represented in date-time if that value can be calculated by non-`nil` slots in date-time, and returns `nil` otherwise. date-time must be a date-time object.

There is no year slot in a date-time instance. This function calculates its value from other slots (such as `ymd-yd-century` and `ymd-yd-year-in-century`). If `nil` is returned, it may be because the date-time is not complete (so needed slots are not filled in) or because the date portion is incomplete (needed information is not available, such as when a relative date -- "85-10-10" -- is all that is provided.) In the needed slots. In the second case, it will not.

    (require :datetime)
    (use-package :util.date-time)

    ;; date-time is 1985/04/12 10:15:30, that is 15 and a half
    ;; minutes after 10 AM April 12, 1985.
    (setq a (date-time "1985-04-12T10:15:30"))
    (date-time-year a) -> 1985

See date-time.html for information on support in Allegro CL for parsing and generating time expressions using the ISO 8601 standard.

# date-time-ymd-day

Generic Function, util.date-time package

Arguments: date-time

Returns the value in the `ymd-day` (day in month) slot of date-time, which must be a date-time object. The value is `nil` if the slot is not set. Otherwise it is an integer from 1 to 31. This value cannot be changed with setf and this function.

    (require :datetime)
    (use-package :util.date-time)

    ;; date-time is 1985/04/12 10:15:30, that is 15 and a half
    ;; minutes after 10 AM April 12, 1985.
    (setq a (date-time "1985-04-12T10:15:30"))
    (date-time-ymd-day a) -> 12

See date-time.html for information on support in Allegro CL for parsing and generating time expressions using the ISO 8601 standard.

# date-time-ymd-month

Generic Function, util.date-time package

Arguments: date-time

Returns the value in the `ymd-month` (month in year) slot of date-time, which must be a date-time object. The value is `nil` if the slot is not set. Otherwise it is an integer from 1 to 12. This value cannot be changed with setf and this function.

    (require :datetime)
    (use-package :util.date-time)

    ;; date-time is 1985/04/12 10:15:30, that is 15 and a half
    ;; minutes after 10 AM April 12, 1985.
    (setq a (date-time "1985-04-12T10:15:30"))
    (date-time-ymd-month a) -> 4

See date-time.html for information on support in Allegro CL for parsing and generating time expressions using the ISO 8601 standard.

# date-time-ymd-yd-before-year-0

Generic Function, util.date-time package

Arguments: date-time

Returns the value of the `ymd-yd-before-year-0` of date-time, which must be a date-time object. The value can be `t` or `nil`. `t` means the date in date-time is definitely before the year 0. `nil` can mean that the date is not before the year 0 or that the slot value has not been calculated and holds its initial value (which is `nil`).

The value depends on the value of the `ymd-yd-century` (reader date-time-ymd-yd-century: if that value is positive, the century is not before year 0 and so `nil` is the proper value for this function; linewise the century being negative means `t` is the correct value for this function. If the value of the `ymd-yd-century` is `nil`, the correct value for this function cannot be determined and the initial value (`nil`) is returned.

date-time should be complete (see complete-date-time) before calling this function. Otherwise the slot may be unset even though there is enough date information to set it accurately.

This is not a particular useful value for user code (its is useful for internal code). Users may wish to just look at the century value to determine whether the date is before year 0 or not, if that information is knowable. See also date-time-ywd-before-year-0, which give a different value on January 1, year 0.

See date-time.html for information on support in Allegro CL for parsing and generating time expressions using the ISO 8601 standard.

# date-time-ymd-yd-century

Generic Function, util.date-time package

Arguments: date-time

Returns the value in the `ymd-yd-century` (the century in calendar date and ordinal date calendars) slot of date-time, which must be a date-time object. The value is `nil` if the slot is not set. Otherwise it is an integer. This value cannot be changed with setf and this

    (require :datetime)
    (use-package :util.date-time)

    ;; date-time is 1985/04/12 10:15:30, that is 15 and a half
    ;; minutes after 10 AM April 12, 1985.
    (setq a (date-time "1985-04-12T10:15:30"))
    (date-time-ymd-yd-century a) -> 19
    (setq a1 (date-time "85102T235030"))  ;; no century specified
    (date-time-ymd-yd-century a1) -> nil

See date-time.html for information on support in Allegro CL for parsing and generating time expressions using the ISO 8601 standard.

# date-time-ymd-yd-year-in-century

Generic Function, util.date-time package

Arguments: date-time

Returns the value in the `ymd-yd-year-in-century` (the year in the century in calendar date and ordinal date calendars) slot of date-time, which must be a date-time object. The value is `nil` if the slot is not set. Otherwise it is an integer. This value cannot be changed with setf and this function. See also related week date claendar functions like

See date-time.html for information on support in Allegro CL for parsing and generating time expressions using the ISO 8601 standard.

# date-time-ywd-before-year-0

Generic Function, util.date-time package

Arguments: date-time

Returns the value of the `ymd-yd-before-year-0` of date-time, which must be a date-time object. The value can be `t` or `nil`. `t` means the date in date-time is definitely before the year 0. `nil` can mean that the date is not before the year 0 or that the slot value has not been calculated and holds its initial value (which is `nil`).

The value depends on the value of the `ywd-century` is positive, the century is not before year 0 and so `nil` is the proper value for this function; linewise the century being negative means `t` is the correct value for this function. If the value of the `ymd-yd-century` is `nil`, the correct value for this function cannot be determined and the initial value (`nil`) is returned.

calling this function. Otherwise the slot may be unset even though there is enough date information to set it accurately.

This is not a particular useful value for user code (its is useful for internal code). Users may wish to just look at the century value to determine whether the date is before year 0 or not, if that give a different value on January 1, year 0.

See date-time.html for information on support in Allegro CL for parsing and generating time expressions using the ISO 8601 standard.

# date-time-ywd-century

Generic Function, util.date-time package

Arguments: date-time

Returns the value in the `ywd-century` (the year in the century in week date calendars) slot of date-time, which must be a date-time object. The value is `nil` if the slot is not set. Otherwise it is an integer. This value cannot be changed with setf and this function.

See date-time.html for information on support in Allegro CL for parsing and generating time expressions using the ISO 8601 standard.

# date-time-ywd-day

Generic Function, util.date-time package

Arguments: date-time

Returns the value in the `ywd-day` (the day in the week, with Monday being 1 and Sunday 7, in week date calendars) slot of date-time, which must be a date-time object. The value is `nil` if the slot is not set. Otherwise it is an integer from 1 to 7. This value cannot be changed with setf.

See date-time.html for information on support in Allegro CL for parsing and generating time expressions using the ISO 8601 standard.

# date-time-ywd-decade-in-century

Generic Function, util.date-time package

Arguments: date-time

Returns the value in the `ywd-decade-in-century` (the decade in the century in week date calendars) slot of date-time, which must be a date-time object. The value is `nil` if the slot is not set. Otherwise it is an integer from 1 to 9. This value cannot be changed with setf.

See date-time.html for information on support in Allegro CL for parsing and generating time expressions using the ISO 8601 standard.

# date-time-ywd-week

Generic Function, util.date-time package

Arguments: date-time

Returns the value in the `ywd-week` (the week in the year in week date calendars) slot of date-time, which must be a date-time object. The value is `nil` if the slot is not set. Otherwise it is an integer from 1 to 53. This value cannot be changed with setf and this function.

See date-time.html for information on support in Allegro CL for parsing and generating time expressions using the ISO 8601 standard.

# date-time-ywd-year-in-decade

Generic Function, util.date-time package

Arguments: date-time

Returns the value in the `ywd-week` (the week in the year in week date calendars) slot of date-time, which must be a date-time object. The value is `nil` if the slot is not set. Otherwise it is an integer from 1 to 53. This value cannot be changed with setf and this function.

See date-time.html for information on support in Allegro CL for parsing and generating time expressions using the ISO 8601 standard.

# date-time-zone

Generic Function, util.date-time package

Arguments: date-time

Returns the time zone as calculated from the `zone-hour` and `zone-minute` slots of date-time, which must be a date-time object. Returns `nil` if the relevant slots are not set (and so the zone value cannot be calculated). The slots are not set even in a complete date-time if no zone information is including in in the original ISO 8601 string. See also date-time-zone-hour and date-time-zone-minute.

See date-time.html for information on support in Allegro CL for parsing and generating time expressions using the ISO 8601 standard.

# date-time-zone-hour

Generic Function, util.date-time package

Arguments: date-time

Returns the value of the time-zone-hout slot of date-time, which must be a date-time object. Returns `nil` if the slot is not set. This slot is not set even in a complete date-time if no zone information is including in the original ISO 8601 string. See also date-time-zone and date-time-zone-minute.

See date-time.html for information on support in Allegro CL for parsing and generating time expressions using the ISO 8601 standard.

# date-time-zone-minute

Generic Function, util.date-time package

Arguments: minute

Returns the value of the time-zone-minute slot of date-time, which must be a date-time object. Returns `nil` if the slot is not set. This slot is not set even in a complete date-time if no zone information is including in the original ISO 8601 string. See also date-time-zone and date-time-zone-hour.

See date-time.html for information on support in Allegro CL for parsing and generating time expressions using the ISO 8601 standard.

# decode-date-time

Function, util.date-time package

Arguments: date-time

This function, the date-time analog of decode-universal-time, takes a date-time object and returns, as multiple value, its sizteen components plus the year and the zone. (So this function returns eighteen values in all.) Each value can be accessed individually with the appropriate reader function.

The argument can also be the keyqord `:key`, in which case the return value is a list of keywords identifying the 18 return values. Here is an example showing some of the return values for a date-time and some of the explanation keywords when the argument is `:key`:

     cl-user(3): (require :datetime)
     t
     cl-user(4): (use-package :util.date-time)
     t
     cl-user(5): (setq d (date-time "1985-04-12T23:20:50"))
     #<date-time "1985-04-12T23:20:50" @ #x71b527d2>
     cl-user(6): (multiple-value-list (decode-date-time d))
     (0 50 20 23 12 4 1985 nil 85 19 ...)
     cl-user(7): (decode-date-time :key)
     (:secondf :second :minute :hour :ymd-day :ymd-month :year :zone
      :ymd-yd-year-in-century :ymd-yd-century ...)

The return values, along with their type and the correcsponding reader function are:

1. secondf: the fractional second, a rational. Reader is date-time-secondf.

2. second: the second, an integer. Reader is date-time-second.

3. minute: the minute, an integer. Reader is date-time-minute.

4. hour: the hour, an integer. Reader is date-time-hour.

5. ymd-day: the day in the month, an integer in the range 1 to 31. Reader is date-time-ymd-day.

6. ymd-month: the month, an integer in the range 1 to 12. Reader is date-time-ymd-month.

7. year: the year, an integer. Returned by date-time-year. `year` does not name a slot in a date-time instance. The year is calculated from the date-time-ymd-yd-before-year-0, date-time-ymd-yd-century, and date-time-ymd-yd-year-in-century slots of date-time.

8. zone: the zone, a time zone or `nil`. Returned by date-time-zone. `zone` does not name a slot in a date-time instance. The zone is calculated from the date-time-zone-hour and date-time-zone-minute slots.

9. ymd-yd-year-in-century: the year in the century, an integer from 0 to 99. (Thus 0 for 1900. Measured from year 0, so backwards for BCE years, that is 15 for -1415.) Reader is date-time-ymd-yd-year-in-century.

10. ymd-yd-century: the century, and integer. 19 for 1900 to 1999, 20 for 2000 to 2099. Measured from year 0, so backwards for BCE years, that is 14 for -1415. Reader is date-time-ymd-yd-century.

11. ymd-yd-before-year-0: a boolean indicating whether before year 0 (`t`) or after (`nil`). Reader is date-time-ymd-yd-before-year-0.

12. yd-day: the day in the year, an integer from 1 to 366. Reader is date-time-yd-day.

13. ywd-day: the day of the week, an integer from 1 (Monday) to 7 (Sunday). Reader is date-time-ywd-day.

14. ywd-week: the week in the year, and integer from 1 to 53. Week 1 is the first week in the year to contain a Thursday. Day 1 of that week is Monday (as day 1 always is) so if Thursday is, say on New Year's day, the previous Monday is in the first week of the year despite actually being in the previous calendar year. Reader is date-time-ywd-week.

15. ywd-year:

16. ywd-year-in-decade

17. ywd-decade-in-century

18. ywd-century

19. ywd-before-year-0

See date-time.html for information on support in Allegro CL for parsing and generating time expressions using the ISO 8601 standard.

# duration

Generic Function, util.date-time package

Arguments: durationspec &key start end

Returns the date-time denoted by durationspec. durationspec should be a duration specifyier. start and end are bounding index designators of durationspec. The defaults for start and end are 0 and `nil`, respectively.

Note the difference between a date-time designator and a time-interval designator of a duration. A time-interval designator specifies that a duration begin with the character #\P, as, for example, in "P1Y2MT5H". The corresponding duration designator does not include the initial #\P and would be "1Y2MT5H".

### Examples

    (require :datetime)
    (use-package :util.date-time)

    (duration-years (duration "2Y10M15DT10H30M20S")) => 2
    (duration-months (duration "00021015T103020")) => 10

See also duration-years, duration-months, duration-weeks, duration-days, duration-hours, duration-minutes, duration-seconds, time-interval, add-duration, subtract-duration.

See date-time.html for information on support in Allegro CL for parsing and generating time expressions using the ISO 8601 standard.

# duration-days

Generic Function, util.date-time package

Arguments: duration

This generic function is the reader for the `days` slot of the duration class. (The slot value cannot be changed with setf and this function.) The argument must be a duration instance.

The value is the number of days in duration. The value is an integer.

See date-time.html for information on support in Allegro CL for parsing and generating time expressions using the ISO 8601 standard.

# duration-hours

Generic Function, util.date-time package

Arguments: duration

This generic function is the reader for the `hours` slot of the duration class. (The slot value cannot be changed with setf and this function.) The argument must be a duration instance.

The value is the number of hours in duration. The value is an integer.

See date-time.html for information on support in Allegro CL for parsing and generating time expressions using the ISO 8601 standard.

# duration-minutes

Generic Function, util.date-time package

Arguments: duration

This generic function is the reader for the `minutes` slot of the duration class. (The slot value cannot be changed with setf and this function.) The argument must be a duration instance.

The value is the number of minutes in duration. The value is an integer.

See date-time.html for information on support in Allegro CL for parsing and generating time expressions using the ISO 8601 standard.

# duration-months

Generic Function, util.date-time package

Arguments: duration

This generic function is the reader for the `months` slot of the duration class. (The slot value cannot be changed with setf and this function.) The argument must be a duration instance.

If tye slot is set, the value is the number of months in duration, an integer. If the slot has not been set, the value is `nil`.

See date-time.html for information on support in Allegro CL for parsing and generating time expressions using the ISO 8601 standard.

# duration-seconds

Generic Function, util.date-time package

Arguments: duration

This generic function is the reader for the `seconds` slot of the duration class. (The slot value cannot be changed with setf and this function.) The argument must be a duration instance.

The value is the number of seconds in duration. The value is an integer.

See date-time.html for information on support in Allegro CL for parsing and generating time expressions using the ISO 8601 standard.

# duration-weeks

Generic Function, util.date-time package

Arguments: duration

This generic function is the reader for the `weeks` slot of the duration class. (The slot value cannot be changed with setf and this function.) The argument must be a duration instance.

The value is the number of weeks in duration. The value is an integer.

See date-time.html for information on support in Allegro CL for parsing and generating time expressions using the ISO 8601 standard.

# duration-years

Generic Function, util.date-time package

Arguments: duration

This generic function is the reader for the `years` slot of the duration class. (The slot value cannot be changed with setf and this function.) The argument must be a duration instance.

The value is the number of years in duration or `nil` if the slot is not set. If set, the value is an integer.

See date-time.html for information on support in Allegro CL for parsing and generating time expressions using the ISO 8601 standard.

# merge-date-times

Function, util.date-time package

Arguments: date-time defaults &key copy

This function returns a date-time object constructed by filling in any unsupplied components in date-time with the corresponding values from defaults. Both date-time and defaults must be date-time objects.

When copy is true a new date-time instance is created. When copy is false (the default), the date-time argument is overwritten with the return value.

### Examples

    cl-user(5) (require :datetime)
    t
    cl-user(6) (use-package :util.date-time)
    t
    ;; DATE-TIME does not have a century specified, and DEFAULTS has
    ;; only a century. The result has complete date info but no time info:
    cl-user(7): (merge-date-times (date-time "06-04-12") (date-time "2000"))
    #<date-time "2006-04-12" @ #x4aefc12>
    ;;  Here DATE-TIME and DEFAULTS both have seconds specified (including
    ;;  fractional seconds in the case of DATE-TIME. The result uses the
    ;;  DATE-TIME seconds and fractional seconds values, but takes other
    ;;  values unspecified in DATE-TIME from DEFAULTS:
    cl-user(8): (merge-date-times (date-time "T--50,5")
                       (date-time "2006-05-13T22:30:51,14+02:00"))
    #<date-time "2006-05-13T22:30:50,5+02:00" @ #x4af9382>
    cl-user(9):

See date-time.html for information on support in Allegro CL for parsing and generating time expressions using the ISO 8601 standard.

# parse-iso8601

Function, util.date-time package

Arguments: iso8601-text &key start end expanded-digits fraction-digits date

Returns a time-interval or a date-time object based on iso8601-text, which should be a string with suitable contents.

If the iso8601-text argument contains either a #\P, #\R, or #/, then the return value is equivalent to the following:

    (require :datetime)
    (use-package :util.date-time)

    (time-interval iso8601-text :start start :end end)

Otherwise, the return value is equivalent to the following:

    (require :datetime)
    (use-package :util.date-time)

    (date-time iso8601-text :start start :end end :date date
                              :expanded-digits expanded-digits
                              :fraction-digits fraction-digits)

See time-interval and date-time for details of the keyword arguments.

### Examples

    (require :datetime)
    (use-package :util.date-time)

     (parse-iso8601 "R5/2002-03-01T13:00:00Z/P1Y2M10DT2H30M"))
    => #<time-interval R5/2002-03-01T13:00:00Z/P1Y2M10DT2H30M0S @ ...>

     (parse-iso8601 "19850412T23:20:50")
    => #<date-time "1985-04-12T23:20:50" @ ...>

See date-time.html for information on support in Allegro CL for parsing and generating time expressions using the ISO 8601 standard.

# subtract-duration

Function, util.date-time package

Arguments: date-timespec durationspec

Returns a new date-time object obtained by subtracting the duration specified by durationspec from the date-time specified by date-timespec.

The default method does not subtract two durations.

     > (require :datetime)
     > (use-package :util.date-time)

     > (subtract-duration (date-time "1985-04-10T10:30:40")
             (duration "1MT1H4S"))
     #<date-time "1985-03-10T09:30:36" @ ...>

See duration, date-time, and add-duration.

See date-time.html for information on support in Allegro CL for parsing and generating time expressions using the ISO 8601 standard. See particularly the section Adding/Subtracting Durations, where it is pointed out (with examples) that adding and subtracting durations are not inverse operations and adding durations is not associative.

# time-interval

Generic Function, util.date-time package

Arguments: time-intervalspec &key start end

Returns the time-interval denoted by the ISO-8601 time-intervalspec. time-intervalspec should be a time-interval designator. start and end are bounding index designators of time-intervalspec. The defaults for start and end are 0 and `nil`, respectively.

ISO 8601 specifies textual representations for time-intervals. They may be specified in four ways:

1. Start and end, such as 2002-03-01T13:00:00Z/2003-05-11T15:30:00Z
2. Start and duration, such as 2002-03-01T13:00:00Z/P1Y2M10DT2H30M
3. Duration and end, such as P1Y2M10DT2H30M/2003-05-11T15:30:00Z
4. Duration only, such as P1Y2M10DT2H30M

### Examples

    (require :datetime)
    (use-package :util.date-time)

     ;; The following time-interval specifies a start time and an end time.
     (setq ti (time-interval "19850412T232050/19850625T103000"))
    => #<time-interval 1985-04-12T23:20:50/1985-06-25T10:30:00 @ ...>

     (time-interval-start ti)
    => #<date-time "1985-04-12T23:20:50" @ ...>

     (time-interval-end ti)
    => #<date-time "1985-06-25T10:30:00" @ ...>

     ;; No duration was specified in ti
     (time-interval-duration ti)
    => nil

     ;; The following time-interval specifies a duration.
     (setq ti2 (time-interval "P2Y10M15DT10H30M20S"))
    => #<time-interval P2Y10M15DT10H30M20S @ ...>

     (time-interval-duration ti2)
    => #<duration 2Y10M15DT10H30M20S @ ...>

     (duration-years (time-interval-duration ti2)) => 2

See also duration, time-interval-start, time-interval-end, time-interval-duration, and time-interval-recurrences.

A repeating interval is formed by adding "Rn/" to the beginning of an interval expression. For example, to repeat the interval P1Y2M10DT2H30M five times starting at 2002-03-01T13:00:00Z, use R5/2002-03-01T13:00:00Z/P1Y2M10DT2H30M

See date-time.html for information on support in Allegro CL for parsing and generating time expressions using the ISO 8601 standard.

# time-interval-duration

Generic Function, util.date-time package

Arguments: time-interval

Returns the value of the duration slot of time-interval, which must be a time-interval object. time-intervals are created with time-interval.

See date-time.html for information on support in Allegro CL for parsing and generating time expressions using the ISO 8601 standard.

# time-interval-end

Generic Function, util.date-time package

Arguments: time-interval

Returns the value of the end slot of time-interval, which must be a time-interval object. time-intervals are created with time-interval.

See date-time.html for information on support in Allegro CL for parsing and generating time expressions using the ISO 8601 standard.

# time-interval-recurrences

Generic Function, util.date-time package

Arguments: time-interval

Returns the value of the recurrences slot of time-interval, which must be a time-interval object. time-intervals are created with time-interval.

See date-time.html for information on support in Allegro CL for parsing and generating time expressions using the ISO 8601 standard.

# time-interval-start

Generic Function, util.date-time package

Arguments: time-interval

Returns the value of the start slot of time-interval, which must be a time-interval object. time-intervals are created with time-interval.

See date-time.html for information on support in Allegro CL for parsing and generating time expressions using the ISO 8601 standard.

# ut-to-date-time

Function, util.date-time package

Arguments: time-interval

Returns the date-time object corresponding to the universal time specified by the argument. This function is the inverse of date-time-to-ut. Note the universal-time is actually an extension of the Common Lisp universal-time since ISO 8601 allows for dates/times to be specified outside the range of those representable by universal-time (i.e., dates before 1900, or times containing fractional seconds). This extended universal-time allows for negative values to represent dates before 1900. In addition, extended universal-times can be non-integer rationals representing times with fractional seconds.

The time-zone keyword argument must be an ANSI time zone value (a rational multiple of 1/3600 between -24 and 24 inclusive) specifying a time zone. If time-zone is not specified, then the host computer's current time-zone is used (corrected for Daylight Saving Time if applicable).

The complete keyword argument should be a boolean. If it is false, the complete-date-time is not called. If complete is true (which is the default), then the return value is the result of calling complete-date-time on the result decoded from the universal-time.

### Examples

    (require :datetime)
    (use-package :util.date-time)

     (setq d (date-time "1985-04-12T23:20:50+02:00"))
    => #<date-time "1985-04-12T23:20:50+02:00" @ ...>

     (setq ut (date-time-to-ut d)) => 2691192050

     (setq d (date-time "1885-04-12T23:20:50+02:00"))
    => #<date-time "1885-04-12T23:20:50+02:00" @ ...>

     ;; The following returns a negative number since the date is before 1900.
     ;;
     (setq ut (date-time-to-ut d)) => -464481550

     (ut-to-date-time (date-time-to-ut "1985-04-12"))
       => #<date-time "1985-04-12T00:00:00+08:00" @ #x718bad0a>

     (ut-to-date-time (date-time-to-ut "1985-04"))
       => #<date-time "1985-04-01T00:00:00+08:00" @ #x718c108a>

     (ut-to-date-time (date-time-to-ut "1985"))
       => #<date-time "1985-01-01T00:00:00+08:00" @ #x718c7092>

     ;; Note that the default may not be desirable in the following case:
     ;;
     (ut-to-date-time (date-time-to-ut "85-04-12"))
       => #<date-time "0085-04-12T00:00:00+08:00" @ #x718ebcba>

     ;; The following are ways to specify different defaults:

     (ut-to-date-time (date-time-to-ut "85-04-12"
                                        :defaults (merge-date-times "1900" :zero)))
       => #<date-time "1985-04-12T00:00:00+08:00" @ #x7191cc8a>

     (ut-to-date-time (date-time-to-ut "85-04-12" :defaults :today))
       => #<date-time "2085-04-12T00:00:00+08:00" @ #x71924f5a>

     (ut-to-date-time (date-time-to-ut "85-04-12" :defaults :now))
       => #<date-time "2085-04-12T22:36:32+08:00" @ #x7192cce2>

    ;; Here we use the time-zone keyword argument (done on March 12, 2007):
     (ut-to-date-time (get-universal-time) :time-zone 6)
       => #<date-time "2007-03-12T12:20:02-06:00" @ #x71cdf832>

See also universal-time-to-string, which converts a universal time to a string in a variety of formats including ISO 8601. See date-time.html for information on support in Allegro CL for parsing and generating time expressions using the ISO 8601 standard.

Copyright (c) Franz Inc. Lafayette, CA., USA. All rights reserved.

ToC | DocOverview | CGDoc | RelNotes | FAQ | Index | PermutedIndex
| Allegro CL version 11.0