kotovalexarian-likes-github/ruby--ruby
1
0
Fork 0
mirror of https://github.com/ruby/ruby.git synced 2022-11-09 12:17:21 -05:00
Code Releases Activity

date_core.c: [DOC] markdown to rdoc [ci skip]

Browse source 
* ext/date/date_core.c (Init_date_core): [DOC] Convert DateTime
  documentation to RDoc from Markdown.
  [ruby-core:75136] [Bug #12311]

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@54721 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
This commit is contained in:
nobu 2016-04-23 02:21:29 +00:00
parent 88783116e0
commit f56a2c7293
2 changed files with 142 additions and 148 deletions
Download patch file Download diff file Expand all files Collapse all files

6
ChangeLog
View file

@ -1,3 +1,9 @@
Sat Apr 23 11:21:27 2016 Marcus Stollsteimer <sto.mar@web.de>
* ext/date/date_core.c (Init_date_core): [DOC] Convert DateTime
documentation to RDoc from Markdown.
[ruby-core:75136] [Bug #12311]
Sat Apr 23 09:03:35 2016 Nobuyoshi Nakada <nobu@ruby-lang.org> Sat Apr 23 09:03:35 2016 Nobuyoshi Nakada <nobu@ruby-lang.org>
* ruby.c: cygwin does not use w32_cmdvector, command line can be * ruby.c: cygwin does not use w32_cmdvector, command line can be

284
ext/date/date_core.c
View file

@ -9394,154 +9394,142 @@ Init_date_core(void)
rb_define_singleton_method(cDate, "_load", date_s__load, 1); rb_define_singleton_method(cDate, "_load", date_s__load, 1);
/* /*
:markup: Markdown * == DateTime
*
## DateTime * A subclass of Date that easily handles date, hour, minute, second and
* offset.
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 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 object is created with DateTime::new, DateTime::jd, * DateTime::strptime, DateTime::now, Time#to_datetime or etc.
DateTime::ordinal, DateTime::commercial, DateTime::parse, *
DateTime::strptime, DateTime::now, Time#to_datetime or etc. * require 'date'
*
require 'date' * DateTime.new(2001,2,3,4,5,6)
* #=> #<DateTime: 2001-02-03T04:05:06+00:00 ...>
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
The last element of day, hour, minute or second can be * at most nanosecond.
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 ...>
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>
An optional argument the offset indicates the difference * represents ahead of 3 hours of UTC, <tt>Rational(-5,24)</tt> represents
between the local time and UTC. For example, `Rational(3,24)` * behind of 5 hours of UTC. The offset should be -1 to +1, and
represents ahead of 3 hours of UTC, `Rational(-5,24)` represents * its precision is assumed at most second. The default value is
behind of 5 hours of UTC. The offset should be -1 to +1, and * zero(equals to UTC).
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 ...>
DateTime.new(2001,2,3,4,5,6,Rational(3,24)) *
#=> #<DateTime: 2001-02-03T04:05:06+03:00 ...> * also accepts string form.
*
also accepts string form. * DateTime.new(2001,2,3,4,5,6,'+03:00')
* #=> #<DateTime: 2001-02-03T04:05:06+03:00 ...>
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
An optional argument the day of calendar reform (start) denotes * -/+oo. The default value is +Date::ITALY+ (2299161=1582-10-15).
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.
*
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 = DateTime.parse('3rd Feb 2001 04:05:06+03:30') * d.hour #=> 4
#=> #<DateTime: 2001-02-03T04:05:06+03:30 ...> * d.min #=> 5
d.hour #=> 4 * d.sec #=> 6
d.min #=> 5 * d.offset #=> (7/48)
d.sec #=> 6 * d.zone #=> "+03:30"
d.offset #=> (7/48) * d += Rational('1.5')
d.zone #=> "+03:30" * #=> #<DateTime: 2001-02-04%16:05:06+03:30 ...>
d += Rational('1.5') * d = d.new_offset('+09:00')
#=> #<DateTime: 2001-02-04%16:05:06+03:30 ...> * #=> #<DateTime: 2001-02-04%21:35:06+09:00 ...>
d = d.new_offset('+09:00') * d.strftime('%I:%M:%S %p')
#=> #<DateTime: 2001-02-04%21:35:06+09:00 ...> * #=> "09:35:06 PM"
d.strftime('%I:%M:%S %p') * d > DateTime.new(1999)
#=> "09:35:06 PM" * #=> true
d > DateTime.new(1999) *
#=> true * === When should you use DateTime and when should you use Time?
*
### 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]
It's a common misconception that [William Shakespeare][1] and * and
[Miguel de Cervantes][2] died on the same day in history - * {Miguel de Cervantes}[http://en.wikipedia.org/wiki/Miguel_de_Cervantes]
so much so that UNESCO named April 23 as [World Book Day * died on the same day in history -
because of this fact][3]. * so much so that UNESCO named April 23 as
However because England hadn't yet adopted [Gregorian Calendar * {World Book Day because of this fact}[http://en.wikipedia.org/wiki/World_Book_Day].
Reform][4] (and wouldn't until [1752][5]) their deaths are * However because England hadn't yet adopted
actually 10 days apart. Since Ruby's `Time` class implements a * {Gregorian Calendar Reform}[http://en.wikipedia.org/wiki/Gregorian_calendar#Gregorian_reform]
[proleptic Gregorian calendar][6] and has no concept of * (and wouldn't until {1752}[http://en.wikipedia.org/wiki/Calendar_(New_Style)_Act_1750])
calendar reform then there's no way to express this. This is * their deaths are actually 10 days apart.
where `DateTime` steps in: * Since Ruby's Time class implements a
* {proleptic Gregorian calendar}[http://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar]
``` irb * and has no concept of calendar reform then there's no way
>> shakespeare = DateTime.iso8601('1616-04-23', Date::ENGLAND) * to express this. This is where DateTime steps in:
=> Tue, 23 Apr 1616 00:00:00 +0000 *
>> cervantes = DateTime.iso8601('1616-04-23', Date::ITALY) * shakespeare = DateTime.iso8601('1616-04-23', Date::ENGLAND)
=> Sat, 23 Apr 1616 00:00:00 +0000 * #=> 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: * Already you can see something's weird - the days of the week
* are different, taking this further:
``` irb *
>> cervantes == shakespeare * cervantes == shakespeare
=> false * #=> false
>> (shakespeare - cervantes).to_i * (shakespeare - cervantes).to_i
=> 10 * #=> 10
``` *
* This shows that in fact they died 10 days apart (in reality
This shows that in fact they died 10 days apart (in reality 11 * 11 days since Cervantes died a day earlier but was buried on
days since Cervantes died a day earlier but was buried on the * the 23rd). We can see the actual date of Shakespeare's death by
23rd). We can see the actual date of Shakespeare's death by * using the #gregorian method to convert it:
using the `gregorian` method to convert it: *
* shakespeare.gregorian
``` irb * #=> Tue, 03 May 1616 00:00:00 +0000
>> 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.
So there's an argument that all the celebrations that take * You can see why when we transition across the reform
place on the 23rd April in Stratford-upon-Avon are actually * date boundary:
the wrong date since England is now using the Gregorian *
calendar. You can see why when we transition across the reform * # start off with the anniversary of Shakespeare's birth in 1751
date boundary: * shakespeare = DateTime.iso8601('1751-04-23', Date::ENGLAND)
* #=> Tue, 23 Apr 1751 00:00:00 +0000
``` irb *
# start off with the anniversary of Shakespeare's birth in 1751 * # add 366 days since 1752 is a leap year and April 23 is after February 29
>> shakespeare = DateTime.iso8601('1751-04-23', Date::ENGLAND) * shakespeare + 366
=> Tue, 23 Apr 1751 00:00:00 +0000 * #=> Thu, 23 Apr 1752 00:00:00 +0000
*
# add 366 days since 1752 is a leap year and April 23 is after February 29 * # add another 365 days to take us to the anniversary in 1753
>> shakespeare + 366 * shakespeare + 366 + 365
=> Thu, 23 Apr 1752 00:00:00 +0000 * #=> Fri, 04 May 1753 00:00:00 +0000
*
# add another 365 days to take us to the anniversary in 1753 * As you can see, if we're accurately tracking the number of
>> shakespeare + 366 + 365 * {solar years}[http://en.wikipedia.org/wiki/Tropical_year]
=> Fri, 04 May 1753 00:00:00 +0000 * since Shakespeare's birthday then the correct anniversary date
``` * would be the 4th May and not the 23rd April.
*
As you can see, if we're accurately tracking the number of * So when should you use DateTime in Ruby and when should
[solar years][9] since Shakespeare's birthday then the correct * you use Time? Almost certainly you'll want to use Time
anniversary date would be the 4th May and not the 23rd April. * since your app is probably dealing with current dates and
* times. However, if you need to deal with dates and times in a
So when should you use `DateTime` in Ruby and when should * historical context you'll want to use DateTime to avoid
you use `Time`? Almost certainly you'll want to use `Time` * making the same mistakes as UNESCO. If you also have to deal
since your app is probably dealing with current dates and * with timezones then best of luck - just bear in mind that
times. However, if you need to deal with dates and times in a * you'll probably be dealing with
historical context you'll want to use `DateTime` to avoid * {local solar times}[http://en.wikipedia.org/wiki/Solar_time],
making the same mistakes as UNESCO. If you also have to deal * since it wasn't until the 19th century that the introduction
with timezones then best of luck - just bear in mind that * of the railways necessitated the need for
you'll probably be dealing with [local solar times][7], since * {Standard Time}[http://en.wikipedia.org/wiki/Standard_time#Great_Britain]
it wasn't until the 19th century that the introduction of the * and eventually timezones.
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); cDateTime = rb_define_class("DateTime", cDate);