summaryrefslogtreecommitdiff
path: root/ext/date/date_core.c
diff options
context:
space:
mode:
Diffstat (limited to 'ext/date/date_core.c')
-rw-r--r--ext/date/date_core.c284
1 files changed, 136 insertions, 148 deletions
diff --git a/ext/date/date_core.c b/ext/date/date_core.c
index ce5ff2fd22..3a10fcb746 100644
--- a/ext/date/date_core.c
+++ b/ext/date/date_core.c
@@ -9394,154 +9394,142 @@ Init_date_core(void)
rb_define_singleton_method(cDate, "_load", date_s__load, 1);
/*
- :markup: Markdown
-
- ## DateTime
-
- A subclass of Date that easily handles date, hour, minute, second and
- offset.
-
- DateTime does not consider any leap seconds, 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 second 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-03T04:05:06+03:00 ...>
-
- also accepts string form.
-
- DateTime.new(2001,2,3,4,5,6,'+03:00')
- #=> #<DateTime: 2001-02-03T04:05:06+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
-
- ### When should you use DateTime and when should you use Time?
-
- It's a common misconception that [William Shakespeare][1] and
- [Miguel de Cervantes][2] died on the same day in history -
- so much so that UNESCO named April 23 as [World Book Day
- because of this fact][3].
- However because England hadn't yet adopted [Gregorian Calendar
- Reform][4] (and wouldn't until [1752][5]) their deaths are
- actually 10 days apart. Since Ruby's `Time` class implements a
- [proleptic Gregorian calendar][6] and has no concept of
- calendar reform then there's no way to express this. This is
- where `DateTime` steps in:
-
- ``` irb
- >> shakespeare = DateTime.iso8601('1616-04-23', Date::ENGLAND)
- => Tue, 23 Apr 1616 00:00:00 +0000
- >> cervantes = DateTime.iso8601('1616-04-23', Date::ITALY)
- => Sat, 23 Apr 1616 00:00:00 +0000
- ```
-
- Already you can see something's weird - the days of the week
- are different, taking this further:
-
- ``` irb
- >> cervantes == shakespeare
- => false
- >> (shakespeare - cervantes).to_i
- => 10
- ```
-
- This shows that in fact they died 10 days apart (in reality 11
- days since Cervantes died a day earlier but was buried on the
- 23rd). We can see the actual date of Shakespeare's death by
- using the `gregorian` method to convert it:
-
- ``` irb
- >> shakespeare.gregorian
- => Tue, 03 May 1616 00:00:00 +0000
- ```
-
- So there's an argument that all the celebrations that take
- place on the 23rd April in Stratford-upon-Avon are actually
- the wrong date since England is now using the Gregorian
- calendar. You can see why when we transition across the reform
- date boundary:
-
- ``` irb
- # start off with the anniversary of Shakespeare's birth in 1751
- >> shakespeare = DateTime.iso8601('1751-04-23', Date::ENGLAND)
- => Tue, 23 Apr 1751 00:00:00 +0000
-
- # add 366 days since 1752 is a leap year and April 23 is after February 29
- >> shakespeare + 366
- => Thu, 23 Apr 1752 00:00:00 +0000
-
- # add another 365 days to take us to the anniversary in 1753
- >> shakespeare + 366 + 365
- => Fri, 04 May 1753 00:00:00 +0000
- ```
-
- As you can see, if we're accurately tracking the number of
- [solar years][9] since Shakespeare's birthday then the correct
- anniversary date would be the 4th May and not the 23rd April.
-
- So when should you use `DateTime` in Ruby and when should
- you use `Time`? Almost certainly you'll want to use `Time`
- since your app is probably dealing with current dates and
- times. However, if you need to deal with dates and times in a
- historical context you'll want to use `DateTime` to avoid
- making the same mistakes as UNESCO. If you also have to deal
- with timezones then best of luck - just bear in mind that
- you'll probably be dealing with [local solar times][7], since
- it wasn't until the 19th century that the introduction of the
- railways necessitated the need for [Standard Time][8] and
- eventually timezones.
-
- [1]: http://en.wikipedia.org/wiki/William_Shakespeare
- [2]: http://en.wikipedia.org/wiki/Miguel_de_Cervantes
- [3]: http://en.wikipedia.org/wiki/World_Book_Day
- [4]: http://en.wikipedia.org/wiki/Gregorian_calendar#Gregorian_reform
- [5]: http://en.wikipedia.org/wiki/Calendar_(New_Style)_Act_1750
- [6]: http://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar
- [7]: http://en.wikipedia.org/wiki/Solar_time
- [8]: http://en.wikipedia.org/wiki/Standard_time#Great_Britain
- [9]: http://en.wikipedia.org/wiki/Tropical_year
+ * == DateTime
+ *
+ * A subclass of Date that easily handles date, hour, minute, second and
+ * offset.
+ *
+ * DateTime does not consider any leap seconds, 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 second 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, <tt>Rational(3,24)</tt>
+ * represents ahead of 3 hours of UTC, <tt>Rational(-5,24)</tt> 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-03T04:05:06+03:00 ...>
+ *
+ * also accepts string form.
+ *
+ * DateTime.new(2001,2,3,4,5,6,'+03:00')
+ * #=> #<DateTime: 2001-02-03T04:05:06+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
+ *
+ * === When should you use DateTime and when should you use Time?
+ *
+ * It's a common misconception that
+ * {William Shakespeare}[http://en.wikipedia.org/wiki/William_Shakespeare]
+ * and
+ * {Miguel de Cervantes}[http://en.wikipedia.org/wiki/Miguel_de_Cervantes]
+ * died on the same day in history -
+ * so much so that UNESCO named April 23 as
+ * {World Book Day because of this fact}[http://en.wikipedia.org/wiki/World_Book_Day].
+ * However because England hadn't yet adopted
+ * {Gregorian Calendar Reform}[http://en.wikipedia.org/wiki/Gregorian_calendar#Gregorian_reform]
+ * (and wouldn't until {1752}[http://en.wikipedia.org/wiki/Calendar_(New_Style)_Act_1750])
+ * their deaths are actually 10 days apart.
+ * Since Ruby's Time class implements a
+ * {proleptic Gregorian calendar}[http://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar]
+ * and has no concept of calendar reform then there's no way
+ * to express this. This is where DateTime steps in:
+ *
+ * shakespeare = DateTime.iso8601('1616-04-23', Date::ENGLAND)
+ * #=> Tue, 23 Apr 1616 00:00:00 +0000
+ * cervantes = DateTime.iso8601('1616-04-23', Date::ITALY)
+ * #=> Sat, 23 Apr 1616 00:00:00 +0000
+ *
+ * Already you can see something's weird - the days of the week
+ * are different, taking this further:
+ *
+ * cervantes == shakespeare
+ * #=> false
+ * (shakespeare - cervantes).to_i
+ * #=> 10
+ *
+ * This shows that in fact they died 10 days apart (in reality
+ * 11 days since Cervantes died a day earlier but was buried on
+ * the 23rd). We can see the actual date of Shakespeare's death by
+ * using the #gregorian method to convert it:
+ *
+ * shakespeare.gregorian
+ * #=> Tue, 03 May 1616 00:00:00 +0000
+ *
+ * So there's an argument that all the celebrations that take
+ * place on the 23rd April in Stratford-upon-Avon are actually
+ * the wrong date since England is now using the Gregorian calendar.
+ * You can see why when we transition across the reform
+ * date boundary:
+ *
+ * # start off with the anniversary of Shakespeare's birth in 1751
+ * shakespeare = DateTime.iso8601('1751-04-23', Date::ENGLAND)
+ * #=> Tue, 23 Apr 1751 00:00:00 +0000
+ *
+ * # add 366 days since 1752 is a leap year and April 23 is after February 29
+ * shakespeare + 366
+ * #=> Thu, 23 Apr 1752 00:00:00 +0000
+ *
+ * # add another 365 days to take us to the anniversary in 1753
+ * shakespeare + 366 + 365
+ * #=> Fri, 04 May 1753 00:00:00 +0000
+ *
+ * As you can see, if we're accurately tracking the number of
+ * {solar years}[http://en.wikipedia.org/wiki/Tropical_year]
+ * since Shakespeare's birthday then the correct anniversary date
+ * would be the 4th May and not the 23rd April.
+ *
+ * So when should you use DateTime in Ruby and when should
+ * you use Time? Almost certainly you'll want to use Time
+ * since your app is probably dealing with current dates and
+ * times. However, if you need to deal with dates and times in a
+ * historical context you'll want to use DateTime to avoid
+ * making the same mistakes as UNESCO. If you also have to deal
+ * with timezones then best of luck - just bear in mind that
+ * you'll probably be dealing with
+ * {local solar times}[http://en.wikipedia.org/wiki/Solar_time],
+ * since it wasn't until the 19th century that the introduction
+ * of the railways necessitated the need for
+ * {Standard Time}[http://en.wikipedia.org/wiki/Standard_time#Great_Britain]
+ * and eventually timezones.
*/
cDateTime = rb_define_class("DateTime", cDate);