ruby-changes:42604
From: usa <ko1@a...>
Date: Fri, 22 Apr 2016 14:06:30 +0900 (JST)
Subject: [ruby-changes:42604] usa:r54678 (ruby_2_2): merge revision(s) 54444: [Backport #12233]
usa 2016-04-22 15:03:06 +0900 (Fri, 22 Apr 2016) New Revision: 54678 https://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=revision&revision=54678 Log: merge revision(s) 54444: [Backport #12233] * ext/date/date_core.c (Init_date_core): [DOC] fix misplaced doc of DateTime. [ruby-core:74729] [Bug #12233] Modified directories: branches/ruby_2_2/ Modified files: branches/ruby_2_2/ChangeLog branches/ruby_2_2/ext/date/date_core.c branches/ruby_2_2/version.h Index: ruby_2_2/ext/date/date_core.c =================================================================== --- ruby_2_2/ext/date/date_core.c (revision 54677) +++ ruby_2_2/ext/date/date_core.c (revision 54678) @@ -9164,67 +9164,6 @@ Init_date_core(void) https://github.com/ruby/ruby/blob/trunk/ruby_2_2/ext/date/date_core.c#L9164 * d += 1 #=> #<Date: 2001-02-04 ...> * d.strftime('%a %d %b %Y') #=> "Sun 04 Feb 2001" * - * - * == 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 */ cDate = rb_define_class("Date", rb_cObject); @@ -9472,7 +9411,156 @@ Init_date_core(void) https://github.com/ruby/ruby/blob/trunk/ruby_2_2/ext/date/date_core.c#L9411 rb_define_method(cDate, "marshal_load", d_lite_marshal_load, 1); rb_define_singleton_method(cDate, "_load", date_s__load, 1); - /* datetime */ + /* + :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 + */ cDateTime = rb_define_class("DateTime", cDate); Index: ruby_2_2/ChangeLog =================================================================== --- ruby_2_2/ChangeLog (revision 54677) +++ ruby_2_2/ChangeLog (revision 54678) @@ -1,3 +1,8 @@ https://github.com/ruby/ruby/blob/trunk/ruby_2_2/ChangeLog#L1 +Fri Apr 22 14:56:46 2016 Nobuyoshi Nakada <nobu@r...> + + * ext/date/date_core.c (Init_date_core): [DOC] fix misplaced doc + of DateTime. [ruby-core:74729] [Bug #12233] + Fri Apr 22 14:48:09 2016 Nobuyoshi Nakada <nobu@r...> * parse.y (parse_ident): allow keyword arguments just after a Index: ruby_2_2/version.h =================================================================== --- ruby_2_2/version.h (revision 54677) +++ ruby_2_2/version.h (revision 54678) @@ -1,6 +1,6 @@ https://github.com/ruby/ruby/blob/trunk/ruby_2_2/version.h#L1 #define RUBY_VERSION "2.2.5" #define RUBY_RELEASE_DATE "2016-04-22" -#define RUBY_PATCHLEVEL 298 +#define RUBY_PATCHLEVEL 299 #define RUBY_RELEASE_YEAR 2016 #define RUBY_RELEASE_MONTH 4 Property changes on: ruby_2_2 ___________________________________________________________________ Modified: svn:mergeinfo Merged /trunk:r54444 -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/