U:RDoc::NormalClass[iI" DateTime:ET@I" Date;To:RDoc::Markup::Document: @parts[o;;[-S:RDoc::Markup::Heading: leveli: textI" DateTime;To:RDoc::Markup::BlankLineo:RDoc::Markup::Paragraph;[I"HA subclass of Date that easily handles date, hour, minute, second, ;TI"and offset.;T@o; ;[I"ADateTime does not consider any leap seconds, does not track ;TI"any summer time rules.;T@o; ;[I"DA DateTime object is created with DateTime::new, DateTime::jd, ;TI"?DateTime::ordinal, DateTime::commercial, DateTime::parse, ;TI">DateTime::strptime, DateTime::now, Time#to_datetime, etc.;T@o:RDoc::Markup::Verbatim;[ I"require 'date' ;TI" ;TI""DateTime.new(2001,2,3,4,5,6) ;TI"H #=> # ;T: @format0o; ;[I"?The last element of day, hour, minute, or second can be a ;TI"Efractional number. The fractional number's precision is assumed ;TI"at most nanosecond.;T@o;;[I"DateTime.new(2001,2,3.5) ;TI"H #=> # ;T;0o; ;[ I"@An optional argument, the offset, indicates the difference ;TI"Jbetween the local time and UTC. For example, Rational(3,24) ;TI"Mrepresents ahead of 3 hours of UTC, Rational(-5,24) represents ;TI"Bbehind of 5 hours of UTC. The offset should be -1 to +1, and ;TI"Cits precision is assumed at most second. The default value is ;TI"zero (equals to UTC).;T@o;;[I"1DateTime.new(2001,2,3,4,5,6,Rational(3,24)) ;TI"H #=> # ;T;0o; ;[I")The offset also accepts string form:;T@o;;[I"+DateTime.new(2001,2,3,4,5,6,'+03:00') ;TI"H #=> # ;T;0o; ;[ I"IAn optional argument, the day of calendar reform (+start+), denotes ;TI"@a Julian day number, which should be 2298874 to 2426355 or ;TI"!negative/positive infinity. ;TI"=The default value is +Date::ITALY+ (2299161=1582-10-15).;T@o; ;[I"?A DateTime object has various methods. See each reference.;T@o;;[I"7d = DateTime.parse('3rd Feb 2001 04:05:06+03:30') ;TI"H #=> # ;TI"d.hour #=> 4 ;TI"d.min #=> 5 ;TI"d.sec #=> 6 ;TI"$d.offset #=> (7/48) ;TI"&d.zone #=> "+03:30" ;TI"d += Rational('1.5') ;TI"H #=> # ;TI" d = d.new_offset('+09:00') ;TI"H #=> # ;TI"d.strftime('%I:%M:%S %p') ;TI"+ #=> "09:35:06 PM" ;TI"d > DateTime.new(1999) ;TI"" #=> true ;T;0S; ; i; I"?When should you use DateTime and when should you use Time?;T@o; ;[I"&It's a common misconception that ;TI"M{William Shakespeare}[http://en.wikipedia.org/wiki/William_Shakespeare] ;TI" and ;TI"M{Miguel de Cervantes}[http://en.wikipedia.org/wiki/Miguel_de_Cervantes] ;TI"'died on the same day in history - ;TI".so much so that UNESCO named April 23 as ;TI"Y{World Book Day because of this fact}[http://en.wikipedia.org/wiki/World_Book_Day]. ;TI"5However, because England hadn't yet adopted the ;TI"c{Gregorian Calendar Reform}[http://en.wikipedia.org/wiki/Gregorian_calendar#Gregorian_reform] ;TI"](and wouldn't until {1752}[http://en.wikipedia.org/wiki/Calendar_(New_Style)_Act_1750]) ;TI".their deaths are actually 10 days apart. ;TI"*Since Ruby's Time class implements a ;TI"_{proleptic Gregorian calendar}[http://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar] ;TI":and has no concept of calendar reform there's no way ;TI"Hto express this with Time objects. This is where DateTime steps in:;T@o;;[ I"Ashakespeare = DateTime.iso8601('1616-04-23', Date::ENGLAND) ;TI"* #=> Tue, 23 Apr 1616 00:00:00 +0000 ;TI"=cervantes = DateTime.iso8601('1616-04-23', Date::ITALY) ;TI"* #=> Sat, 23 Apr 1616 00:00:00 +0000 ;T;0o; ;[I"CAlready you can see something is weird - the days of the week ;TI"(are different. Taking this further:;T@o;;[ I"cervantes == shakespeare ;TI" #=> false ;TI"$(shakespeare - cervantes).to_i ;TI" #=> 10 ;T;0o; ;[ I"AThis shows that in fact they died 10 days apart (in reality ;TI"B11 days since Cervantes died a day earlier but was buried on ;TI"Ethe 23rd). We can see the actual date of Shakespeare's death by ;TI"/using the #gregorian method to convert it:;T@o;;[I"shakespeare.gregorian ;TI"* #=> Tue, 03 May 1616 00:00:00 +0000 ;T;0o; ;[ I"@So there's an argument that all the celebrations that take ;TI"Aplace on the 23rd April in Stratford-upon-Avon are actually ;TI"Gthe wrong date since England is now using the Gregorian calendar. ;TI":You can see why when we transition across the reform ;TI"date boundary:;T@o;;[I"E# start off with the anniversary of Shakespeare's birth in 1751 ;TI"Ashakespeare = DateTime.iso8601('1751-04-23', Date::ENGLAND) ;TI"* #=> Tue, 23 Apr 1751 00:00:00 +0000 ;TI" ;TI"P# add 366 days since 1752 is a leap year and April 23 is after February 29 ;TI"shakespeare + 366 ;TI"* #=> Thu, 23 Apr 1752 00:00:00 +0000 ;TI" ;TI"B# add another 365 days to take us to the anniversary in 1753 ;TI"shakespeare + 366 + 365 ;TI"* #=> Fri, 04 May 1753 00:00:00 +0000 ;T;0o; ;[ I"@As you can see, if we're accurately tracking the number of ;TI"?{solar years}[http://en.wikipedia.org/wiki/Tropical_year] ;TI"Dsince Shakespeare's birthday then the correct anniversary date ;TI"1would be the 4th May and not the 23rd April.;T@o; ;[I"=So when should you use DateTime in Ruby and when should ;TI"