*************** The date Module *************** .. current-library:: system .. current-module:: date The ``date`` module is part of the System library and provides a machine-independent facility for representing and manipulating dates and date/time intervals. Representing dates and times ---------------------------- The ``date`` module contains a single class, ````, an instance of which can represent any date between 1 Jan 1800 00:00:00 and 31 Dec 2199 23:59:59, Greenwich Mean Time. You can create a date object by calling the function *encode-date* or using the *make* method for ````. - :class:`` - :meth:`make )>` - :func:`encode-date` - :func:`current-date` - :class:`` Each of the arguments to :func:`encode-date` and to the :meth:`make )>` method on :class:`` is an instance of :drm:`` (except for the *iso8601-string* keyword for the *make* method, which is a string) that is passed as an init-keyword value to the ```` object. Each init-keyword takes an instance of :drm:``, limited to the natural range for that attribute. For example, *month:* can only take values between 1 and 12. You must specify values, via :func:`encode-date`, for at least the *year:*, *month:*, and *day:* init-keywords. In addition, you can also specify values for *hours:*, *minutes:*, *seconds:*, *microseconds:*, and *time-zone-offset:*. If not supplied, the default value for each of these init-keywords is 0. The *time-zone-offset:* init-keyword is used to represent time zones in the ``date`` module as :drm:`` values representing the offset in minutes from Greenwich Mean Time (GMT). Positive values are used for time zones East of Greenwich; negative values represent time zones to the west of Greenwich. For example, the value -300 (-5 hours) is U.S. Eastern Standard Time and the value -240 (-4 hours) is U.S. Eastern Daylight Savings Time. If you wish, a ```` can be specified completely by using the *iso8601-string:* init-keyword. This init-keyword takes an instance of :drm:``, which should be a valid ISO8601 format date. If you use the *iso8601-string:* init-keyword, there is no need to specify any other init-keywords to a call to *make* on ````. Representing durations ---------------------- Date/time intervals, called durations, are modeled in a style quite similar to that of SQL. There are two, effectively disjoint, classes of duration: one with a resolution of months (for example, 3 years, 2 months) and the other with a resolution of microseconds (for example, 50 days, 6 hours, 23 minutes). The first is :class:`` and the second :class:``. An important distinction between ```` and ```` is that a given instance of ```` is always a fixed unit of a fixed length, whereas a ```` follows the vagaries of the calendar. So if you have a ```` that represents, for example, the 5th of some month, adding a ```` of 1 month to that will always take you to the 5th of the following month, whether that is an interval of 28, 29, 30, or 31 days. - :class:`` - :class:`` - :class:`` - :func:`encode-year/month-duration` - :func:`encode-day/time-duration` - :gf:`decode-duration` Performing operations on dates and durations -------------------------------------------- A number of interfaces are exported from the ``date`` module that let you perform other operations on dates and durations, and extract date-specific information from your local machine. Comparing dates ^^^^^^^^^^^^^^^ The following operations are exported from the ``date`` module. - :meth:`= <=()>` - :meth:`< <<()>` These methods let you perform arithmetic-like operations on dates to test for equality, or to test whether one date occurred before another. Comparing durations ^^^^^^^^^^^^^^^^^^^ The following operations are exported from the ``date`` module. - :meth:`= <=()>` - :meth:`< <<()>` As with dates, you can perform arithmetic-like operations on durations to test for equality, or to test whether one duration is shorter than another. Performing arithmetic operations ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ You can add, subtract, multiply, and divide dates and durations in a number of ways to produce a variety of date or duration information. Methods are defined for any combination of date and duration, with any operation that makes sense, and the return value is of the appropriate type. For example, a method is defined that subtracts one date from another, and returns a duration, but there is no method for adding two dates together, since dates cannot be summed in any sensible way. However, there are methods for adding dates and durations which return dates. Note that some addition and subtraction operations involving dates and instances of :class:`` can cause errors where the result is a date that does not exist in the calendar. For example, adding one month to January 30th. The table below summarizes the methods defined for each arithmetic operation, for different combinations of date and duration arguments, together with their return values. Methods defined for arithmetic operations on dates and durations +---------------------------+--------------------------------+--------------------------------+--------------------------------+ | Op | Argument 1 | Argument 2 | Return value | +===========================+================================+================================+================================+ | :meth:`+ <+()>` | :class:`` | :class:`` | :class:`` | +---------------------------+--------------------------------+--------------------------------+--------------------------------+ | :meth:`+ <+()>` | :class:`` | :class:`` | :class:`` | +---------------------------+--------------------------------+--------------------------------+--------------------------------+ | :meth:`+ <+()>` | :class:`` | :class:`` | :class:`` | +---------------------------+--------------------------------+--------------------------------+--------------------------------+ | :meth:`+ <+()>` | :class:`` | :class:`` | :class:`` | +---------------------------+--------------------------------+--------------------------------+--------------------------------+ | :meth:`+ <+()>` | :class:`` | :class:`` | :class:`` | +---------------------------+--------------------------------+--------------------------------+--------------------------------+ | :meth:`- <-()>` | :class:`` | :class:`` | :class:`` | +---------------------------+--------------------------------+--------------------------------+--------------------------------+ | :meth:`- <-()>` | :class:`` | :class:`` | :class:`` | +---------------------------+--------------------------------+--------------------------------+--------------------------------+ | :meth:`- <-()>` | :class:`` | :class:`` | :class:`` | +---------------------------+--------------------------------+--------------------------------+--------------------------------+ | :meth:`- <-()>` | :class:`` | :class:`` | :class:`` | +---------------------------+--------------------------------+--------------------------------+--------------------------------+ | :meth:`- <-()>` | :class:`` | :class:`` | :class:`` | +---------------------------+--------------------------------+--------------------------------+--------------------------------+ | :meth:`* <*()>` | :class:`` | :drm:`` | :class:`` | +---------------------------+--------------------------------+--------------------------------+--------------------------------+ | :meth:`* <*()>` | :drm:`` | :class:`` | :class:`` | +---------------------------+--------------------------------+--------------------------------+--------------------------------+ | :meth:`/ )>` | :class:`` | :drm:`` | :class:`` | +---------------------------+--------------------------------+--------------------------------+--------------------------------+ Dealing with time-zones ^^^^^^^^^^^^^^^^^^^^^^^ The following functions return information about the time-zone that the host machine is in. - :func:`local-time-zone-name` - :func:`local-time-zone-offset` - :func:`local-daylight-savings-time?` Extracting information from dates --------------------------------- A number of functions are available to return discrete pieces of information from a specified ```` object. These are useful to allow you to deconstruct a given date in order to retrieve useful information from it. The most basic way to extract information from a date is to use the function *decode-date*. - :func:`decode-date` Decodes a ```` into its constituent parts. This function is the companion of *encode-date*, in that it takes a ```` object and returns all of its constituent parts. Note, however, that in contrast to *encode-date*, it does not return any millisecond component to the date, but it does return the day of the week of the specified date. A number of other functions exist to extract individual components from a ```` object. Each of these functions is listed below. Each function takes a single argument, a ```` object, and returns the component of the date referred to in the function name. For example, *date-month* takes a ```` object as an argument, and returns the month that the date refers to. - :func:`date-year` - :func:`date-month` - :func:`date-day` - :func:`date-day-of-week` - :func:`date-hours` - :func:`date-minutes` - :func:`date-seconds` - :func:`date-microseconds` - :func:`date-time-zone-offset` For each function except *date-day-of-week*, the value returned is an instance of :drm:``. The *date-day-of-week* function returns an object of type ````. For more information, please refer to the reference entries of each function. Also see the function :func:`date-time-zone-offset-setter`, which allows you to set the time-zone offset of a ```` explicitly. Formatting Dates ---------------- To return an ISO 8601 format date from a ```` object, use the function :func:`as-iso8601-string`. Dates can also be returned in RFC-822 and RFC-1123 formats with the :func:`as-rfc822-string` and :func:`as-rfc1123-string` functions. More flexible date formatting is available with :func:`format-date`. Parsing Dates ------------- Dates can be parsed with :func:`parse-date-string`. ISO-8601 formatted date strings can be parsed with :func:`parse-iso8601-string`. The date module --------------- This section contains a reference entry for each item exported from the Date module. .. method:: = :specializer: :sealed: Compares two dates for equality. :signature: *date1* = *date2* => *equal?* :parameter date1: An instance of :class:``. :parameter date2: An instance of :class:``. :value equal?: An instance of :drm:``. :description: This method lets you compare two dates to see if they are equal. Any differences in microseconds between *date1* and *date2* are ignored. :seealso: - :meth:`< <<()>` .. method:: = :specializer: :sealed: Compares two durations for equality. :signature: *duration1* = *duration2* => *equal?* :parameter duration1: An instance of :class:``. :parameter duration2: An instance of :class:``. :value equal?: An instance of :drm:``. :description: This method lets you compare two durations to see if they are equal. If the durations are actually instances of :class:``, any differences in microseconds between *duration1* and *duration2* are ignored. :seealso: - :meth:`< <<()>` .. method:: < :sealed: :specializer: Determines whether one date is earlier than another. :signature: *date1* < *date2* => *before?* :parameter date1: An instance of :class:``. :parameter date2: An instance of :class:``. :value before?: An instance of :drm:``. :description: This method determines if *date1* is earlier than *date2*. Any differences in microseconds between *date1* and *date2* are ignored. :seealso: - :meth:`= <=()>` .. method:: < :sealed: :specializer: Determines whether one duration is less than another. :signature: *duration1* < *duration2* => *less-than?* :parameter duration1: An instance of :class:``. :parameter duration2: An instance of :class:``. :value less-than?: An instance of :drm:``. :description: This method determines if *duration1* is less than *duration2*. If the durations are actually instances of :class:``, any differences in microseconds between *duration1* and *duration2* are ignored. :seealso: - :meth:`= <=()>` .. method:: + :sealed: :specializer: Performs addition on specific combinations of dates and durations. :signature: + *arg1* *arg2* => *sum* :parameter arg1: An instance of :class:`` or :class:``. See description for details. :parameter arg2: An instance of :class:`` or :class:``. See description for details. :value sum: An instance of :class:``. :description: A number of methods are defined for the :drm:`+` generic function to allow summing of various combinations of dates and durations. Note that there is not a method defined for every possible combination of date and duration. Specifically, you cannot sum two dates. The table below lists the methods that are defined on :drm:`+` and :class:``. Methods defined for addition of dates and durations +--------------------------------+--------------------------------+--------------------------------+ | arg1 | arg2 | sum | +================================+================================+================================+ | :class:`` | :class:`` | :class:`` | +--------------------------------+--------------------------------+--------------------------------+ | :class:`` | :class:`` | :class:`` | +--------------------------------+--------------------------------+--------------------------------+ :seealso: - :meth:`+()` - :meth:`-()` - :meth:`-()` - :meth:`*()` - :meth:`/()` .. method:: + :sealed: :specializer: Performs addition on durations. :signature: + *arg1* *arg2* => *sum* :parameter arg1: An instance of :class:``. :parameter arg2: An instance of :class:``. :value sum: An instance of :class:``. :description: A number of methods are defined for the :drm:`+` generic function to allow summing of durations. Note that there is not a method defined for every possible combination of duration. Specifically, you cannot sum different types of duration. The table below lists the methods that are defined on :drm:`+`. Methods defined for addition of durations +--------------------------------+--------------------------------+--------------------------------+ | arg1 | arg2 | sum | +================================+================================+================================+ | :class:`` | :class:`` | :class:`` | +--------------------------------+--------------------------------+--------------------------------+ | :class:`` | :class:`` | :class:`` | +--------------------------------+--------------------------------+--------------------------------+ | :class:`` | :class:`` | :class:`` | +--------------------------------+--------------------------------+--------------------------------+ :seealso: - :meth:`+()` - :meth:`-()` - :meth:`-()` - :meth:`*()` - :meth:`/()` .. method:: - :sealed: :specializer: Performs subtraction on specific combinations of dates and durations. :signature: - *arg1* *arg2* => *diff* :parameter arg1: An instance of :class:`` or :class:``. See description for details. :parameter arg2: An instance of :class:``, or an instance of :class:`` if *arg1* is a ````. See description for details. :value diff: An instance of :class:`` or :class:``. See description for details. :description: A number of methods are defined for the :drm:`-` generic function to allow subtraction of various combinations of dates and durations. Note that there is not a method defined for every possible combination of date and duration. Specifically, you cannot subtract a date from a duration, and you cannot subtract different types of duration. The return value can be either a date or a duration, depending on the arguments supplied. The table below lists the methods that are defined on :drm:`-`. Methods defined for subtraction of dates and durations +--------------------------------+--------------------------------+--------------------------------+ | arg1 | arg2 | difference | +================================+================================+================================+ | :class:`` | :class:`` | :class:`` | +--------------------------------+--------------------------------+--------------------------------+ | :class:`` | :class:`` | :class:`` | +--------------------------------+--------------------------------+--------------------------------+ :seealso: - :meth:`+()` - :meth:`+()` - :meth:`-()` - :meth:`*()` - :meth:`/()` .. method:: - :sealed: :specializer: Performs subtraction on specific combinations of durations. :signature: - *arg1* *arg2* => *diff* :parameter arg1: An instance of :class:`` or :class:``. See description for details. :parameter arg2: An instance of :class:``, or an instance of :class:`` if *arg1* is a ````. See description for details. :value diff: An instance of :class:`` or :class:``. See description for details. :description: A number of methods are defined for the :drm:`-` generic function to allow subtraction of durations. Note that there is not a method defined for every possible combination of duration. Specifically, you cannot subtract different types of duration. The table below lists the methods that are defined on :drm:`-`. Methods defined for subtraction of dates and durations +--------------------------------+--------------------------------+--------------------------------+ | arg1 | arg2 | difference | +================================+================================+================================+ | :class:`` | :class:`` | :class:`` | +--------------------------------+--------------------------------+--------------------------------+ | :class:`` | :class:`` | :class:`` | +--------------------------------+--------------------------------+--------------------------------+ :seealso: - :meth:`+()` - :meth:`+()` - :meth:`-()` - :meth:`*()` - :meth:`/()` .. method:: * :sealed: :specializer: Multiplies a duration by a scale factor. :signature: \* *duration* *scale* => *new-duration* :signature: \* *scale* *duration* => *new-duration* :parameter duration: An instance of :class:``. :parameter scale: An instance of :drm:``. :value new-duration: An instance of :class:``. :description: *Note:* These arguments can be expressed in any order. Multiples a duration by a scale factor and returns the result. Note that the arguments can be expressed in any order: methods are defined such that the duration can be placed first or second in the list of arguments. :seealso: - :meth:`+()` - :meth:`+()` - :meth:`-()` - :meth:`-()` - :meth:`/()` .. method:: / :sealed: :specializer: Divides a duration by a scale factor :signature: / *duration* *scale* => *new-duration* :parameter duration: An instance of :class:``. :parameter scale: An instance of :drm:``. :value new-duration: An instance of :class:``. :description: :seealso: - :meth:`+()` - :meth:`+()` - :meth:`-()` - :meth:`-()` - :meth:`*()` .. function:: as-iso8601-string Returns a string representation of a date, conforming to the ISO 8601 standard. :signature: as-iso8601-string *date* #key *precision* => *iso8601-string* :parameter date: An instance of :class:``. :parameter #key precision: An instance of :drm:``. Default value: 0. :value iso8601-string: An instance of :drm:``. :description: Returns a string representation of *date* using the format identified by International Standard ISO 8601 (for example, ``"19960418T210634Z"``). If *precision* is non-zero, the specified number of digits of a fraction of a second are included in the string (for example, ``"19960418T210634.0034Z"``). The returned string always expresses the time in Greenwich Mean Time. The *iso8601-string* init-keyword for :class:``, however, accepts ISO 8601 strings with other time zone specifications. This is the same as calling: .. code-block:: dylan format-date("%Y-%m-%dT%H:%M:%S%:z", date); :seealso: - :class:`` - :func:`as-rfc822-string` - :func:`as-rfc1123-string` - :func:`format-date` - :func:`parse-date-string` - :func:`parse-iso8601-string` .. function:: as-rfc822-string Returns a string representation of a date, conforming to `RFC 822 `_. :signature: as-rfc822-string *date* => *rfc822-string* :parameter date: An instance of :class:``. :value rfc822-string: An instance of :drm:``. :description: An example in this format is:: Sun, 01 Sep 13 17:00:00 GMT This is the same as calling: .. code-block:: dylan format-date("%a, %d %b %y %H:%M:%S %z", date); :seealso: - :class:`` - :func:`as-rfc1123-string` - :func:`as-iso8601-string` - :func:`format-date` - :func:`parse-date-string` .. function:: as-rfc1123-string Returns a string representation of a date, conforming to `RFC 1123 `_. :signature: as-rfc1123-string *date* => *rfc1123-string* :parameter date: An instance of :class:``. :value rfc1123-string: An instance of :drm:``. :description: The date format for RFC-1123 is the same as for RFC-822 except that the year must be 4 digits rather than 2:: Sun, 01 Sep 2013 17:00:00 GMT This is the same as calling: .. code-block:: dylan format-date("%a, %d %b %Y %H:%M:%S %z", date); This format is commonly used in email, HTTP headers, RSS feeds and other protocols where date representations are used. :seealso: - :class:`` - :func:`as-rfc822-string` - :func:`as-iso8601-string` - :func:`format-date` - :func:`parse-date-string` .. function:: current-date Returns a date object representing the current date and time. :signature: current-date () => *date* :value date: An instance of :class:``. :description: Returns *date* for the current date and time. .. class:: :sealed: The class of objects representing dates. :superclasses: :drm:`` :keyword iso8601-string: An instance of ``false-or()``. Default value: :drm:`#f`. :keyword year: An instance of ``limited(, min: 1800, max: 2199)``. :keyword month: An instance of ``limited(, min: 1, max: 12)``. :keyword day: An instance of ``limited(, min: 1, max: 31)``. :keyword hours: An instance of ``limited(, min: 0, max: 23)``. Default value: 0. :keyword minutes: An instance of ``limited(, min: 0, max: 59)``. Default value: 0. :keyword seconds: An instance of ``limited(, min: 0, max: 59)``. Default value: 0. :keyword microseconds: An instance of ``limited(, min: 0, max: 999999)``. Default value: 0. :keyword time-zone-offset: An instance of :drm:``. Default value: 0. :description: Represents a date and time between 1 Jan 1800 00:00:00 and 31 Dec 2199 23:59:59, Greenwich Mean Time (GMT). A ```` can be specified to microsecond precision and includes a time zone indication. If supplied, the *iso8601-string:* init-keyword completely specifies the value of the ````. Otherwise, the *year:*, *month:*, and *day:* init-keywords must be supplied. Note that, although you can supply ISO 8601 strings that represent any time zone specification, the related function :func:`as-iso8601-string` always returns an ISO 8601 string representing a time in Greenwich Mean Time. For the *time-zone-offset* init-keyword, a positive number represents an offset ahead of GMT, in minutes, and a negative number represents an offset behind GMT. The value returned is an instance of :drm:`` (for example, -300 represents the offset for EST, which is 5 hours behind GMT). :operations: - :meth:`= <=()>` - :meth:`< <<()>` - :meth:`+ <+()>` - :meth:`- <-()>` - :func:`as-iso8601-string` - :func:`as-rfc822-string` - :func:`as-rfc1123-string` - :func:`current-date` - :func:`date-day` - :func:`date-day-of-week` - :func:`date-hours` - :func:`date-microseconds` - :func:`date-minutes` - :func:`date-month` - :func:`date-seconds` - :func:`date-time-zone-offset` - :func:`date-time-zone-offset-setter` - :func:`date-year` - :func:`decode-date` :seealso: - :func:`as-iso8601-string` - :func:`as-rfc822-string` - :func:`as-rfc1123-string` - :class:`` .. function:: date-day Returns the day of the month component of a specified date. :signature: date-day *date* => *day* :parameter date: An instance of :class:``. :value day: An instance of :drm:``. :description: Returns the day of the month component of the specified *date*. For example, if passed a :class:`` that represented 16:36 on the 20th June, 1997, *date-day* returns the value 20. :seealso: - :func:`decode-date` - :func:`date-month` - :func:`date-year` - :func:`date-hours` - :func:`date-minutes` - :func:`date-seconds` - :func:`date-microseconds` - :func:`date-time-zone-offset` - :func:`date-day-of-week` .. function:: date-day-of-week Returns the day of the week of a specified date. :signature: date-day-of-week *date* => *day-of-week* :parameter date: An instance of :class:``. :value day-of-week: An object of type ````. :description: Returns the day of the week of the specified *date*. :seealso: - :func:`decode-date` - :func:`date-month` - :func:`date-year` - :func:`date-hours` - :func:`date-minutes` - :func:`date-seconds` - :func:`date-microseconds` - :func:`date-time-zone-offset` - :func:`date-day` - :class:`` .. function:: date-hours Returns the hour component of a specified date. :signature: date-hours *date* => *hour* :parameter date: An instance of :class:``. :value hour: An instance of :drm:``. :description: Returns the hour component of the specified *date*. This component is always expressed in 24 hour format. :seealso: - :func:`decode-date` - :func:`date-month` - :func:`date-day` - :func:`date-year` - :func:`date-minutes` - :func:`date-seconds` - :func:`date-microseconds` - :func:`date-time-zone-offset` - :func:`date-day-of-week` .. function:: date-microseconds Returns the microseconds component of a specified date. :signature: date-microseconds *date* => *microseconds* :parameter date: An instance of :class:``. :value microseconds: An instance of :drm:``. :description: Returns the microseconds component of the specified *date*. Note that this does *not* return the entire date object, represented as a number of microseconds; it returns any value assigned to the *microseconds:* init-keyword when the :class:`` object was created. :seealso: - :func:`decode-date` - :func:`date-month` - :func:`date-day` - :func:`date-hours` - :func:`date-minutes` - :func:`date-seconds` - :func:`date-year` - :func:`date-time-zone-offset` - :func:`date-day-of-week` .. function:: date-minutes Returns the minutes component of a specified date. :signature: date-minutes *date* => *minutes* :parameter date: An instance of :class:``. :value minutes: An instance of :drm:``. :description: Returns the minutes component of the specified *date*. :seealso: - :func:`decode-date` - :func:`date-month` - :func:`date-day` - :func:`date-hours` - :func:`date-year` - :func:`date-seconds` - :func:`date-microseconds` - :func:`date-time-zone-offset` - :func:`date-day-of-week` .. function:: date-month Returns the month of a specified date. :signature: date-month *date* => *month* :parameter date: An instance of :class:``. :value month: An instance of :drm:``. :description: Returns the month of the specified *date*. :seealso: - :func:`decode-date` - :func:`date-year` - :func:`date-day` - :func:`date-hours` - :func:`date-minutes` - :func:`date-seconds` - :func:`date-microseconds` - :func:`date-time-zone-offset` - :func:`date-day-of-week` .. function:: date-seconds Returns the seconds component of a specified date. :signature: date-seconds *date* => *seconds* :parameter date: An instance of :class:``. :value seconds: An instance of :drm:``. :description: Returns the seconds component of the specified *date*. Note that this does *not* return the entire date object, represented as a number of seconds; it returns any value assigned to the *seconds:* init-keyword when the :class:`` object was created. :seealso: - :func:`decode-date` - :func:`date-month` - :func:`date-day` - :func:`date-hours` - :func:`date-minutes` - :func:`date-year` - :func:`date-microseconds` - :func:`date-time-zone-offset` - :func:`date-day-of-week` .. function:: date-time-zone-offset Returns the time zone offset of a specified date. :signature: date-time-zone-offset *date* => *time-zone-offset* :parameter date: An instance of :class:``. :value time-zone-offset: An instance of :drm:``. :description: Returns the time zone offset of the specified *date*. The values of the other components of *date* reflect this time zone. A positive number represents an offset ahead of GMT, in minutes, and a negative number represents an offset behind GMT. The value returned is an instance of :drm:`` (for example, -300 represents the offset for EST, which is 5 hours behind GMT). :seealso: - :func:`decode-date` - :func:`date-month` - :func:`date-day` - :func:`date-hours` - :func:`date-minutes` - :func:`date-seconds` - :func:`date-year` - :func:`date-microseconds` - :func:`date-time-zone-offset-setter` - :func:`date-day-of-week` .. function:: date-time-zone-offset-setter Change the time zone offset of a specified date, while maintaining the same point in time. :signature: date-time-zone-offset-setter *new-time-zone-offset* *date* => *new-time-zone-offset* :parameter new-time-zone-offset: An instance of :drm:``. :parameter date: An instance of :class:``. :value new-time-zone-offset: An instance of :drm:``. :description: Changes the time zone offset of *date* without changing the actual point in time identified by the *date*. The values of the other components of *date* are adjusted to reflect the new time zone. The *new-time-zone-offset* argument should represent the offset from GMT, in minutes. Thus, if you wish to specify a new offset representing EST, which is 5 hours behind GMT, *new-time-zone-offset* should have the value -300. :seealso: - :func:`date-time-zone-offset` .. function:: date-year Returns the year of a specified date. :signature: date-year *date* => *year* :parameter date: An instance of :class:``. :value year: An instance of :drm:``. :description: Returns the year of the specified *date*. :seealso: - :func:`decode-date` - :func:`date-month` - :func:`date-day` - :func:`date-hours` - :func:`date-minutes` - :func:`date-seconds` - :func:`date-microseconds` - :func:`date-time-zone-offset` - :func:`date-day-of-week` :: todo Make this a type. .. class:: The days of the week. :description: The days of the week. This is the type of the return value of the :func:`date-day-of-week` function. .. code-block:: dylan one-of(#"Sunday", #"Monday", #"Tuesday", #"Wednesday", #"Thursday", #"Friday", #"Saturday") :operations: - :func:`date-day-of-week` :seealso: - :func:`date-day-of-week` .. class:: :sealed: The class of objects representing durations in units of microseconds. :superclasses: :class:`` :keyword days: An instance of :drm:``. :keyword hours: An instance of :drm:``. Default value: 0. :keyword minutes: An instance of :drm:``. Default value: 0. :keyword seconds: An instance of :drm:``. Default value: 0. :keyword microseconds: An instance of :drm:``. Default value: 0. :description: The class of objects representing durations in units of microseconds. It is a subclass of :class:``. Use this class to represent a number of days and fractions thereof. If you need to represent durations in calendar units of months or years, use :class:`` instead. :operations: - :meth:`< <<()>` - :meth:`+ <+()>` - :meth:`- <-()>` - :gf:`decode-duration` - :func:`encode-day/time-duration` :seealso: - :class:`` - :class:`` .. function:: decode-date Returns the date and time stored in a date object. :signature: decode-date *date* => *year month day hours minutes seconds day-of-week time-zone-offset* :parameter date: An instance of :class:``. :value year: An instance of :drm:``. :value month: An instance of :drm:``. :value day: An instance of :drm:``. :value hours: An instance of :drm:``. :value minutes: An instance of :drm:``. :value seconds: An instance of :drm:``. :value day-of-week: An instance of ````. :value time-zone-offset: An instance of :drm:``. :description: Returns the date and time stored in *date*. Note that it does not return the millisecond component of a :class:``, but it does return the appropriate ````. :seealso: - :func:`encode-date` .. generic-function:: decode-duration :sealed: Decodes a duration into its constituent parts. :signature: decode-duration *duration* => #rest *components* :parameter duration: An instance of :class:``. :value #rest components: Instances of :drm:``. :description: Decodes an instance of :class:`` into its constituent parts. There are methods for this generic function that specialize on :class:`` and :class:`` respectively, as described below. :seealso: - :meth:`decode-duration )>` - :meth:`decode-duration )>` .. method:: decode-duration :specializer: :sealed: Decodes a day/time duration into its constituent parts. :signature: decode-duration *duration* => *days* *hours* *minutes* *seconds* *microseconds* :parameter duration: An instance of :class:``. :value days: An instance of :drm:``. :value hours: An instance of :drm:``. :value minutes: An instance of :drm:``. :value seconds: An instance of :drm:``. :value microseconds: An instance of :drm:``. :description: Decodes an instance of :class:`` into its constituent parts. :seealso: - :gf:`decode-duration` - :meth:`decode-duration )>` - :func:`encode-day/time-duration` .. method:: decode-duration :specializer: :sealed: Decodes a year/month duration into its constituent parts. :signature: decode-duration *duration* => *years* *months* :parameter duration: An instance of :class:``. :value years: An instance of :drm:``. :value months: An instance of :drm:``. :description: Decodes an instance of :class:`` into its constituent parts. :seealso: - :gf:`decode-duration` - :meth:`decode-duration )>` - :func:`encode-year/month-duration` .. class:: :sealed: :abstract: :instantiable: The class of objects representing durations. :superclasses: :drm:`` :keyword iso8601-string: An instance of ``false-or()``. Default value: :drm:`#f`. :keyword year: An instance of ``limited(, min: 1800, max: 2199)``. :keyword month: An instance of ``limited(, min: 1, max: 12)``. :keyword day: An instance of ``limited(, min: 1, max: 31)``. :keyword hours: An instance of ``limited(, min: 0, max: 23)``. Default value: 0. :keyword minutes: An instance of ``limited(, min: 0, max: 59)``. Default value: 0. :keyword seconds: An instance of ``limited(, min: 0, max: 59)``. Default value: 0. :keyword microseconds: An instance of ``limited(, min: 0, max: 999999)``. Default value: 0. :keyword time-zone-offset: An instance of :drm:``. Default value: 0. :description: This class is the used to represent durations. It is a subclass of :drm:``, and it has two subclasses. :operations: - :meth:`= <=()>` - :meth:`< <<()>` - :meth:`+ <+()>` - :meth:`- <-()>` - :meth:`\* <*()>` - :meth:`/ )>` :seealso: - :class:`` - :class:`` .. function:: encode-date Creates a date object for the specified date and time. :signature: encode-date *year month day hours minutes seconds* #key*microseconds time-zone-offset* => *date* :parameter year: An instance of :drm:``. :parameter month: An instance of :drm:``. :parameter day: An instance of :drm:``. :parameter hours: An instance of :drm:``. :parameter minutes: An instance of :drm:``. :parameter seconds: An instance of :drm:``. :parameter #key microseconds: An instance of :drm:``. Default value: 0. :parameter #keytime-zone-offset: An instance of :drm:``. Default value: :func:`local-time-zone-offset()`. :value date: An instance of :class:``. :description: Creates a :class:`` object for the specified date and time. :seealso: - :gf:`decode-date` - :func:`local-time-zone-offset` - :meth:`make )>` .. function:: encode-day/time-duration Creates a day/time duration from a set of integer values. :signature: encode-day/time-duration *days* *hours* *minutes* *seconds* *microseconds* => *duration* :parameter days: An instance of :drm:``. :parameter hours: An instance of :drm:``. :parameter minutes: An instance of :drm:``. :parameter seconds: An instance of :drm:``. :parameter microseconds: An instance of :drm:``. :value duration: An instance of :class:``. :description: Creates an instance of :class:``. :seealso: - :gf:`decode-duration` - :func:`encode-year/month-duration` .. function:: encode-year/month-duration Creates a year/month duration from a set of integer values. :signature: encode-year/month-duration *years* *months* => *duration* :parameter years: An instance of :drm:``. :parameter months: An instance of :drm:``. :value duration: An instance of :class:``. :description: Creates an instance of :class:``. :seealso: - :gf:`decode-duration` - :func:`encode-day/time-duration` .. function:: format-date Formats a date according to a format string. :signature: format-date *format* *date* => *formatted-date* :parameter format: An instance of :drm:``. :parameter date: An instance of :class:``. :value formatted-date: An instance of :drm:``. :description: ``format-date`` interprets a control string, ``format``, to create a string representing the ``date``. The control string can contain these directives: - ``%Y`` - The year. - ``%y`` - The year, in 2 digit form. - ``%H`` - Hours, zero padded. - ``%k`` - Hours, space padded. - ``%M`` - Minutes, zero padded. - ``%S`` - Seconds, zero padded. - ``%f`` - Microseconds, 6 digits. - ``%F`` - Milliseconds, 3 digits. - ``%T`` - Time, each component zero padded. - ``%m`` - Month in numeric form, zero padded. - ``%d`` - Day of the month, zero padded. - ``%e`` - Day of the month, space padded. - ``%A`` - Name of the day of the week. - ``%a`` - Short name of the day of the week. - ``%B`` - Name of the month. - ``%b`` - Short name of the month. - ``%z`` - Time zone offset. - ``%:z`` - Time zone offset, but using ``:`` between hours and minutes. - ``%n`` - A new line. - ``%%`` - A % character. :seealso: - :func:`as-rfc822-string` - :func:`as-rfc1123-string` - :func:`as-iso8601-string` - :func:`parse-date-string` - :func:`parse-iso8601-string` .. function:: local-daylight-savings-time? Checks whether the local machine is using Daylight Savings Time. :signature: local-daylight-savings-time? () => *dst?* :value dst?: An instance of :drm:``. :description: Returns :drm:`#t` if the local machine is using Daylight Savings Time, and :drm:`#f` otherwise. .. function:: local-time-zone-name Returns the time zone name in use by the local machine. :signature: local-time-zone-name () => *time-zone-name* :value time-zone-name: An instance of :drm:``. :description: Returns the time zone name in use by the local machine, if available, or a string of the form ``+/-HHMM`` if the time zone name is unknown. .. function:: local-time-zone-offset Returns the offset of the time-zone from Greenwich Mean Time, expressed as a number of minutes. :signature: local-time-zone-offset () => *time-zone-offset* :value time-zone-offset: An instance of :drm:``. :description: Returns the offset of the time-zone from Greenwich Mean Time, expressed as a number of minutes. A positive number represents an offset ahead of GMT, and a negative number represents an offset behind GMT. The return value is an instance of :drm:`` (for example, -300 represents the offset for EST, which is 5 hours behind GMT). The return value incorporates daylight savings time when necessary. .. method:: make :specializer: Creates an instance of the :class:`` class. :signature: make *date-class* #key *iso8601-string year month day hours minutes seconds microseconds time-zone-offset* => *date-instance* :parameter date-class: The class :class:``. :parameter #key iso8601-string: An instance of ``false-or()``. Default value: :drm:`#f`. :parameter #key year: An instance of ``limited(, min: 1800, max: 2199)``. :parameter #key month: An instance of ``limited(, min: 1, max: 12)``. :parameter #key day: An instance of ``limited(, min: 1, max: 31)``. :parameter #key hours: An instance of ``limited(, min: 0, max: 23)``. Default value: 0. :parameter #key minutes: An instance of ``limited(, min: 0, max: 59)``. Default value: 0. :parameter #key seconds: An instance of ``limited(, min: 0, max: 59)``. Default value: 0. :parameter #key microseconds: An instance of ``limited(, min: 0, max: 999999)``. Default value: 0. :parameter #key time-zone-offset: An instance of :drm:``. Default value: 0. :value date-instance: An instance of :class:``. :description: Creates an instance of :class:``. The make method on :class:`` takes the same keywords as the :class:`` class. **Note**: The iso8601-string keyword accepts a richer subset of the ISO 8601 specification than is produced by the :func:`as-iso8601-string` function. See :func:`parse-iso8601-string` for details. :example: .. code-block:: dylan make (, iso8601-string: "19970717T1148-0400") :seealso: - :class:`` - :func:`encode-date` - :func:`parse-iso8601-string` .. function:: parse-date-string Parse a date in string form according to a control string, returning a date. :signature: parse-date-string *date* *format* => *date* :parameter date: An instance of :drm:``. :parameter format: An instance of :drm:``. :value date: An instance of :class:``. :description: Parses a date in string form according to a control string, ``format``. The control string uses the same directives as :func:`format-date`. :seealso: - :func:`format-date` - :func:`parse-iso8601-string` .. function:: parse-iso8601-string Parse a variety of variants on ISO-8601 formatted date strings. :signature: parse-iso8601-string *string* #key *strict?* => *date* :parameter string: An instance of :drm:``. :parameter #key strict?: An instance of :drm:``, default :drm:`#t`. :value date: An instance of :class:``. :description: This function parses the ISO 8601 formats listed below, with the following differences if strict? = #f: * the '-' in YYYY-MM-DD is optional * the ':' in hh:mm:ss is optional * the ':' in the timezone is optional * the date and time may be separated by a space character * TZD may be preceded by a space character See https://www.w3.org/TR/NOTE-datetime.html. Year: YYYY (eg 1997) Year and month: YYYY-MM (eg 1997-07) Complete date: YYYY-MM-DD (eg 1997-07-16) Complete date plus hours and minutes: YYYY-MM-DDThh:mmTZD (eg 1997-07-16T19:20+01:00) Complete date plus hours, minutes and seconds: YYYY-MM-DDThh:mm:ssTZD (eg 1997-07-16T19:20:30+01:00) Complete date plus hours, minutes, seconds and a decimal fraction of a second YYYY-MM-DDThh:mm:ss.sTZD (eg 1997-07-16T19:20:30.45+01:00) where: * YYYY = four-digit year * MM = two-digit month (01=January, etc.) * DD = two-digit day of month (01 through 31) * hh = two digits of hour (00 through 23) (am/pm NOT allowed) * mm = two digits of minute (00 through 59) * ss = two digits of second (00 through 59) * s = one or more digits representing a decimal fraction of a second * TZD = time zone designator (Z or +hh:mm or -hh:mm) :seealso: - :func:`as-iso8601-string` - :func:`format-date` - :func:`parse-date-string` .. class:: :sealed: The class of objects representing durations with a coarse resolution. :superclasses: :class:`` :keyword year: An instance of :drm:``. :keyword month: An instance of :drm:``. :description: The class of objects representing durations in units of calendar years and months. It is a subclass of :class:``. Use this class to represent a number of calendar years and months. If you need to represent durations in units of days or fractions thereof (to microsecond resolution), use :class:`` instead. :operations: - :meth:`< <<()>` - :meth:`+ <+()>` - :meth:`- <-()>` - :func:`decode-duration` - :func:`encode-year/month-duration` :seealso: - :class:`` - :class:``