summaryrefslogtreecommitdiff
path: root/ext/date
diff options
context:
space:
mode:
authorzzak <zzak@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2015-05-31 19:49:03 +0000
committerzzak <zzak@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2015-05-31 19:49:03 +0000
commit45458752d3f54ac81661d93aa55b8b5805f78138 (patch)
tree8af71b95997ffa521994d6bd7314493ca2885a9b /ext/date
parentac6990c75f6850a845c4c7d09d96ebc5e17cea0a (diff)
* ext/date/date_core.c: [DOC] Add comparison of Time and DateTime
Patch provided by @pixeltrix git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@50702 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
Diffstat (limited to 'ext/date')
-rw-r--r--ext/date/date_core.c61
1 files changed, 60 insertions, 1 deletions
diff --git a/ext/date/date_core.c b/ext/date/date_core.c
index 07b65a7..3dfadbe 100644
--- a/ext/date/date_core.c
+++ b/ext/date/date_core.c
@@ -9472,7 +9472,66 @@ Init_date_core(void)
rb_define_method(cDate, "marshal_load", d_lite_marshal_load, 1);
rb_define_singleton_method(cDate, "_load", date_s__load, 1);
- /* datetime */
+ /*
+ :markup: Markdown
+
+ # 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 use 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
+ */
cDateTime = rb_define_class("DateTime", cDate);