[local-time-devel] Proposed local-time 1.0 API (revision 1)

[Daniel Lowe]

Please look over the proposed API and make criticisms and suggestions.

CLASSES

timestamp

A timestamp is a value indicating a particular point in
time.  Arithmetic is not possible with timestamps, but they may be
compared.  Internally, timestamps are always encoded as UTC.

duration

A duration is a value indicating a particular duration.  Arithmetic
is possible with durations, and they may be also be added to
timestamps to produce another timestamp.

Duration slots are entirely seperate from each other - no rollover is
applied during arithmetic.  A one day duration is treated differently
from a 24 hour duration.  Duration slots must be always be positive
integers.

When adding durations to each other, each slot is added to the
corresponding slot.  When adding a duration to a timestamp, the slots
are added to the timestamp in order of increasing resolution.  The
timestamp is modified in such a way that each duration slot affects
only the decoded values of equal or less resolution.  Illegal dates
will signal an error.

Example:
(+ @D1M @2008-03-05)  => @2008-04-05 ; adding one month
(+ @D30D @2008-03-05) => @2008-04-04 ; adding 30 days
(+ @D1M60D @2008-03-05) => @2008-06-05 ; adding one month and 60 days
;; Adding one day and five minutes
(+ @D1D5M @2008-03-05T23:59:00) => @2008-03-07T00:04:00

timezone

Timezones are local modifications to UTC. They are only applied when
encoding or decoding a timestamp.

CONSTANTS

+day-names+
+short-day-names+
+month-names+
+short-month-names+

+days-per-week+
+hours-per-day+
+seconds-per-day+
+seconds-per-hour+
+seconds-per-minute+
+minutes-per-day+
+minutes-per-hour+

SPECIAL VARIABLES

*default-timezone*

When an encoding or decoding timestamp function is called without an
explicit timezone, the timezone stored here is used.

MACROS

with-decoded-timestamp ((&key nsec sec minute hour day month year day-of-week
daylight-p timezone) timestamp &body body)

Binds various parts of the timestamp to variables in the body.

TIMESTAMP ENCODING

make-timestamp (&rest args)

Creates an instance of a timestamp, given the raw timestamp data.  Do
we even want this as an exported API?  The internal representation of
timestamps should probably be opaque.  Might be necessary for
efficient serialization, though.

clone-timestamp (timestamp)

Given a timestamp, returns another timestamp of the same value.

universal-to-timestamp (&key universal nsec timezone)

Converts a universal time into a timestamp with the given nanosecond
field.  If timezone is omitted, the default timezone is used.

unix-to-timestamp (&key unix nsec timezone)

Converts the unix time to a timestamp with the given nanosecond field.
If timezone is omitted, the default timezone is used.

parse-duration (durationstr &key (date-separator #\-) (date-time-separator #\T))

Parses a duration in ISO format.

parse-timestring (timestring &rest args)

Parses a timestamp in ISO format.  This function may raise an error if
the string is not in ISO format, or if an attempt to create an invalid
timestamp is detected.

encode-timestamp (nsec sec minute hour day month year &key (timezone
*default-timezone*) into)

Encodes a timestamp with the given time values.  This function may
raise an error if an invalid timestamp is specified.

now ()

Returns a timestamp corresponding to the current instant in time.

today ()

Returns a timestamp corresponding to midnight UTC of the current date.

first-day-of-year (timestamp-or-year &key into timezone)
last-day-of-year (timestamp-or-year &key into timezone)
first-day-of-month (timestamp &key into timezone)
last-day-of-month (timestamp &key into timezone)
first-day-of-week (timestamp &key into timezone)
last-day-of-week (timestamp &key into timezone)

Returns the first or last days of various time periods.  If a
timestamp is passed as INTO, the value is altered and the timestamp
returned.  Otherwise, a new timestamp is returned.


TIMESTAMP DECODING

timestamp-to-unix (timestamp &key timezone)
timestamp-to-universal (timestamp &key timezone)
decode-timestamp (timestamp &key timezone)
format-timestamp (format timestamp &key timezone)
format-datestring (date &key timezone)
format-duration (duration &key (omit-date-part-p nil) (omit-time-part-p nil)
format-timestring (timestamp &key destination timezone (omit-date-part-p nil)
timestamp-century
timestamp-day
timestamp-day-of-week (timestamp &key timezone)
timestamp-day-of-year
timestamp-decade
timestamp-decode-date (time &key timezone)
timestamp-decode-time (timestamp &key timezone)
timestamp-hour
timestamp-iso-day-of-week
timestamp-iso-year
timestamp-microseconds
timestamp-millennium
timestamp-milliseconds
timestamp-minute
timestamp-month
timestamp-quarter
timestamp-second
timestamp-week
timestamp-year

TIMESTAMP MANIPULATION

age (time &key from (unit :seconds))

Returns an integer (not a duration) representing the time difference in the
given units

timestamp+ (time duration &rest durations)
timestamp- (time duration &rest durations)

Timestamp/duration arithmetic functions.

timestamp> (time &rest times)
timestamp< (time &rest times)
timestamp>= (time &rest times)
timestamp<= (time &rest times)
timestamp= (time &rest times)
timestamp/= (time &rest times)

Comparison between timestamps.

timestamp-max (time &rest times)
timestamp-min (time &rest times)

Returns the earliest (min) or the latest (max) timestamp.

timestamp-ceiling (time unit &key timezone)
timestamp-floor (time unit &key timezone)

Truncates the timestamp to the given unit.  timestamp-ceiling truncates to the
maximum possible value, timestamp-floor truncates to the minimum possible value.

DURATION FUNCTIONS

make-duration (&key (nsec 0) (usec 0) (msec 0) (sec 0) (minute 0) (hour 0) (day
0) (week 0) (months 0) (years 0))
duration+ (duration &rest durations)
duration- (duration &rest durations)
duration* (duration &rest numbers)


TIMEZONE FUNCTIONS

reread-timezone-repository ()
define-timezone (zone-name zone-file &key (load nil))
timezone= (timezone-1 timezone-2)

UTILITY FUNCTIONS

interval-overlaps-p (time-a duration-a time-b duration-b)

Returns T if the intervals overlap in time.  Otherwise returns NIL.

astronomical-julian-date (timestamp)
modified-julian-date (timestamp)

Returns the julian dates as a floating-point value.

days-in-month (month year)

Returns the number of days in the current month.

days-to-years (days)
years-to-days (years)

These functions are of dubious utility.   Should we keep them at all?

enable-read-macros ()

Enables the reader macros for reading literal timestamps and durations.