ruby-changes:43325
From: nagachika <ko1@a...>
Date: Tue, 14 Jun 2016 02:58:55 +0900 (JST)
Subject: [ruby-changes:43325] nagachika:r55399 (ruby_2_3): merge revision(s) 54721: [Backport #12311]
nagachika 2016-06-14 02:58:50 +0900 (Tue, 14 Jun 2016) New Revision: 55399 https://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=revision&revision=55399 Log: merge revision(s) 54721: [Backport #12311] * ext/date/date_core.c (Init_date_core): [DOC] Convert DateTime documentation to RDoc from Markdown. [ruby-core:75136] [Bug #12311] Modified directories: branches/ruby_2_3/ Modified files: branches/ruby_2_3/ChangeLog branches/ruby_2_3/ext/date/date_core.c branches/ruby_2_3/version.h Index: ruby_2_3/ext/date/date_core.c =================================================================== --- ruby_2_3/ext/date/date_core.c (revision 55398) +++ ruby_2_3/ext/date/date_core.c (revision 55399) @@ -9418,154 +9418,142 @@ Init_date_core(void) https://github.com/ruby/ruby/blob/trunk/ruby_2_3/ext/date/date_core.c#L9418 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); Index: ruby_2_3/version.h =================================================================== --- ruby_2_3/version.h (revision 55398) +++ ruby_2_3/version.h (revision 55399) @@ -1,10 +1,10 @@ https://github.com/ruby/ruby/blob/trunk/ruby_2_3/version.h#L1 #define RUBY_VERSION "2.3.2" -#define RUBY_RELEASE_DATE "2016-06-12" -#define RUBY_PATCHLEVEL 123 +#define RUBY_RELEASE_DATE "2016-06-14" +#define RUBY_PATCHLEVEL 124 #define RUBY_RELEASE_YEAR 2016 #define RUBY_RELEASE_MONTH 6 -#define RUBY_RELEASE_DAY 12 +#define RUBY_RELEASE_DAY 14 #include "ruby/version.h" Index: ruby_2_3/ChangeLog =================================================================== --- ruby_2_3/ChangeLog (revision 55398) +++ ruby_2_3/ChangeLog (revision 55399) @@ -1,3 +1,9 @@ https://github.com/ruby/ruby/blob/trunk/ruby_2_3/ChangeLog#L1 +Tue Jun 14 02:58:41 2016 Marcus Stollsteimer <sto.mar@w...> + + * ext/date/date_core.c (Init_date_core): [DOC] Convert DateTime + documentation to RDoc from Markdown. + [ruby-core:75136] [Bug #12311] + Sun Jun 12 02:36:52 2016 NARUSE, Yui <naruse@r...> * regcomp.c (compile_length_tree): return error code immediately Property changes on: ruby_2_3 ___________________________________________________________________ Modified: svn:mergeinfo Merged /trunk:r54721 -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/