χρόνος

What is Chronos?

Chronos is a reusable code library, written in Smalltalk, for the creation of and computations with date and time values. It provides classes to represent and perform computations with point-in-time values, temporal extents (durations of time) and temporal intervals (specific periods of time, such as the quarter from 15 July 2005 through 14 October 2005.) Chronos implements the ANSI-Smalltalk Standard DateAndTime, DateAndTimeFactory, Duration and DurationFactory protocols.

Currently, there are versions available for VisualWorks, Squeak and Dolphin--although the Squeak and Dolphin versions lack some of the functionality herein described.

Chronos has been designed and architected for inter-Smalltalk portability. It is intended as a reference/standard implementation of advanced, rich date/time functionality for all Smalltalk flavors.

The current distribution is a beta version--mostly because there will probably be significant API changes in order to more fully support leap seconds.

Chronos Functionality Summary

  • Supports business, legal, historical and scientific use cases:

    • Provides time-of-day-preserving date arithmetic, so that adding days or months doesn't change the time-of-day when crossing a DST transition.

    • Provides full support for both scientific (scale-invariant) and civil (calendar/business/legal) durations.

    • Supports point-in-time values that are either invariant to Universal Time (as required by the ANSI Standard) or invariant to nominal time. UT-invariant point-in-time values compare as equal to all others whose designation in Universal Time is the same--regardless of their time zone or designation in local time. Nominal-time-invariant point-in-time values compare as equal to all others with the same local ("nominal") time, regardless of time zone or designation in Universal Time--so a single instance can correctly specify the first moment of New Year's Day (of a particular year) in any time zone. (Example of a problem solvable by means of nominal-time invariance.)

    • Provides for the definition/detection of annually-recurring events (e.g., holidays, anniversaries, legal deadlines, number of trading days on the NYSE between two dates...)

    • Provides resolution down to the nanosecond.

  • Provides comprehensive time zone functionality:

    • Fully supports the world-wide time zone rulesets defined by the Olson Timezone Database (the native time zone database of UNIX/MacOS X.)

    • Supports diachronic time zone rules that can change from one year to the next (For example, although you might know that Hawaii's current time zone offset is -10 hours, what you might not know is that on Dec 7, 1941 Hawaii's time zone offset was -10:30 hours. Chronos, however, knows this.)

    • Can automatically discover the local time zone from the Windows Registry or from the TZ "Environment Variable" (UNIX/MacOS X or Windows.)

    • Enables updating time zone rules without changing your application code (NOTE: US Daylight Saving Time extended by 4 weeks)

  • Supports various calendrical systems in addition to the international standard Gregorian calendar (e.g., Julian, Hebrew, Islamic, Persian...).

  • Provides very flexible formatting of date/time values, including extensible support for multiple locales, and "built in" support for ISO 8601 and RFC 2822 formats.

  • Provides very flexible parsing of dates, times and date-and-time values from character data--including full support for ISO 8601, RFC 2822, time zone names, time zone abbreviations and time zone offsets.

  • Provides high performance--usually significantly faster than the competition.

Getting Started Using Chronos

External Documentation

Document Name Description/Subject/Purpose
ANSI Smalltalk Standard The ANSI Standard is an excellent reference for the core Chronos API.  Chronos fully and completely conforms to the ANSI Smalltalk Standard regarding Date/Time behavior [Chronos is intended to serve as a reference implementation of  ANSI-Standard Smalltalk Date/Time behavior.]
Chronos Website Web site where the latest published/released versions of all code and documentation can be obtained.  Site also includes additional usage examples, and extensive references to educational material about the date/time domain.
Chronos Blog The author's blog.  Announcements, discussion of any an all subjects related to Chronos and the date/time domain.
Overview.html This document.
Installation.html Detailed instructions for installing the Chronos Date/Time Library and the Chronos Time Zone Repository. Required reading for full functionality.
Examples.html Executable examples (“do its”) illustrating usage and functionality.
Porting.html  Advice on porting Chronos to other platforms/environments.
Motivation.html Why use Chronos? [Under construction]

Documentation in the code itself

Most of the documentation for Chronos is in the code itself. The following "core API" classes have comments that should prove especially helpful in learning to use and obtain value from Chronos:

Class Name Remarks
ChronosTimezone Abstract class for all Chronos timezones, aliased by the global Timezone.
Calendar Abstract class for all Chronos calendars.
ScientificDuration Duration (temporal extent) implementation, aliased by the global Duration.
Timeperiod Implements intervals of time.

Although they are "core API" classes, the following have not yet been fully commented (although the ANSI Smalltalk Standard serves as an excellent reference for some of them):

Class Name Remarks
Timepoint Point-in-time implementation, aliased by the global DateAndTime.
AnnualDate Abstract class for partial dates that recur from year to year.
SemanticDatePolicy Handles definition and detection of “holidays.”
ChronosPrintPolicy Provides formatted printing of date, time and durational values.

[Chronos] All code (classes and methods, and all associated documentation,) distributed as part of the Chronos Date/Time library are © Copyright 2005-2006 by Alan L. Lovejoy.  All Rights Reserved. Usage is controlled by the Chronos License (which is included in the distribution as the contents of the file {chronos-license.txt}, and is also available from the Chronos web site {http://www.chronos-st.org/License.html})

"Do not go gentle into that good night,
Old age should burn and rave at the close of the day;
Rage, rage at the dying of the light!" -- Dylan Thomas