Lib datetime

A library for date and time.

Concepts

• Instant: an infinitesimal location in the time continuum.
• Time Interval: a part of the the time continuum limited by two instants.
• Time Scale: a system of ordered marks of instants. One instant is chosen as the Origin, see Epoch.
• Epoch: the origin of a particular era, e.g. the Incarnation of Jesus.
• Time Point: an instant, defined by the means of a Time Scale.
• Duration: a non-negative length of time.
• International Atomic Time (TAI): ?
• Coordinated Universal Time (UTC): is the primary time scale by which the world regulates clocks and time.
• Standard Time: the result of synchronizing clocks in different geographical locations within a time zone to the same time.
• Local Time: a time in the local non-UTC based standard time

See ISO 8601, which relies on IEC 60050-111, IEC 60050-713.

Things to be aware of

• leap seconds
• infinity
• high resolution
• network time sources
• daylight saving time
• eras, e.g. BC/AD
• time zone changes, sometimes on short notice

1. Announcement to mailing list

• Proposed editor: your name
• Date proposed: date of proposal
• Link: link to email

Notes from discussion on mailing list

• note
• note
• note

2. Research of standards and techniques

Standards

1. ISO 31-1 defines the units day, hour, minute, second for time, time interval and duration
2. ISO 8601days
3. Gregorian calendar - 1582-10-04 last day of the Julian calendar, followed by - 1582-10-15 first day of the Gregorian calendar
4. ITU-R TF.460-5
5. Coordinated Universal Time (UTC) - Leap second
6. Julian Day - Epoch: -4714-11-24T12:00:00Z
7. Modified Julian Day - Epoch: 1858-11-17T00:00:00Z - MJD = JD - 2400000.5
8. Unix Time - Epoch: 1970-01-01T00:00:00Z - UnixTime = (JD − 2440587.5) × 86400
9. TAI (Temps Atomique International) - The underlying atomic time, non-leap seconds - International Atomic Time - UTC vs. TAI discussion
10. Network Time Protocol
11. IANA Time Zone Database
12. Sources for Time Zone and Daylight Saving Time Data

Techniques

• Gregorian Date <=> Julian Day conversion:
  • Letter to the editor of Communications of the ACM (CACM, volume 11, number 10, October 1968, p.657) Henry F. Fliegel and Thomas C. Van Flandern

Those intended to follow (and why)

Those intended to ignore (and why)

3. Research of libraries from other languages

• Proposal to Add Date-Time to the C++ Standard Library
• https://github.com/ThreeTen/threeten/wiki/Multi-calendar-system

Simple immutable objects

Used by: Boost, Cocoa, JSR-310

Separate date and time types

Options:

• having separate types for Date and Time
  • Used by: Boost, Haskell, Joda, Python, Qt, Ruby
  • Cons:
    • more complex API (to use and implement)
  • Pros:
    • more space-efficient if one only needs date or time
    • more expressive (e.g. for birthdays often the time of birth is not known)
• having only one type for Date/Time
  • Used by: Cocoa, Go, .Net
  • Cons:
    • less space-efficient if one only needs date or time
    • less expressive (e.g. for birthdays often the time of birth is not known)
  • Pros:
    • simpler API (to use and implement)

Integers vs floats

All known representations are based on the time passed from a certain epoch, either counted in days or seconds/milliseconds/nanoseconds.

Options:

• floats
  • Used by:
    • Cocoa: NSTimeInterval := double (seconds since the Cocoa epoch)
  • Cons:
    • ?
  • Pros:
    • ?
• integers
  • Used by:
    • Boost: int?? (template argument) (days since 1400-01-01)
    • Go: int64 (seconds since 0001-01-01) + int32 (nanoseconds)
    • Haskell: arbitrary-precision integers (days since Modified Julian Day epoch)
    • Joda: long (milliseconds since the Unix Time epoch)
    • Qt: int64 (days since the Julian Day epoch)
    • Ruby: int (days since the Julian Day epoch)
  • Cons:
    • ?
  • Pros:
    • faster comparison and calculation
    • more space-efficient
    • lossless calculations

Epochs

Epochs are the reference for the internal date/time counting. It does not matter so much, which instant in time one chooses if the type is large enough (Year 2038 problem for int32).

Options:

• 0001-01-01T00:00:00Z
  • Used by: Go
• Julian Day
  • Used by: Qt
  • Cons:
    • ?
  • Pros:
    • ?
• Modified Julian Day
  • Used by: Haskell
  • Cons:
    • ?
  • Pros:
    • more space-efficient
• Unix Time
  • Used by: Joda, Unix
  • Cons:
    • ?
  • Pros:
    • ?
• 2001-01-01T00:00:00Z
  • Used by: Apple Cocoa
  • Cons:
    • ?
  • Pros:
    • ?

Separate date/time and calendar interfaces

Options:

• date/time interface is coupled to a calendar (Gregorian)
  • Used by: Go, Qt
  • Cons:
    • ?
  • Pros:
    • less code is needed to get started
• date/time interface is tied to a configurable calendar
  • Used by: Boost, Joda
  • Cons:
    • ?
  • Pros:
    • not much code is needed to get started
• date/time interface is independent of a calendar
  • Used by:
    • Cocoa: NSCalendar create NSDates and are used for calendrical calculation
  • Cons:
    • more code is needed to get started
  • Pros:
    • seperated interfaces are themselves easier to understand and extend

Support for date/time without a timezone

Sometimes the timezone information is missing, e.g. parsing from a textual representation.

Options:

• support Date/Time with no attached timezone
  • Used by:
    • Joda: LocalDate, LocalTime, LocalDateTime
  • Cons:
    • more complex interfaces/types
    • ?
  • Pros:
    • clear distinction between dates that are comparable and date that are not
    • more space-efficient
• assume the local timezone if the timezone is not available
  • Used by:
    • Cocoa
  • Cons:
    • dates are created that appear to be comparable, but are not. One needs to keep tracks of those dates.
    • less space-efficient
  • Pros:
    • ?

Reference

1. Language: C - time.h - glib - libtai - Modernized <time.h> API proposal by Markus Kuhn
2. Language: C++ - Boost.Date_Time
   • boost::date_time
     • boost::date_time::date
     • [boost::date_time::period] (http://www.boost.org/doc/libs/1_53_0/doc/html/boost/date_time/period.html)
   • boost::date_time::gregorian
     • Gregorian
       • valid date range: 1400-01-01 to 9999-12-03
   • boost::date_time::posix_time
     • Posix Time
   • Unit tests - Qt
   • QDate
   • QTime: a clock time since midnight
   • QDateTime
   • Unit tests:
     • https://qt.gitorious.org/qt/qt/blobs/4.8/tests/auto/qdate/tst_qdate.cpp
     • https://qt.gitorious.org/qt/qt/blobs/4.8/tests/auto/qtime/tst_qtime.cpp
     • https://qt.gitorious.org/qt/qt/blobs/4.8/tests/auto/qdatetime/tst_qdatetime.cpp - QuantLib
   • Date
   • Period
   • Calendar
3. Language: Go - time
   • Duration: a duration with an int64 nanosecond count.
   • Location: maps time instants to the zone in use at that time.
   • Time: an instant in time with nanosecond precision.
4. Language: Haskell - Data.Time
5. Language: Java - JSR-310 - Joda-Time
   • DateTime: the datetime as milliseconds from the Unix epoch and a Chronology (calendar system).
   • Chronology
   • LocalDate: a date without a time zone.
   • LocalTime: a time without a time zone.
   • LocalDateTime: a datetime without a time zone. - java.util
   • java.util.Date: a time period with millisecond duration
   • java.util.Calendar
   • java.util.GregorianCalendar
   • java.util.TimeZone
   • java.util.SimpleTimeZone
6. Language: Objective-C - Cocoa Date and Time Programming Guide
   • NSDate
   • NSCalendar
   • NSDateComponents
7. Language: Python - builtin
   • datetime
     • distinguishes between "naive" and "aware" date/time objects
     • datetime.date
     • datetime.time
     • datetime.datetime
     • datetime.timedelta
     • datetime.timezone
   • time
   • calendar - pytz - dateutil
8. Language: Ruby - Date
9. Language: Scheme - SRFI 19

4. Module writing

• Pull request: link to bug