Flowdock

date and datetime class - Tadayoshi Funaba 1998-2011

‘date’ provides two classes Date and DateTime.

Terms and definitions

Some terms and definitions are based on ISO 8601 and JIS X 0301.

calendar date

The calendar date is a particular day of a calendar year, identified by its ordinal number within a calendar month within that year.

In those classes, this is so-called “civil”.

ordinal date

The ordinal date is a particular day of a calendar year identified by its ordinal number within the year.

In those classes, this is so-called “ordinal”.

week date

The week date is a date identified by calendar week and day numbers.

The calendar week is a seven day period within a calendar year, starting on a Monday and identified by its ordinal number within the year; the first calendar week of the year is the one that includes the first Thursday of that year. In the Gregorian calendar, this is equivalent to the week which includes January 4.

In those classes, this so-called “commercial”.

julian day number

The Julian day number is in elapsed days since noon (Greenwich mean time) on January 1, 4713 BCE (in the Julian calendar).

In this document, the astronomical Julian day number is same as the original Julian day number. And the chronological Julian day number is a variation of the Julian day number. Its days begin at midnight on local time.

In this document, when the term “Julian day number” simply appears, it just refers to “chronological Julian day number”, not the original.

In those classes, those are so-called “ajd” and “jd”.

modified julian day number

The modified Julian day number is in elapsed days since midnight (Coordinated universal time) on November 17, 1858 CE (in the Gregorian calendar).

In this document, the astronomical modified Julian day number is same as the original modified Julian day number. And the chronological modified Julian day number is a variation of the modified Julian day number. Its days begin at midnight on local time.

In this document, when the term “modified Julian day number” simply appears, it just refers to “chronological modified Julian day number”, not the original.

In those classes, this is so-called “mjd”.

Date

A subclass of Object includes Comparable module, easily handles date.

Date object is created with Date::new, Date::jd, Date::ordinal, Date::commercial, Date::parse, Date::strptime, Date::today, Time#to_date or etc.

require 'date'

Date.new(2001,2,3)           #=> #<Date: 2001-02-03 ...>
Date.jd(2451944)             #=> #<Date: 2001-02-03 ...>
Date.ordinal(2001,34)        #=> #<Date: 2001-02-03 ...>
Date.commercial(2001,5,6)    #=> #<Date: 2001-02-03 ...>
Date.parse('2001-02-03')     #=> #<Date: 2001-02-03 ...>
Date.strptime('03-02-2001', '%d-%m-%Y')
                             #=> #<Date: 2001-02-03 ...>
Time.new(2001,2,3).to_date   #=> #<Date: 2001-02-03 ...>

All date objects are immutable; hence cannot modify themselves.

The concept of this date object can be represented as a tuple of the day count, the offset and the day of calendar reform.

The day count denotes the absolute position of a temporal dimension. The offset is relative adjustment, which determines decoded local time with the day count. The day of calendar reform denotes the start day of the new style. The old style of the West is the Julian calendar which was adopted by Caersar. The new style is the Gregorian calendar, which is the current civil calendar of many countries.

The day count is virtually the astronomical Julian day number. The offset in this class is usually zero, and cannot be specified directly.

An optional argument the day of calendar reform (start) as a Julian day number, which should be 2298874 to 2426355 or -/+oo. The default value is Date::ITALY (2299161=1582-10-15). See also sample/cal.rb.

$ ruby sample/cal.rb -c it 10 1582
    October 1582
 S  M Tu  W Th  F  S
    1  2  3  4 15 16
17 18 19 20 21 22 23
24 25 26 27 28 29 30
31

$ ruby sample/cal.rb -c gb  9 1752
   September 1752
 S  M Tu  W Th  F  S
       1  2 14 15 16
17 18 19 20 21 22 23
24 25 26 27 28 29 30

Date object has various methods. See each reference.

d = Date.parse('3rd Feb 2001')
                             #=> #<Date: 2001-02-03 ...>
d.year                       #=> 2001
d.mon                        #=> 2
d.mday                       #=> 3
d.wday                       #=> 6
d += 1                       #=> #<Date: 2001-02-04 ...>
d.strftime('%a %d %b %Y')    #=> "Sun 04 Feb 2001"

DateTime

A subclass of Date easily handles date, hour, minute, second and offset.

DateTime does not consider any leapseconds, does not track any summer time rules.

DateTime object is created with DateTime::new, DateTime::jd, DateTime::ordinal, DateTime::commercial, DateTime::parse, DateTime::strptime, DateTime::now, Time#to_datetime or etc.

require 'date'

DateTime.new(2001,2,3,4,5,6)
                     #=> #<DateTime: 2001-02-03T04:05:06+00:00 ...>

The last element of day, hour, minute or senond can be fractional number. The fractional number’s precision is assumed at most nanosecond.

DateTime.new(2001,2,3.5)
                     #=> #<DateTime: 2001-02-03T12:00:00+00:00 ...>

An optional argument the offset indicates the difference between the local time and UTC. For example, Rational(3,24) represents ahead of 3 hours of UTC, Rational(-5,24) represents behind of 5 hours of UTC. The offset should be -1 to +1, and its precision is assumed at most second. The default value is zero (equals to UTC).

DateTime.new(2001,2,3,4,5,6,Rational(3,24))
                     #=> #<DateTime: 2001-02-03T03:04:05+03:00 ...>

also accepts string form.

DateTime.new(2001,2,3,4,5,6,'+03:00')
                     #=> #<DateTime: 2001-02-03T03:04:05+03:00 ...>

An optional argument the day of calendar reform (start) denotes a Julian day number, which should be 2298874 to 2426355 or -/+oo. The default value is Date::ITALY (2299161=1582-10-15).

DateTime object has various methods. See each reference.

d = DateTime.parse('3rd Feb 2001 04:05:06+03:30')
                     #=> #<DateTime: 2001-02-03T04:05:06+03:30 ...>
d.hour               #=> 4
d.min                #=> 5
d.sec                #=> 6
d.offset             #=> (7/48)
d.zone               #=> "+03:30"
d += Rational('1.5')
                     #=> #<DateTime: 2001-02-04%16:05:06+03:30 ...>
d = d.new_offset('+09:00')
                     #=> #<DateTime: 2001-02-04%21:35:06+09:00 ...>
d.strftime('%I:%M:%S %p')
                     #=> "09:35:06 PM"
d > DateTime.new(1999)
                     #=> true

DateTime serialization/deserialization

Show files where this class is defined (2 files)
Register or log in to add new notes.