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

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. Sources for Time Zone and Daylight Saving Time Data

Techniques

• Conversion Gregorian Date <=> Julian Day
  • 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
  • 1582-10-04 => 1582-10-15

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:
    • ?
  • Pros:
    • more space-efficient
    • ?
• having only one type for Date/Time
  • Used by: Cocoa, Go, .Net
  • Cons:
    • loss of expressiveness (e.g. for acquaintances' birthdays often the time of birth is not known)
    • ?
  • Pros:
    • simpler interfaces, fewer classes
    • ?

Integers vs floats representation

All 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: int32 (days since 1400-01-01)
    • Go: int64 (seconds since the Unix Time epoch) + int32 (nanoseconds)
    • Haskell: arbitrary-precision integers (days since Modified Julian Day 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 date/time for internal state. It does not matter much, which instant in time one chooses if the type is large enough (Year 2038 problem for int32).

Options:

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

Separate Date/Time and Calendar interfaces

Options:

• Date/Time coupled to a calendar
  • Used by:
    • Qt: Gregorian calendar
  • Cons:
    • ?
  • Pros:
    • ?
• Date/Time tied to a configurable calendar
  • Used by: Boost, Joda
  • Cons:
    • ?
  • Pros:
    • ?
• Date/Time independent of a calendar
  • Used by: Cocoa
  • Cons:
    • ?
  • Pros:
    • ?

Support for Date/Time without a timezone

When the timezone information is missing, e.g. parsing from a textual representation, there are the following options:

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
    • ?
• 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.
    • ?
  • Pros:
    • ?

Reference

1. Language: C - time.h - glib - libtai
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. Consists of:
     • Seconds (int64) since the Unix epoch
     • Nanoseconds (int32)
     • Location
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).
   • 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

Types

• Date represents time points with a resolution of days
• Time represents XXX
• DateTime represents time points with a resolution of XXX
• Month an enum: January, February, ...
• Weekday an enum: Monday, Tuesday, ...

Conversion to/from other date representations

• Date -> Gregorian Date (y,m,d)
• Date <- Gregorian Date (y,m,d)
  • Feb 29 should be legal/illegal depending on leap years
• Date <- Julian Day
• Date -> Julian Day
• Date -> week number
• Date -> day number
• Date -> day of year number
• Date -> day of week number
  • should we use an enum instead?

Calculations

• Instant +/- Duration gives a Instant relative to the former
• Instant - Instant gives the Duration between them
• Duration +/- Duration gives an extended/reduced Duration
  • what about negative Durations?
• Period +/- Duration gives an extended/reduced Period
  • what about negative Durations?

Conversion to/from strings

• Date <-> user formatted string
• Date <-> ISO 8601 string
• Date <-> localized string