# cl-dates

*A comprehensive date handling library for Common Lisp*

This library contains a fairly comprehensive set of functions to
handle dates with somewhat weaker support for date-times. It is useful
for applications where dates are an important data type e.g., business
or financial calculations.

Dates are stored as a floating point number whose value is the Julian
day number plus the day fraction corresponding to the time. Since a
Julian date, by definition starts at noon, the date is an integer only
when the time is exactly noon. For example, "January 1, 2017" can have
values from 2457754.5 to 2457755.499*. As a result, the date
arithmetic functions provided work off the Julian day number (2457755
in this case) and ignore the time.

## Features

*cl-dates* has the following features:

- *Parse a date from a string*: Largely based on the Python
  *dateutils* library, a complex parser for commonly encountered date
  formats is provided in the function **string->date**. The test cases
  in *test-parse-date.lisp* provide a flavour of what kinds of strings
  are acceptable.

- Dates can be *converted to a string* in several formats including
  ISO 8601 and RFC 822 using the function **date->string**.

- Functions are provided to calculate *astronomical dates* for any
  given year (**easter-day**, **vernal-equinox**,
  **autumnal-equinox**, **summer-solstice**, and **winter-solstice**).

- *Date arithmetic*
    - Functions are provided to add or subtract days or months from a
      date (**date+**, **date-**, **add-months**,
      **add-years**). Addition of months or years correctly handles
      cases where the given date falls on a month end.
    - Compute differences between dates (**diff-days**,
      **diff-years**). When computing the number of years, the day
      convention (such as *Actual/365* or *30/360*) is taken into
      account so that the result can be used to accurately compute
      interest on a bond or loan.
	  
- *Holiday calendars*: Functions to automatically generate holidays
  for certain currencies / trading centres are provided. Dates can
  be checked against these calendars to see if they are business days
  or not.

- *Miscellaneous* date manipulation functions are provided to compute
  the last day of a month, last day of the previous month, Nth day of
  week in a month (e.g., 3rd Wednesday), etc.

All functions are provided in the CL-DATES package. A nickname "DT" is
defined to reduce typing if the symbols are not imported.

## Dependencies

The only dependency is on the Common Lisp package. There are no third
party library dependencies.

## Test Suite

Test cases are in _test-*.lisp_. To run, load the *cl-dates-test* package
and run **cl-dates-test:run-all-tests**.

The library has been tested with CCL on Mac OS X and Windows and SBCL on Mac
OS X. The code is portable and should run on any Common Lisp environment. 

## License

*cl-dates* is licensed under the 2-clause BSD license.

## To Do

Date arithmetic functions that use holiday calendars to advance dates
are not yet included.