README.rdoc

Path: README.rdoc
Last Update: Sun Aug 24 19:00:48 +0200 2008

Chronos

INDEXING

Name:Chronos
Gem:chronos
Summary:Library to deal with Date, Time, Durations and Intervals.
Author:Stefan Rusterholz <stefan.rusterholz+chronos at gmail.com>
Version:0.1.1
Website:chronos.rubyforge.org/
Git Repository:github.com/apeiros/chronos
Bugtracker:rubyforge.org/tracker/?atid=25774&group_id=6649&func=browse
Feature Requests:rubyforge.org/tracker/?atid=25777&group_id=6649&func=browse
License:Ruby License (see LICENSE.txt)

SUMMARY

Chronos is a library that lets you easily deal with various kinds of calculations with dates, times, durations and intervals.

DESCRIPTION

(none yet)

IMPORTANT

Date, Time and Duration don‘t satisfy usual algebraic laws. Many operations are a matter of definition. It is very likely that your expectation might be broken at some points. Read the NOTES.rdoc for ambiguous cases and how they are solved in Chronos.

INSTALLING

Via RubyGems

You need for the installation:

  • rubygems >= 1.2.0

You need for some of the rake tasks:

  • bacon
  • flexmock
  • git
  • hpricot
  • rcov
  • rdiscount (or markdown)
  • rdoc
  • rspec

To install, do:

        gem install chronos

Note: you might have to use ‘sudo gem install chronos‘

From Github

You need for the installation:

  • rubygems >= 1.2.0

You need for some of the rake tasks:

  • bacon
  • flexmock
  • git
  • hpricot
  • rcov
  • rdiscount (or markdown)
  • rdoc
  • rspec

To install, do:

        curl -L -o chronos.tgz http://github.com/apeiros/chronos/tarball/master
        tar -xfz chronos.tgz
        cd apeiros-chronos-<big number here>/
        rake gem:install

Note: you might have to use ‘sudo rake gem:install‘

EXAMPLES

See in the examples directory for code examples.

DESIGN

General

In general for all structures there are calendary-agnostic classes. Those are directly defined within the Chronos module. The calendary specific subclasses are then defined as ::Chronos::Classname::Calendarname. There are shortcuts defined via specific requires. E.g. if you require ‘chronos/calendarname’ it will map all ::Chronos::Classname::Calendarname to ::Classname for convenience.

Datetime

A datetime is a point on the axis of time. This axis has an origin (zero point). For chronos this origin is defined to be backdated gregorian datetime 0000-01-01T00:00:00Z. The units to measure the distance from this origin is days+picoseconds, where 8.64e16 picoseconds is 1 day. The calendar specific classes then can represent that date/time in the units defined for that calendar, such as gregorian can represent that distance from origin as year-month-day"T"hour:minute:second.fraction┬▒offset. Timezone and DST are only representational offsets on top of that distance. That means that 2008-01-01T12:00Z and 2008-01-01T14:00+02:00 have the same distance, but are represented differently due to the different offset. Just as "May" (english) and "Mai" (german) are different representations of the same month. So Datetime and all its subclasses store date and time without representational offsets, those are only respected when accessing calendary-specific values, such as month, day, hour etc.

CREDITS

Yukihiro "Matz" Matsumoto:For ruby
Jarrett C.:Helping with the C implementation
Various People:For rubygems, rake, all the support in ruby-lang, ruby-pro and the ruby-talk ML

LINKS

Website:chronos.rubyforge.org/
Git Repository:github.com/apeiros/chronos
Report a bug:rubyforge.org/tracker/?func=add&group_id=6649&atid=25774
Request a feature:rubyforge.org/tracker/?func=add&group_id=6649&atid=25777
ISO 8601:en.wikipedia.org/wiki/ISO_8601

[Validate]