Project

General

Profile

Bug #12311 ยป doc-datetime-to-rdoc.patch

stomar (Marcus Stollsteimer), 04/22/2016 03:07 PM

View differences:

ext/date/date_core.c
9394 9394
    rb_define_singleton_method(cDate, "_load", date_s__load, 1);
9395 9395

  
9396 9396
    /*
9397
	:markup: Markdown
9398

  
9399
	## DateTime
9400

  
9401
	A subclass of Date that easily handles date, hour, minute, second and
9402
	offset.
9403

  
9404
	DateTime does not consider any leap seconds, does not track
9405
	any summer time rules.
9406

  
9407
	DateTime object is created with DateTime::new, DateTime::jd,
9408
	DateTime::ordinal, DateTime::commercial, DateTime::parse,
9409
	DateTime::strptime, DateTime::now, Time#to_datetime or etc.
9410

  
9411
	    require 'date'
9412

  
9413
	    DateTime.new(2001,2,3,4,5,6)
9414
				#=> #<DateTime: 2001-02-03T04:05:06+00:00 ...>
9415

  
9416
	The last element of day, hour, minute or second can be
9417
	fractional number. The fractional number's precision is assumed
9418
	at most nanosecond.
9419

  
9420
	    DateTime.new(2001,2,3.5)
9421
				#=> #<DateTime: 2001-02-03T12:00:00+00:00 ...>
9422

  
9423
	An optional argument the offset indicates the difference
9424
	between the local time and UTC. For example, `Rational(3,24)`
9425
	represents ahead of 3 hours of UTC, `Rational(-5,24)` represents
9426
	behind of 5 hours of UTC. The offset should be -1 to +1, and
9427
	its precision is assumed at most second. The default value is
9428
	zero(equals to UTC).
9429

  
9430
	    DateTime.new(2001,2,3,4,5,6,Rational(3,24))
9431
				#=> #<DateTime: 2001-02-03T04:05:06+03:00 ...>
9432

  
9433
	also accepts string form.
9434

  
9435
	    DateTime.new(2001,2,3,4,5,6,'+03:00')
9436
				#=> #<DateTime: 2001-02-03T04:05:06+03:00 ...>
9437

  
9438
	An optional argument the day of calendar reform (start) denotes
9439
	a Julian day number, which should be 2298874 to 2426355 or
9440
	-/+oo.  The default value is `Date::ITALY` (2299161=1582-10-15).
9441

  
9442
	DateTime object has various methods. See each reference.
9443

  
9444
	    d = DateTime.parse('3rd Feb 2001 04:05:06+03:30')
9445
				#=> #<DateTime: 2001-02-03T04:05:06+03:30 ...>
9446
	    d.hour		#=> 4
9447
	    d.min		#=> 5
9448
	    d.sec		#=> 6
9449
	    d.offset		#=> (7/48)
9450
	    d.zone		#=> "+03:30"
9451
	    d += Rational('1.5')
9452
				#=> #<DateTime: 2001-02-04%16:05:06+03:30 ...>
9453
	    d = d.new_offset('+09:00')
9454
				#=> #<DateTime: 2001-02-04%21:35:06+09:00 ...>
9455
	    d.strftime('%I:%M:%S %p')
9456
				#=> "09:35:06 PM"
9457
	    d > DateTime.new(1999)
9458
				#=> true
9459

  
9460
	### When should you use DateTime and when should you use Time?
9461

  
9462
	It's a common misconception that [William Shakespeare][1] and
9463
	[Miguel de Cervantes][2] died on the same day in history -
9464
	so much so that UNESCO named April 23 as [World Book Day
9465
	because of this fact][3].
9466
	However because England hadn't yet adopted [Gregorian Calendar
9467
	Reform][4] (and wouldn't until [1752][5]) their deaths are
9468
	actually 10 days apart. Since Ruby's `Time` class implements a
9469
	[proleptic Gregorian calendar][6] and has no concept of
9470
	calendar reform then there's no way to express this. This is
9471
	where `DateTime` steps in:
9472

  
9473
	``` irb
9474
	>> shakespeare = DateTime.iso8601('1616-04-23', Date::ENGLAND)
9475
	=> Tue, 23 Apr 1616 00:00:00 +0000
9476
	>> cervantes = DateTime.iso8601('1616-04-23', Date::ITALY)
9477
	=> Sat, 23 Apr 1616 00:00:00 +0000
9478
	```
9479

  
9480
	Already you can see something's weird - the days of the week
9481
	are different, taking this further:
9482

  
9483
	``` irb
9484
	>> cervantes == shakespeare
9485
	=> false
9486
	>> (shakespeare - cervantes).to_i
9487
	=> 10
9488
	```
9489

  
9490
	This shows that in fact they died 10 days apart (in reality 11
9491
	days since Cervantes died a day earlier but was buried on the
9492
	23rd). We can see the actual date of Shakespeare's death by
9493
	using the `gregorian` method to convert it:
9494

  
9495
	``` irb
9496
	>> shakespeare.gregorian
9497
	=> Tue, 03 May 1616 00:00:00 +0000
9498
	```
9499

  
9500
	So there's an argument that all the celebrations that take
9501
	place on the 23rd April in Stratford-upon-Avon are actually
9502
	the wrong date since England is now using the Gregorian
9503
	calendar. You can see why when we transition across the reform
9504
	date boundary:
9505

  
9506
	``` irb
9507
	# start off with the anniversary of Shakespeare's birth in 1751
9508
	>> shakespeare = DateTime.iso8601('1751-04-23', Date::ENGLAND)
9509
	=> Tue, 23 Apr 1751 00:00:00 +0000
9510

  
9511
	# add 366 days since 1752 is a leap year and April 23 is after February 29
9512
	>> shakespeare + 366
9513
	=> Thu, 23 Apr 1752 00:00:00 +0000
9514

  
9515
	# add another 365 days to take us to the anniversary in 1753
9516
	>> shakespeare + 366 + 365
9517
	=> Fri, 04 May 1753 00:00:00 +0000
9518
	```
9519

  
9520
	As you can see, if we're accurately tracking the number of
9521
	[solar years][9] since Shakespeare's birthday then the correct
9522
	anniversary date would be the 4th May and not the 23rd April.
9523

  
9524
	So when should you use `DateTime` in Ruby and when should
9525
	you use `Time`? Almost certainly you'll want to use `Time`
9526
	since your app is probably dealing with current dates and
9527
	times. However, if you need to deal with dates and times in a
9528
	historical context you'll want to use `DateTime` to avoid
9529
	making the same mistakes as UNESCO. If you also have to deal
9530
	with timezones then best of luck - just bear in mind that
9531
	you'll probably be dealing with [local solar times][7], since
9532
	it wasn't until the 19th century that the introduction of the
9533
	railways necessitated the need for [Standard Time][8] and
9534
	eventually timezones.
9535

  
9536
	[1]: http://en.wikipedia.org/wiki/William_Shakespeare
9537
	[2]: http://en.wikipedia.org/wiki/Miguel_de_Cervantes
9538
	[3]: http://en.wikipedia.org/wiki/World_Book_Day
9539
	[4]: http://en.wikipedia.org/wiki/Gregorian_calendar#Gregorian_reform
9540
	[5]: http://en.wikipedia.org/wiki/Calendar_(New_Style)_Act_1750
9541
	[6]: http://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar
9542
	[7]: http://en.wikipedia.org/wiki/Solar_time
9543
	[8]: http://en.wikipedia.org/wiki/Standard_time#Great_Britain
9544
	[9]: http://en.wikipedia.org/wiki/Tropical_year
9397
     * == DateTime
9398
     *
9399
     * A subclass of Date that easily handles date, hour, minute, second and
9400
     * offset.
9401
     *
9402
     * DateTime does not consider any leap seconds, does not track
9403
     * any summer time rules.
9404
     *
9405
     * DateTime object is created with DateTime::new, DateTime::jd,
9406
     * DateTime::ordinal, DateTime::commercial, DateTime::parse,
9407
     * DateTime::strptime, DateTime::now, Time#to_datetime or etc.
9408
     *
9409
     *     require 'date'
9410
     *
9411
     *     DateTime.new(2001,2,3,4,5,6)
9412
     *                         #=> #<DateTime: 2001-02-03T04:05:06+00:00 ...>
9413
     *
9414
     * The last element of day, hour, minute or second can be
9415
     * fractional number. The fractional number's precision is assumed
9416
     * at most nanosecond.
9417
     *
9418
     *     DateTime.new(2001,2,3.5)
9419
     *                         #=> #<DateTime: 2001-02-03T12:00:00+00:00 ...>
9420
     *
9421
     * An optional argument the offset indicates the difference
9422
     * between the local time and UTC. For example, <tt>Rational(3,24)</tt>
9423
     * represents ahead of 3 hours of UTC, <tt>Rational(-5,24)</tt> represents
9424
     * behind of 5 hours of UTC. The offset should be -1 to +1, and
9425
     * its precision is assumed at most second. The default value is
9426
     * zero(equals to UTC).
9427
     *
9428
     *     DateTime.new(2001,2,3,4,5,6,Rational(3,24))
9429
     *                         #=> #<DateTime: 2001-02-03T04:05:06+03:00 ...>
9430
     *
9431
     * also accepts string form.
9432
     *
9433
     *     DateTime.new(2001,2,3,4,5,6,'+03:00')
9434
     *                         #=> #<DateTime: 2001-02-03T04:05:06+03:00 ...>
9435
     *
9436
     * An optional argument the day of calendar reform (start) denotes
9437
     * a Julian day number, which should be 2298874 to 2426355 or
9438
     * -/+oo.  The default value is +Date::ITALY+ (2299161=1582-10-15).
9439
     *
9440
     * DateTime object has various methods. See each reference.
9441
     *
9442
     *     d = DateTime.parse('3rd Feb 2001 04:05:06+03:30')
9443
     *                         #=> #<DateTime: 2001-02-03T04:05:06+03:30 ...>
9444
     *     d.hour              #=> 4
9445
     *     d.min               #=> 5
9446
     *     d.sec               #=> 6
9447
     *     d.offset            #=> (7/48)
9448
     *     d.zone              #=> "+03:30"
9449
     *     d += Rational('1.5')
9450
     *                         #=> #<DateTime: 2001-02-04%16:05:06+03:30 ...>
9451
     *     d = d.new_offset('+09:00')
9452
     *                         #=> #<DateTime: 2001-02-04%21:35:06+09:00 ...>
9453
     *     d.strftime('%I:%M:%S %p')
9454
     *                         #=> "09:35:06 PM"
9455
     *     d > DateTime.new(1999)
9456
     *                         #=> true
9457
     *
9458
     * === When should you use DateTime and when should you use Time?
9459
     *
9460
     * It's a common misconception that
9461
     * {William Shakespeare}[http://en.wikipedia.org/wiki/William_Shakespeare]
9462
     * and
9463
     * {Miguel de Cervantes}[http://en.wikipedia.org/wiki/Miguel_de_Cervantes]
9464
     * died on the same day in history -
9465
     * so much so that UNESCO named April 23 as
9466
     * {World Book Day because of this fact}[http://en.wikipedia.org/wiki/World_Book_Day].
9467
     * However because England hadn't yet adopted
9468
     * {Gregorian Calendar Reform}[http://en.wikipedia.org/wiki/Gregorian_calendar#Gregorian_reform]
9469
     * (and wouldn't until {1752}[http://en.wikipedia.org/wiki/Calendar_(New_Style)_Act_1750])
9470
     * their deaths are actually 10 days apart.
9471
     * Since Ruby's Time class implements a
9472
     * {proleptic Gregorian calendar}[http://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar]
9473
     * and has no concept of calendar reform then there's no way
9474
     * to express this. This is where DateTime steps in:
9475
     *
9476
     *     shakespeare = DateTime.iso8601('1616-04-23', Date::ENGLAND)
9477
     *      #=> Tue, 23 Apr 1616 00:00:00 +0000
9478
     *     cervantes = DateTime.iso8601('1616-04-23', Date::ITALY)
9479
     *      #=> Sat, 23 Apr 1616 00:00:00 +0000
9480
     *
9481
     * Already you can see something's weird - the days of the week
9482
     * are different, taking this further:
9483
     *
9484
     *     cervantes == shakespeare
9485
     *      #=> false
9486
     *     (shakespeare - cervantes).to_i
9487
     *      #=> 10
9488
     *
9489
     * This shows that in fact they died 10 days apart (in reality
9490
     * 11 days since Cervantes died a day earlier but was buried on
9491
     * the 23rd). We can see the actual date of Shakespeare's death by
9492
     * using the #gregorian method to convert it:
9493
     *
9494
     *     shakespeare.gregorian
9495
     *      #=> Tue, 03 May 1616 00:00:00 +0000
9496
     *
9497
     * So there's an argument that all the celebrations that take
9498
     * place on the 23rd April in Stratford-upon-Avon are actually
9499
     * the wrong date since England is now using the Gregorian calendar.
9500
     * You can see why when we transition across the reform
9501
     * date boundary:
9502
     *
9503
     *     # start off with the anniversary of Shakespeare's birth in 1751
9504
     *     shakespeare = DateTime.iso8601('1751-04-23', Date::ENGLAND)
9505
     *      #=> Tue, 23 Apr 1751 00:00:00 +0000
9506
     *
9507
     *     # add 366 days since 1752 is a leap year and April 23 is after February 29
9508
     *     shakespeare + 366
9509
     *      #=> Thu, 23 Apr 1752 00:00:00 +0000
9510
     *
9511
     *     # add another 365 days to take us to the anniversary in 1753
9512
     *     shakespeare + 366 + 365
9513
     *      #=> Fri, 04 May 1753 00:00:00 +0000
9514
     *
9515
     * As you can see, if we're accurately tracking the number of
9516
     * {solar years}[http://en.wikipedia.org/wiki/Tropical_year]
9517
     * since Shakespeare's birthday then the correct anniversary date
9518
     * would be the 4th May and not the 23rd April.
9519
     *
9520
     * So when should you use DateTime in Ruby and when should
9521
     * you use Time? Almost certainly you'll want to use Time
9522
     * since your app is probably dealing with current dates and
9523
     * times. However, if you need to deal with dates and times in a
9524
     * historical context you'll want to use DateTime to avoid
9525
     * making the same mistakes as UNESCO. If you also have to deal
9526
     * with timezones then best of luck - just bear in mind that
9527
     * you'll probably be dealing with
9528
     * {local solar times}[http://en.wikipedia.org/wiki/Solar_time],
9529
     * since it wasn't until the 19th century that the introduction
9530
     * of the railways necessitated the need for
9531
     * {Standard Time}[http://en.wikipedia.org/wiki/Standard_time#Great_Britain]
9532
     * and eventually timezones.
9545 9533
     */
9546 9534

  
9547 9535
    cDateTime = rb_define_class("DateTime", cDate);