Class: DateTime

Relationships & Source Files
Super Chains via Extension / Inclusion / Inheritance
Class Chain: self, `::Date`
Instance Chain: self, `::Date`, Comparable
Inherits:	Date `::Object` Date DateTime
Defined in:	ext/date/date_core.c

Overview

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.

A DateTime object is created with .new, .jd, .ordinal, .commercial, .parse, .strptime, .now, Time#to_datetime, 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 a 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 ...>

The offset 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 negative/positive infinity. The default value is Date::ITALY (2299161=1582-10-15).

A 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 and 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. However, because England hadn’t yet adopted the Gregorian Calendar Reform (and wouldn’t until 1752) their deaths are actually 10 days apart. Since Ruby’s ::Time class implements a proleptic Gregorian calendar and has no concept of calendar reform there’s no way to express this with ::Time objects. 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 is 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 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, since it wasn’t until the 19th century that the introduction of the railways necessitated the need for Standard Time and eventually timezones.

Constant Summary

`::Date` - Inherited

ABBR_DAYNAMES, ABBR_MONTHNAMES, DAYNAMES, ENGLAND, GREGORIAN, ITALY, JULIAN, MONTHNAMES, VERSION

Class Method Summary

._strptime(string[, format='%FT%T%z']) ⇒ Hash

Parses the given representation of date and time with the given template, and returns a hash of parsed elements.
.civil([year=-4712[, month=1[, mday=1[, hour=0[, minute=0[, second=0[, offset=0[, start=Date::ITALY]]]]]]]]) ⇒ DateTime

Alias for .new.
.commercial([cwyear=-4712[, cweek=1[, cwday=1[, hour=0[, minute=0[, second=0[, offset=0[, start=Date::ITALY]]]]]]]]) ⇒ DateTime

Creates a DateTime object denoting the given week date.
.httpdate(string='Mon, 01 Jan -4712 00:00:00 GMT'[, start=Date::ITALY]) ⇒ DateTime

Creates a new DateTime object by parsing from a string according to some RFC 2616 format.
.iso8601(string='-4712-01-01T00:00:00+00:00'[, start=Date::ITALY], limit: 128) ⇒ DateTime

Creates a new DateTime object by parsing from a string according to some typical ISO 8601 formats.
.jd([jd=0[, hour=0[, minute=0[, second=0[, offset=0[, start=Date::ITALY]]]]]]) ⇒ DateTime

Creates a DateTime object denoting the given chronological Julian day number.
.jisx0301(string='-4712-01-01T00:00:00+00:00'[, start=Date::ITALY], limit: 128) ⇒ DateTime

Creates a new DateTime object by parsing from a string according to some typical JIS X 0301 formats.
.new([year=-4712[, month=1[, mday=1[, hour=0[, minute=0[, second=0[, offset=0[, start=Date::ITALY]]]]]]]]) ⇒ DateTime (also: .civil) constructor

Creates a DateTime object denoting the given calendar date.
.now([start = Date::ITALY]) ⇒ DateTime

Creates a DateTime object denoting the present time.
.nth_kday(*args)
.ordinal([year=-4712[, yday=1[, hour=0[, minute=0[, second=0[, offset=0[, start=Date::ITALY]]]]]]]) ⇒ DateTime

Creates a DateTime object denoting the given ordinal date.
.parse(string='-4712-01-01T00:00:00+00:00'[, comp=true[, start=Date::ITALY]], limit: 128) ⇒ DateTime

Parses the given representation of date and time, and creates a DateTime object.
.rfc2822(string='Mon, 1 Jan -4712 00:00:00 +0000'[, start=Date::ITALY], limit: 128) ⇒ DateTime

Alias for .rfc822.
.rfc3339(string='-4712-01-01T00:00:00+00:00'[, start=Date::ITALY], limit: 128) ⇒ DateTime

Creates a new DateTime object by parsing from a string according to some typical RFC 3339 formats.
.rfc822(string='Mon, 1 Jan -4712 00:00:00 +0000'[, start=Date::ITALY], limit: 128) ⇒ DateTime (also: .rfc2822)

Creates a new DateTime object by parsing from a string according to some typical RFC 2822 formats.
.strptime([string='-4712-01-01T00:00:00+00:00'[, format='%FT%T%z'[ ,start=Date::ITALY]]]) ⇒ DateTime

Parses the given representation of date and time with the given template, and creates a DateTime object.
.weeknum(*args)
.xmlschema(string='-4712-01-01T00:00:00+00:00'[, start=Date::ITALY], limit: 128) ⇒ DateTime

Creates a new DateTime object by parsing from a string according to some typical XML Schema formats.

`::Date` - Inherited

._httpdate	Returns a hash of parsed elements.
._iso8601	Returns a hash of parsed elements.
._jisx0301	Returns a hash of parsed elements.
._parse	Parses the given representation of date and time, and returns a hash of parsed elements.
._rfc2822	Alias for Date._rfc822.
._rfc3339	Returns a hash of parsed elements.
._rfc822	Returns a hash of parsed elements.
._strptime	Parses the given representation of date and time with the given template, and returns a hash of parsed elements.
._xmlschema	Returns a hash of parsed elements.
.civil	Creates a date object denoting the given calendar date.
.commercial	Creates a date object denoting the given week date.
.gregorian_leap?	Alias for Date.leap?.
.httpdate	Creates a new `::Date` object by parsing from a string according to some RFC 2616 format.
.iso8601	Creates a new `::Date` object by parsing from a string according to some typical ISO 8601 formats.
.jd	Creates a date object denoting the given chronological Julian day number.
.jisx0301	Creates a new `::Date` object by parsing from a string according to some typical JIS X 0301 formats.
.julian_leap?	Returns true if the given year is a leap year of the proleptic Julian calendar.
.leap?	Returns true if the given year is a leap year of the proleptic Gregorian calendar.
.new, .new!, .nth_kday,
.ordinal	Creates a date object denoting the given ordinal date.
.parse	Parses the given representation of date and time, and creates a date object.
.rfc2822	Alias for Date.rfc822.
.rfc3339	Creates a new `::Date` object by parsing from a string according to some typical RFC 3339 formats.
.rfc822	Creates a new `::Date` object by parsing from a string according to some typical RFC 2822 formats.
.strptime	Parses the given representation of date and time with the given template, and creates a date object.
.test_all,
.test_civil	tests.
.test_commercial, .test_nth_kday, .test_ordinal, .test_unit_conv, .test_weeknum,
.today	Creates a date object denoting the present day.
.valid_civil?	Alias for Date.valid_date?.
.valid_commercial?	Returns true if the given week date is valid, and false if not.
.valid_date?	Returns true if the given calendar date is valid, and false if not.
.valid_jd?	Just returns true.
.valid_ordinal?	Returns true if the given ordinal date is valid, and false if not.
.weeknum,
.xmlschema	Creates a new `::Date` object by parsing from a string according to some typical XML Schema formats.
._load

Instance Attribute Summary

`::Date` - Inherited

#friday?	Returns true if the date is Friday.
#gregorian	This method is equivalent to new_start(Date::GREGORIAN).
#gregorian?	Returns true if the date is on or after the day of calendar reform.
#julian	This method is equivalent to new_start(Date::JULIAN).
#julian?	Returns true if the date is before the day of calendar reform.
#leap?	Returns true if the year is a leap year.
#monday?	Returns true if the date is Monday.
#saturday?	Returns true if the date is Saturday.
#sunday?	Returns true if the date is Sunday.
#thursday?	Returns true if the date is Thursday.
#tuesday?	Returns true if the date is Tuesday.
#wednesday?	Returns true if the date is Wednesday.

Instance Method Summary

#hour ⇒ Fixnum

Returns the hour (0-23).
#iso8601([n = 0]) ⇒ String (also: #xmlschema)

This method is equivalent to strftime(‘%FT%T%:z’).
#jisx0301([n = 0]) ⇒ String

Returns a string in a JIS X 0301 format.
#min ⇒ Fixnum (also: #minute)

Returns the minute (0-59).
#minute ⇒ Fixnum

Alias for #min.
#new_offset([offset = 0]) ⇒ date

Duplicates self and resets its offset.
#offset ⇒ Rational

Returns the offset.
#rfc3339([n = 0]) ⇒ String

This method is equivalent to strftime(‘%FT%T%:z’).
#sec ⇒ Fixnum (also: #second)

Returns the second (0-59).
#sec_fraction ⇒ Rational (also: #second_fraction)

Returns the fractional part of the second.
#second ⇒ Fixnum

Alias for #sec.
#second_fraction ⇒ Rational

Alias for #sec_fraction.
#strftime([format = '%FT%T%:z']) ⇒ String

Formats date according to the directives in the given format string.
#to_date ⇒ date

Returns a ::Date object which denotes self.
#to_datetime ⇒ self

Returns self.
#to_s ⇒ String

Returns a string in an ISO 8601 format.
#to_time ⇒ Time

Returns a ::Time object which denotes self.
#xmlschema([n = 0]) ⇒ String

Alias for #iso8601.
#zone ⇒ String

Returns the timezone.

`::Date` - Inherited

#+	Returns a date object pointing `other` days after self.
#-	Returns the difference between the two dates if the other is a date object.
#<<	Returns a date object pointing `n` months before self.
#<=>	Compares the two dates and returns -1, zero, 1 or nil.
#===	Returns true if they are the same day.
#>>	Returns a date object pointing `n` months after self.
#ajd	Returns the astronomical Julian day number.
#amjd	Returns the astronomical modified Julian day number.
#asctime	Alias for Date#ctime.
#ctime	Returns a string in asctime(3) format (but without “n0” at the end).
#cwday	Returns the day of calendar week (1-7, Monday is 1).
#cweek	Returns the calendar week number (1-53).
#cwyear	Returns the calendar week based year.
#day	Returns the day of the month (1-31).
#day_fraction	Returns the fractional part of the day.
#downto	This method is equivalent to step(min, -1){\|date\| …}.
#england	This method is equivalent to new_start(Date::ENGLAND).
#fill,
#httpdate	This method is equivalent to strftime(‘%a, %d %b %Y %T GMT’).
#inspect	Returns the value as a string for inspection.
#inspect_raw,
#iso8601	This method is equivalent to strftime(‘%F’).
#italy	This method is equivalent to new_start(Date::ITALY).
#jd	Returns the Julian day number.
#jisx0301	Returns a string in a JIS X 0301 format.
#ld	Returns the Lilian day number.
#marshal_dump_old,
#mday	Alias for Date#day.
#mjd	Returns the modified Julian day number.
#mon	Returns the month (1-12).
#month	Alias for Date#mon.
#new_start	Duplicates self and resets its day of calendar reform.
#next	Returns a date object denoting the following day.
#next_day	This method is equivalent to d + n.
#next_month	This method is equivalent to d >> n.
#next_year	This method is equivalent to d >> (n * 12).
#nth_kday?,
#prev_day	This method is equivalent to d - n.
#prev_month	This method is equivalent to d << n.
#prev_year	This method is equivalent to d << (n * 12).
#rfc2822	Alias for Date#rfc822.
#rfc3339	This method is equivalent to strftime(‘%FT%T%:z’).
#rfc822	This method is equivalent to strftime(‘%a, %-d %b %Y %T %z’).
#start	Returns the Julian day number denoting the day of calendar reform.
#step	Iterates evaluation of the given block, which takes a date object.
#strftime	Formats date according to the directives in the given format string.
#succ	Alias for Date#next.
#to_date	Returns self.
#to_datetime	Returns a `DateTime` object which denotes self.
#to_s	Returns a string in an ISO 8601 format.
#to_time	Returns a `::Time` object which denotes self.
#upto	This method is equivalent to step(max, 1){\|date\| …}.
#wday	Returns the day of week (0-6, Sunday is zero).
#xmlschema	Alias for Date#iso8601.
#yday	Returns the day of the year (1-366).
#year	Returns the year.
#hour	Alias for Date#min.
#min,
#minute	Alias for Date#min.
#sec	Alias for Date#min.
#second	Alias for Date#min.
#wnum0, #wnum1, #eql?, #hash, #initialize_copy, #marshal_dump, #marshal_load

Constructor Details

.civil([year=-4712[, month=1[, mday=1[, hour=0[, minute=0[, second=0[, offset=0[, start=Date::ITALY]]]]]]]]) ⇒ `DateTime` .new([year=-4712[, month=1[, mday=1[, hour=0[, minute=0[, second=0[, offset=0[, start=Date::ITALY]]]]]]]]) ⇒ `DateTime`
Also known as: .civil

Creates a DateTime object denoting the given calendar date.

DateTime.new(2001,2,3)    #=> #<DateTime: 2001-02-03T00:00:00+00:00 ...>
DateTime.new(2001,2,3,4,5,6,'+7')
                          #=> #<DateTime: 2001-02-03T04:05:06+07:00 ...>
DateTime.new(2001,-11,-26,-20,-55,-54,'+7')
                          #=> #<DateTime: 2001-02-03T04:05:06+07:00 ...>

[ GitHub ]

# File 'ext/date/date_core.c', line 7521


static VALUE
datetime_s_civil(int argc, VALUE *argv, VALUE klass)
{
    return datetime_initialize(argc, argv, d_lite_s_alloc_complex(klass));
}

Class Method Details

._strptime(string[, format='%FT%T%z']) ⇒ `Hash`

Parses the given representation of date and time with the given template, and returns a hash of parsed elements. _strptime does not support specification of flags and width unlike strftime.

.civil([year=-4712[, month=1[, mday=1[, hour=0[, minute=0[, second=0[, offset=0[, start=Date::ITALY]]]]]]]]) ⇒ `DateTime` .new([year=-4712[, month=1[, mday=1[, hour=0[, minute=0[, second=0[, offset=0[, start=Date::ITALY]]]]]]]]) ⇒ `DateTime`

Alias for .new.

.commercial([cwyear=-4712[, cweek=1[, cwday=1[, hour=0[, minute=0[, second=0[, offset=0[, start=Date::ITALY]]]]]]]]) ⇒ `DateTime`

Creates a DateTime object denoting the given week date.

DateTime.commercial(2001) #=> #<DateTime: 2001-01-01T00:00:00+00:00 ...>
DateTime.commercial(2002) #=> #<DateTime: 2001-12-31T00:00:00+00:00 ...>
DateTime.commercial(2001,5,6,4,5,6,'+7')
                          #=> #<DateTime: 2001-02-03T04:05:06+07:00 ...>

[ GitHub ]

# File 'ext/date/date_core.c', line 7630


static VALUE
datetime_s_commercial(int argc, VALUE *argv, VALUE klass)
{
    VALUE vy, vw, vd, vh, vmin, vs, vof, vsg, y, fr, fr2, ret;
    int w, d, h, min, s, rof;
    double sg;

    rb_scan_args(argc, argv, "08", &vy, &vw, &vd, &vh, &vmin, &vs, &vof, &vsg);

    y = INT2FIX(-4712);
    w = 1;
    d = 1;

    h = min = s = 0;
    fr2 = INT2FIX(0);
    rof = 0;
    sg = DEFAULT_SG;

    switch (argc) {
      case 8:
	val2sg(vsg, sg);
      case 7:
	val2off(vof, rof);
      case 6:
	num2int_with_frac(s, positive_inf);
      case 5:
	num2int_with_frac(min, 5);
      case 4:
	num2int_with_frac(h, 4);
      case 3:
	num2int_with_frac(d, 3);
      case 2:
	w = NUM2INT(vw);
      case 1:
	y = vy;
    }

    {
	VALUE nth;
	int ry, rw, rd, rh, rmin, rs, rjd, rjd2, ns;

	if (!valid_commercial_p(y, w, d, sg,
				&nth, &ry,
				&rw, &rd, &rjd,
				&ns))
	    rb_raise(rb_eArgError, "invalid date");
	if (!c_valid_time_p(h, min, s, &rh, &rmin, &rs))
	    rb_raise(rb_eArgError, "invalid date");
	canon24oc();

	rjd2 = jd_local_to_utc(rjd,
			       time_to_df(rh, rmin, rs),
			       rof);

	ret = d_complex_new_internal(klass,
				     nth, rjd2,
				     0, INT2FIX(0),
				     rof, sg,
				     0, 0, 0,
				     rh, rmin, rs,
				     HAVE_JD | HAVE_TIME);
    }
    add_frac();
    return ret;
}

.httpdate(string='Mon, 01 Jan -4712 00:00:00 GMT'[, start=Date::ITALY]) ⇒ `DateTime`

Creates a new DateTime object by parsing from a string according to some RFC 2616 format.

DateTime.httpdate('Sat, 03 Feb 2001 04:05:06 GMT')
                          #=> #<DateTime: 2001-02-03T04:05:06+00:00 ...>

Raise an ArgumentError when the string length is longer than limit. You can stop this check by passing limit: nil, but note that it may take a long time to parse.

[ GitHub ]

# File 'ext/date/date_core.c', line 8333


static VALUE
datetime_s_httpdate(int argc, VALUE *argv, VALUE klass)
{
    VALUE str, sg, opt;

    rb_scan_args(argc, argv, "02:", &str, &sg, &opt);
    if (!NIL_P(opt)) argc--;

    switch (argc) {
      case 0:
	str = rb_str_new2("Mon, 01 Jan -4712 00:00:00 GMT");
      case 1:
	sg = INT2FIX(DEFAULT_SG);
    }

    {
        int argc2 = 1;
        VALUE argv2[2];
        argv2[0] = str;
        argv2[1] = opt;
        if (!NIL_P(opt)) argc2++;
	VALUE hash = date_s__httpdate(argc2, argv2, klass);
	return dt_new_by_frags(klass, hash, sg);
    }
}

.iso8601(string='-4712-01-01T00:00:00+00:00'[, start=Date::ITALY], limit: 128) ⇒ `DateTime`

Creates a new DateTime object by parsing from a string according to some typical ISO 8601 formats.

DateTime.iso8601('2001-02-03T04:05:06+07:00')
                          #=> #<DateTime: 2001-02-03T04:05:06+07:00 ...>
DateTime.iso8601('20010203T040506+0700')
                          #=> #<DateTime: 2001-02-03T04:05:06+07:00 ...>
DateTime.iso8601('2001-W05-6T04:05:06+07:00')
                          #=> #<DateTime: 2001-02-03T04:05:06+07:00 ...>

Raise an ArgumentError when the string length is longer than limit. You can stop this check by passing limit: nil, but note that it may take a long time to parse.

[ GitHub ]

# File 'ext/date/date_core.c', line 8172


static VALUE
datetime_s_iso8601(int argc, VALUE *argv, VALUE klass)
{
    VALUE str, sg, opt;

    rb_scan_args(argc, argv, "02:", &str, &sg, &opt);
    if (!NIL_P(opt)) argc--;

    switch (argc) {
      case 0:
	str = rb_str_new2("-4712-01-01T00:00:00+00:00");
      case 1:
	sg = INT2FIX(DEFAULT_SG);
    }

    {
        int argc2 = 1;
        VALUE argv2[2];
        argv2[0] = str;
        argv2[1] = opt;
        if (!NIL_P(opt)) argc2--;
	VALUE hash = date_s__iso8601(argc2, argv2, klass);
	return dt_new_by_frags(klass, hash, sg);
    }
}

.jd([jd=0[, hour=0[, minute=0[, second=0[, offset=0[, start=Date::ITALY]]]]]]) ⇒ `DateTime`

Creates a DateTime object denoting the given chronological Julian day number.

DateTime.jd(2451944)      #=> #<DateTime: 2001-02-03T00:00:00+00:00 ...>
DateTime.jd(2451945)      #=> #<DateTime: 2001-02-04T00:00:00+00:00 ...>
DateTime.jd(Rational('0.5'))
                          #=> #<DateTime: -4712-01-01T12:00:00+00:00 ...>

[ GitHub ]

# File 'ext/date/date_core.c', line 7377


static VALUE
datetime_s_jd(int argc, VALUE *argv, VALUE klass)
{
    VALUE vjd, vh, vmin, vs, vof, vsg, jd, fr, fr2, ret;
    int h, min, s, rof;
    double sg;

    rb_scan_args(argc, argv, "06", &vjd, &vh, &vmin, &vs, &vof, &vsg);

    jd = INT2FIX(0);

    h = min = s = 0;
    fr2 = INT2FIX(0);
    rof = 0;
    sg = DEFAULT_SG;

    switch (argc) {
      case 6:
	val2sg(vsg, sg);
      case 5:
	val2off(vof, rof);
      case 4:
	num2int_with_frac(s, positive_inf);
      case 3:
	num2int_with_frac(min, 3);
      case 2:
	num2int_with_frac(h, 2);
      case 1:
	num2num_with_frac(jd, 1);
    }

    {
	VALUE nth;
	int rh, rmin, rs, rjd, rjd2;

	if (!c_valid_time_p(h, min, s, &rh, &rmin, &rs))
	    rb_raise(rb_eArgError, "invalid date");
	canon24oc();

	decode_jd(jd, &nth, &rjd);
	rjd2 = jd_local_to_utc(rjd,
			       time_to_df(rh, rmin, rs),
			       rof);

	ret = d_complex_new_internal(klass,
				     nth, rjd2,
				     0, INT2FIX(0),
				     rof, sg,
				     0, 0, 0,
				     rh, rmin, rs,
				     HAVE_JD | HAVE_TIME);
    }
    add_frac();
    return ret;
}

.jisx0301(string='-4712-01-01T00:00:00+00:00'[, start=Date::ITALY], limit: 128) ⇒ `DateTime`

Creates a new DateTime object by parsing from a string according to some typical JIS X 0301 formats.

DateTime.jisx0301('H13.02.03T04:05:06+07:00')
                          #=> #<DateTime: 2001-02-03T04:05:06+07:00 ...>

For no-era year, legacy format, Heisei is assumed.

DateTime.jisx0301('13.02.03T04:05:06+07:00')
                          #=> #<DateTime: 2001-02-03T04:05:06+07:00 ...>

Raise an ArgumentError when the string length is longer than limit. You can stop this check by passing limit: nil, but note that it may take a long time to parse.

[ GitHub ]

# File 'ext/date/date_core.c', line 8378


static VALUE
datetime_s_jisx0301(int argc, VALUE *argv, VALUE klass)
{
    VALUE str, sg, opt;

    rb_scan_args(argc, argv, "02:", &str, &sg, &opt);
    if (!NIL_P(opt)) argc--;

    switch (argc) {
      case 0:
	str = rb_str_new2("-4712-01-01T00:00:00+00:00");
      case 1:
	sg = INT2FIX(DEFAULT_SG);
    }

    {
        int argc2 = 1;
        VALUE argv2[2];
        argv2[0] = str;
        argv2[1] = opt;
        if (!NIL_P(opt)) argc2++;
	VALUE hash = date_s__jisx0301(argc2, argv2, klass);
	return dt_new_by_frags(klass, hash, sg);
    }
}

.now([start = Date::ITALY]) ⇒ `DateTime`

Creates a DateTime object denoting the present time.

DateTime.now              #=> #<DateTime: 2011-06-11T21:20:44+09:00 ...>

[ GitHub ]

# File 'ext/date/date_core.c', line 7844


static VALUE
datetime_s_now(int argc, VALUE *argv, VALUE klass)
{
    VALUE vsg, nth, ret;
    double sg;
#ifdef HAVE_CLOCK_GETTIME
    struct timespec ts;
#else
    struct timeval tv;
#endif
    time_t sec;
    struct tm tm;
    long sf, of;
    int y, ry, m, d, h, min, s;

    rb_scan_args(argc, argv, "01", &vsg);

    if (argc < 1)
	sg = DEFAULT_SG;
    else
	sg = NUM2DBL(vsg);

#ifdef HAVE_CLOCK_GETTIME
    if (clock_gettime(CLOCK_REALTIME, &ts) == -1)
	rb_sys_fail("clock_gettime");
    sec = ts.tv_sec;
#else
    if (gettimeofday(&tv, NULL) == -1)
	rb_sys_fail("gettimeofday");
    sec = tv.tv_sec;
#endif
    tzset();
    if (!localtime_r(&sec, &tm))
	rb_sys_fail("localtime");

    y = tm.tm_year + 1900;
    m = tm.tm_mon + 1;
    d = tm.tm_mday;
    h = tm.tm_hour;
    min = tm.tm_min;
    s = tm.tm_sec;
    if (s == 60)
	s = 59;
#ifdef HAVE_STRUCT_TM_TM_GMTOFF
    of = tm.tm_gmtoff;
#elif defined(HAVE_TIMEZONE)
#ifdef HAVE_ALTZONE
    of = (long)-((tm.tm_isdst > 0) ? altzone : timezone);
#else
    of = (long)-timezone;
    if (tm.tm_isdst) {
	time_t sec2;

	tm.tm_isdst = 0;
	sec2 = mktime(&tm);
	of += (long)difftime(sec2, sec);
    }
#endif
#elif defined(HAVE_TIMEGM)
    {
	time_t sec2;

	sec2 = timegm(&tm);
	of = (long)difftime(sec2, sec);
    }
#else
    {
	struct tm tm2;
	time_t sec2;

	if (!gmtime_r(&sec, &tm2))
	    rb_sys_fail("gmtime");
	tm2.tm_isdst = tm.tm_isdst;
	sec2 = mktime(&tm2);
	of = (long)difftime(sec, sec2);
    }
#endif
#ifdef HAVE_CLOCK_GETTIME
    sf = ts.tv_nsec;
#else
    sf = tv.tv_usec * 1000;
#endif

    if (of < -DAY_IN_SECONDS || of > DAY_IN_SECONDS) {
	of = 0;
	rb_warning("invalid offset is ignored");
    }

    decode_year(INT2FIX(y), -1, &nth, &ry);

    ret = d_complex_new_internal(klass,
				 nth, 0,
				 0, LONG2NUM(sf),
				 (int)of, GREGORIAN,
				 ry, m, d,
				 h, min, s,
				 HAVE_CIVIL | HAVE_TIME);
    {
	get_d1(ret);
	set_sg(dat, sg);
    }
    return ret;
}

.nth_kday(*args)

[ GitHub ]

# File 'ext/date/date_core.c', line 7766


static VALUE
datetime_s_nth_kday(int argc, VALUE *argv, VALUE klass)
{
    VALUE vy, vm, vn, vk, vh, vmin, vs, vof, vsg, y, fr, fr2, ret;
    int m, n, k, h, min, s, rof;
    double sg;

    rb_scan_args(argc, argv, "09", &vy, &vm, &vn, &vk,
		 &vh, &vmin, &vs, &vof, &vsg);

    y = INT2FIX(-4712);
    m = 1;
    n = 1;
    k = 1;

    h = min = s = 0;
    fr2 = INT2FIX(0);
    rof = 0;
    sg = DEFAULT_SG;

    switch (argc) {
      case 9:
	val2sg(vsg, sg);
      case 8:
	val2off(vof, rof);
      case 7:
	num2int_with_frac(s, positive_inf);
      case 6:
	num2int_with_frac(min, 6);
      case 5:
	num2int_with_frac(h, 5);
      case 4:
	num2int_with_frac(k, 4);
      case 3:
	n = NUM2INT(vn);
      case 2:
	m = NUM2INT(vm);
      case 1:
	y = vy;
    }

    {
	VALUE nth;
	int ry, rm, rn, rk, rh, rmin, rs, rjd, rjd2, ns;

	if (!valid_nth_kday_p(y, m, n, k, sg,
			      &nth, &ry,
			      &rm, &rn, &rk, &rjd,
			      &ns))
	    rb_raise(rb_eArgError, "invalid date");
	if (!c_valid_time_p(h, min, s, &rh, &rmin, &rs))
	    rb_raise(rb_eArgError, "invalid date");
	canon24oc();

	rjd2 = jd_local_to_utc(rjd,
			       time_to_df(rh, rmin, rs),
			       rof);
	ret = d_complex_new_internal(klass,
				     nth, rjd2,
				     0, INT2FIX(0),
				     rof, sg,
				     0, 0, 0,
				     rh, rmin, rs,
				     HAVE_JD | HAVE_TIME);
    }
    add_frac();
    return ret;
}

.ordinal([year=-4712[, yday=1[, hour=0[, minute=0[, second=0[, offset=0[, start=Date::ITALY]]]]]]]) ⇒ `DateTime`

Creates a DateTime object denoting the given ordinal date.

DateTime.ordinal(2001,34) #=> #<DateTime: 2001-02-03T00:00:00+00:00 ...>
DateTime.ordinal(2001,34,4,5,6,'+7')
                          #=> #<DateTime: 2001-02-03T04:05:06+07:00 ...>
DateTime.ordinal(2001,-332,-20,-55,-54,'+7')
                          #=> #<DateTime: 2001-02-03T04:05:06+07:00 ...>

[ GitHub ]

# File 'ext/date/date_core.c', line 7445


static VALUE
datetime_s_ordinal(int argc, VALUE *argv, VALUE klass)
{
    VALUE vy, vd, vh, vmin, vs, vof, vsg, y, fr, fr2, ret;
    int d, h, min, s, rof;
    double sg;

    rb_scan_args(argc, argv, "07", &vy, &vd, &vh, &vmin, &vs, &vof, &vsg);

    y = INT2FIX(-4712);
    d = 1;

    h = min = s = 0;
    fr2 = INT2FIX(0);
    rof = 0;
    sg = DEFAULT_SG;

    switch (argc) {
      case 7:
	val2sg(vsg, sg);
      case 6:
	val2off(vof, rof);
      case 5:
	num2int_with_frac(s, positive_inf);
      case 4:
	num2int_with_frac(min, 4);
      case 3:
	num2int_with_frac(h, 3);
      case 2:
	num2int_with_frac(d, 2);
      case 1:
	y = vy;
    }

    {
	VALUE nth;
	int ry, rd, rh, rmin, rs, rjd, rjd2, ns;

	if (!valid_ordinal_p(y, d, sg,
			     &nth, &ry,
			     &rd, &rjd,
			     &ns))
	    rb_raise(rb_eArgError, "invalid date");
	if (!c_valid_time_p(h, min, s, &rh, &rmin, &rs))
	    rb_raise(rb_eArgError, "invalid date");
	canon24oc();

	rjd2 = jd_local_to_utc(rjd,
			       time_to_df(rh, rmin, rs),
			       rof);

	ret = d_complex_new_internal(klass,
				     nth, rjd2,
				     0, INT2FIX(0),
				     rof, sg,
				     0, 0, 0,
				     rh, rmin, rs,
				     HAVE_JD | HAVE_TIME);
    }
    add_frac();
    return ret;
}

.parse(string='-4712-01-01T00:00:00+00:00'[, comp=true[, start=Date::ITALY]], limit: 128) ⇒ `DateTime`

Parses the given representation of date and time, and creates a DateTime object. This method does not function as a validator.

If the optional second argument is true and the detected year is in the range “00” to “99”, makes it full.

DateTime.parse('2001-02-03T04:05:06+07:00')
                          #=> #<DateTime: 2001-02-03T04:05:06+07:00 ...>
DateTime.parse('20010203T040506+0700')
                          #=> #<DateTime: 2001-02-03T04:05:06+07:00 ...>
DateTime.parse('3rd Feb 2001 04:05:06 PM')
                          #=> #<DateTime: 2001-02-03T16:05:06+00:00 ...>

Raise an ArgumentError when the string length is longer than limit. You can stop this check by passing limit: nil, but note that it may take a long time to parse.

[ GitHub ]

# File 'ext/date/date_core.c', line 8125


static VALUE
datetime_s_parse(int argc, VALUE *argv, VALUE klass)
{
    VALUE str, comp, sg, opt;

    rb_scan_args(argc, argv, "03:", &str, &comp, &sg, &opt);
    if (!NIL_P(opt)) argc--;

    switch (argc) {
      case 0:
	str = rb_str_new2("-4712-01-01T00:00:00+00:00");
      case 1:
	comp = Qtrue;
      case 2:
	sg = INT2FIX(DEFAULT_SG);
    }

    {
        int argc2 = 2;
        VALUE argv2[3];
        argv2[0] = str;
        argv2[1] = comp;
        argv2[2] = opt;
        if (!NIL_P(opt)) argc2++;
	VALUE hash = date_s__parse(argc2, argv2, klass);
	return dt_new_by_frags(klass, hash, sg);
    }
}

.rfc2822(string='Mon, 1 Jan -4712 00:00:00 +0000'[, start=Date::ITALY], limit: 128) ⇒ `DateTime` .rfc822(string='Mon, 1 Jan -4712 00:00:00 +0000'[, start=Date::ITALY], limit: 128) ⇒ `DateTime`

Alias for .rfc822.

.rfc3339(string='-4712-01-01T00:00:00+00:00'[, start=Date::ITALY], limit: 128) ⇒ `DateTime`

Creates a new DateTime object by parsing from a string according to some typical RFC 3339 formats.

DateTime.rfc3339('2001-02-03T04:05:06+07:00')
                          #=> #<DateTime: 2001-02-03T04:05:06+07:00 ...>

Raise an ArgumentError when the string length is longer than limit. You can stop this check by passing limit: nil, but note that it may take a long time to parse.

[ GitHub ]

# File 'ext/date/date_core.c', line 8212


static VALUE
datetime_s_rfc3339(int argc, VALUE *argv, VALUE klass)
{
    VALUE str, sg, opt;

    rb_scan_args(argc, argv, "02:", &str, &sg, &opt);
    if (!NIL_P(opt)) argc--;

    switch (argc) {
      case 0:
	str = rb_str_new2("-4712-01-01T00:00:00+00:00");
      case 1:
	sg = INT2FIX(DEFAULT_SG);
    }

    {
        int argc2 = 1;
        VALUE argv2[2];
        argv2[0] = str;
        argv2[1] = opt;
        if (!NIL_P(opt)) argc2++;
	VALUE hash = date_s__rfc3339(argc2, argv2, klass);
	return dt_new_by_frags(klass, hash, sg);
    }
}

.rfc2822(string='Mon, 1 Jan -4712 00:00:00 +0000'[, start=Date::ITALY], limit: 128) ⇒ `DateTime` .rfc822(string='Mon, 1 Jan -4712 00:00:00 +0000'[, start=Date::ITALY], limit: 128) ⇒ `DateTime`
Also known as: .rfc2822

Creates a new DateTime object by parsing from a string according to some typical RFC 2822 formats.

DateTime.rfc2822('Sat, 3 Feb 2001 04:05:06 +0700')
                         #=> #<DateTime: 2001-02-03T04:05:06+07:00 ...>

Raise an ArgumentError when the string length is longer than limit. You can stop this check by passing limit: nil, but note that it may take a long time to parse.

[ GitHub ]

# File 'ext/date/date_core.c', line 8293


static VALUE
datetime_s_rfc2822(int argc, VALUE *argv, VALUE klass)
{
    VALUE str, sg, opt;

    rb_scan_args(argc, argv, "02:", &str, &sg, &opt);
    if (!NIL_P(opt)) argc--;

    switch (argc) {
      case 0:
	str = rb_str_new2("Mon, 1 Jan -4712 00:00:00 +0000");
      case 1:
	sg = INT2FIX(DEFAULT_SG);
    }

    {
        int argc2 = 1;
        VALUE argv2[2];
        argv2[0] = str;
        argv2[1] = opt;
        if (!NIL_P(opt)) argc2++;
	VALUE hash = date_s__rfc2822(argc2, argv2, klass);
	return dt_new_by_frags(klass, hash, sg);
    }
}

.strptime([string='-4712-01-01T00:00:00+00:00'[, format='%FT%T%z'[ ,start=Date::ITALY]]]) ⇒ `DateTime`

Parses the given representation of date and time with the given template, and creates a DateTime object. strptime does not support specification of flags and width unlike strftime.

DateTime.strptime('2001-02-03T04:05:06+07:00', '%Y-%m-%dT%H:%M:%S%z')
                          #=> #<DateTime: 2001-02-03T04:05:06+07:00 ...>
DateTime.strptime('03-02-2001 04:05:06 PM', '%d-%m-%Y %I:%M:%S %p')
                          #=> #<DateTime: 2001-02-03T16:05:06+00:00 ...>
DateTime.strptime('2001-W05-6T04:05:06+07:00', '%G-W%V-%uT%H:%M:%S%z')
                          #=> #<DateTime: 2001-02-03T04:05:06+07:00 ...>
DateTime.strptime('2001 04 6 04 05 06 +7', '%Y %U %w %H %M %S %z')
                          #=> #<DateTime: 2001-02-03T04:05:06+07:00 ...>
DateTime.strptime('2001 05 6 04 05 06 +7', '%Y %W %u %H %M %S %z')
                          #=> #<DateTime: 2001-02-03T04:05:06+07:00 ...>
DateTime.strptime('-1', '%s')
                          #=> #<DateTime: 1969-12-31T23:59:59+00:00 ...>
DateTime.strptime('-1000', '%Q')
                          #=> #<DateTime: 1969-12-31T23:59:59+00:00 ...>
DateTime.strptime('sat3feb014pm+7', '%a%d%b%y%H%p%z')
                          #=> #<DateTime: 2001-02-03T16:00:00+07:00 ...>

.weeknum(*args)

[ GitHub ]

# File 'ext/date/date_core.c', line 7697


static VALUE
datetime_s_weeknum(int argc, VALUE *argv, VALUE klass)
{
    VALUE vy, vw, vd, vf, vh, vmin, vs, vof, vsg, y, fr, fr2, ret;
    int w, d, f, h, min, s, rof;
    double sg;

    rb_scan_args(argc, argv, "09", &vy, &vw, &vd, &vf,
		 &vh, &vmin, &vs, &vof, &vsg);

    y = INT2FIX(-4712);
    w = 0;
    d = 1;
    f = 0;

    h = min = s = 0;
    fr2 = INT2FIX(0);
    rof = 0;
    sg = DEFAULT_SG;

    switch (argc) {
      case 9:
	val2sg(vsg, sg);
      case 8:
	val2off(vof, rof);
      case 7:
	num2int_with_frac(s, positive_inf);
      case 6:
	num2int_with_frac(min, 6);
      case 5:
	num2int_with_frac(h, 5);
      case 4:
	f = NUM2INT(vf);
      case 3:
	num2int_with_frac(d, 4);
      case 2:
	w = NUM2INT(vw);
      case 1:
	y = vy;
    }

    {
	VALUE nth;
	int ry, rw, rd, rh, rmin, rs, rjd, rjd2, ns;

	if (!valid_weeknum_p(y, w, d, f, sg,
			     &nth, &ry,
			     &rw, &rd, &rjd,
			     &ns))
	    rb_raise(rb_eArgError, "invalid date");
	if (!c_valid_time_p(h, min, s, &rh, &rmin, &rs))
	    rb_raise(rb_eArgError, "invalid date");
	canon24oc();

	rjd2 = jd_local_to_utc(rjd,
			       time_to_df(rh, rmin, rs),
			       rof);
	ret = d_complex_new_internal(klass,
				     nth, rjd2,
				     0, INT2FIX(0),
				     rof, sg,
				     0, 0, 0,
				     rh, rmin, rs,
				     HAVE_JD | HAVE_TIME);
    }
    add_frac();
    return ret;
}

.xmlschema(string='-4712-01-01T00:00:00+00:00'[, start=Date::ITALY], limit: 128) ⇒ `DateTime`

Creates a new DateTime object by parsing from a string according to some typical XML Schema formats.

DateTime.xmlschema('2001-02-03T04:05:06+07:00')
                          #=> #<DateTime: 2001-02-03T04:05:06+07:00 ...>

Raise an ArgumentError when the string length is longer than limit. You can stop this check by passing limit: nil, but note that it may take a long time to parse.

[ GitHub ]

# File 'ext/date/date_core.c', line 8252


static VALUE
datetime_s_xmlschema(int argc, VALUE *argv, VALUE klass)
{
    VALUE str, sg, opt;

    rb_scan_args(argc, argv, "02:", &str, &sg, &opt);
    if (!NIL_P(opt)) argc--;

    switch (argc) {
      case 0:
	str = rb_str_new2("-4712-01-01T00:00:00+00:00");
      case 1:
	sg = INT2FIX(DEFAULT_SG);
    }

    {
        int argc2 = 1;
        VALUE argv2[2];
        argv2[0] = str;
        argv2[1] = opt;
        if (!NIL_P(opt)) argc2++;
	VALUE hash = date_s__xmlschema(argc2, argv2, klass);
	return dt_new_by_frags(klass, hash, sg);
    }
}

Instance Method Details

#hour ⇒ `Fixnum`

Returns the hour (0-23).

DateTime.new(2001,2,3,4,5,6).hour         #=> 4

[ GitHub ]

# File 'ext/date/date_core.c', line 5337


static VALUE
d_lite_hour(VALUE self)
{
    get_d1(self);
    return INT2FIX(m_hour(dat));
}

#iso8601([n = 0]) ⇒ `String` #xmlschema([n = 0]) ⇒ `String`
Also known as: #xmlschema

This method is equivalent to strftime(‘%FT%T%:z’). The optional argument n is the number of digits for fractional seconds.

DateTime.parse('2001-02-03T04:05:06.123456789+07:00').iso8601(9)
                          #=> "2001-02-03T04:05:06.123456789+07:00"

[ GitHub ]

# File 'ext/date/date_core.c', line 8632


static VALUE
dt_lite_iso8601(int argc, VALUE *argv, VALUE self)
{
    long n = 0;

    rb_check_arity(argc, 0, 1);
    if (argc >= 1)
	n = NUM2LONG(argv[0]);

    return rb_str_append(strftimev("%Y-%m-%d", self, set_tmx),
			 iso8601_timediv(self, n));
}

#jisx0301([n = 0]) ⇒ `String`

Returns a string in a JIS X 0301 format. The optional argument n is the number of digits for fractional seconds.

DateTime.parse('2001-02-03T04:05:06.123456789+07:00').jisx0301(9)
                          #=> "H13.02.03T04:05:06.123456789+07:00"

[ GitHub ]

# File 'ext/date/date_core.c', line 8671


static VALUE
dt_lite_jisx0301(int argc, VALUE *argv, VALUE self)
{
    long n = 0;

    rb_check_arity(argc, 0, 1);
    if (argc >= 1)
	n = NUM2LONG(argv[0]);

    return rb_str_append(d_lite_jisx0301(self),
			 iso8601_timediv(self, n));
}

#min ⇒ `Fixnum` #minute ⇒ `Fixnum`
Also known as: #minute

Returns the minute (0-59).

DateTime.new(2001,2,3,4,5,6).min          #=> 5

[ GitHub ]

# File 'ext/date/date_core.c', line 5353


static VALUE
d_lite_min(VALUE self)
{
    get_d1(self);
    return INT2FIX(m_min(dat));
}

#min ⇒ `Fixnum` #minute ⇒ `Fixnum`

Alias for #min.

#new_offset([offset = 0]) ⇒ `date`

Duplicates self and resets its offset.

d = DateTime.new(2001,2,3,4,5,6,'-02:00')
                          #=> #<DateTime: 2001-02-03T04:05:06-02:00 ...>
d.new_offset('+09:00')    #=> #<DateTime: 2001-02-03T15:05:06+09:00 ...>

[ GitHub ]

# File 'ext/date/date_core.c', line 5651


static VALUE
d_lite_new_offset(int argc, VALUE *argv, VALUE self)
{
    VALUE vof;
    int rof;

    rb_scan_args(argc, argv, "01", &vof);

    rof = 0;
    if (argc >= 1)
	val2off(vof, rof);

    return dup_obj_with_new_offset(self, rof);
}

#offset ⇒ `Rational`

Returns the offset.

DateTime.parse('04pm+0730').offset        #=> (5/16)

[ GitHub ]

# File 'ext/date/date_core.c', line 5400


static VALUE
d_lite_offset(VALUE self)
{
    get_d1(self);
    return m_of_in_day(dat);
}

#rfc3339([n = 0]) ⇒ `String`

This method is equivalent to strftime(‘%FT%T%:z’). The optional argument n is the number of digits for fractional seconds.

DateTime.parse('2001-02-03T04:05:06.123456789+07:00').rfc3339(9)
                          #=> "2001-02-03T04:05:06.123456789+07:00"

[ GitHub ]

# File 'ext/date/date_core.c', line 8655


static VALUE
dt_lite_rfc3339(int argc, VALUE *argv, VALUE self)
{
    return dt_lite_iso8601(argc, argv, self);
}

#sec ⇒ `Fixnum` #second ⇒ `Fixnum`
Also known as: #second

Returns the second (0-59).

DateTime.new(2001,2,3,4,5,6).sec          #=> 6

[ GitHub ]

# File 'ext/date/date_core.c', line 5369


static VALUE
d_lite_sec(VALUE self)
{
    get_d1(self);
    return INT2FIX(m_sec(dat));
}

#sec_fraction ⇒ `Rational` #second_fraction ⇒ `Rational`
Also known as: #second_fraction

Returns the fractional part of the second.

DateTime.new(2001,2,3,4,5,6.5).sec_fraction       #=> (1/2)

[ GitHub ]

# File 'ext/date/date_core.c', line 5385


static VALUE
d_lite_sec_fraction(VALUE self)
{
    get_d1(self);
    return m_sf_in_sec(dat);
}

#sec ⇒ `Fixnum` #second ⇒ `Fixnum`

Alias for #sec.

#sec_fraction ⇒ `Rational` #second_fraction ⇒ `Rational`

Alias for #sec_fraction.

#strftime([format = '%FT%T%:z']) ⇒ `String`

Formats date according to the directives in the given format string. The directives begin with a percent (%) character. Any text not listed as a directive will be passed through to the output string.

A directive consists of a percent (%) character, zero or more flags, an optional minimum field width, an optional modifier, and a conversion specifier as follows.

%<flags><width><modifier><conversion>

Flags:

-  don't pad a numerical output.
_  use spaces for padding.
0  use zeros for padding.
^  upcase the result string.
#  change case.
:  use colons for %z.

The minimum field width specifies the minimum width.

The modifiers are “E” and “O”. They are ignored.

Format directives:

Date (Year, Month, Day):
  %Y - Year with century (can be negative, 4 digits at least)
          -0001, 0000, 1995, 2009, 14292, etc.
  %C - year / 100 (round down.  20 in 2009)
  %y - year % 100 (00..99)

  %m - Month of the year, zero-padded (01..12)
          %_m  blank-padded ( 1..12)
          %-m  no-padded (1..12)
  %B - The full month name (``January'')
          %^B  uppercased (``JANUARY'')
  %b - The abbreviated month name (``Jan'')
          %^b  uppercased (``JAN'')
  %h - Equivalent to %b

  %d - Day of the month, zero-padded (01..31)
          %-d  no-padded (1..31)
  %e - Day of the month, blank-padded ( 1..31)

  %j - Day of the year (001..366)

Time (Hour, Minute, Second, Subsecond):
  %H - Hour of the day, 24-hour clock, zero-padded (00..23)
  %k - Hour of the day, 24-hour clock, blank-padded ( 0..23)
  %I - Hour of the day, 12-hour clock, zero-padded (01..12)
  %l - Hour of the day, 12-hour clock, blank-padded ( 1..12)
  %P - Meridian indicator, lowercase (``am'' or ``pm'')
  %p - Meridian indicator, uppercase (``AM'' or ``PM'')

  %M - Minute of the hour (00..59)

  %S - Second of the minute (00..60)

  %L - Millisecond of the second (000..999)
  %N - Fractional seconds digits, default is 9 digits (nanosecond)
          %3N  millisecond (3 digits)   %15N femtosecond (15 digits)
          %6N  microsecond (6 digits)   %18N attosecond  (18 digits)
          %9N  nanosecond  (9 digits)   %21N zeptosecond (21 digits)
          %12N picosecond (12 digits)   %24N yoctosecond (24 digits)

Time zone:
  %z - Time zone as hour and minute offset from UTC (e.g. +0900)
          %:z - hour and minute offset from UTC with a colon (e.g. +09:00)
          %::z - hour, minute and second offset from UTC (e.g. +09:00:00)
          %:::z - hour, minute and second offset from UTC
                                            (e.g. +09, +09:30, +09:30:30)
  %Z - Equivalent to %:z (e.g. +09:00)

Weekday:
  %A - The full weekday name (``Sunday'')
          %^A  uppercased (``SUNDAY'')
  %a - The abbreviated name (``Sun'')
          %^a  uppercased (``SUN'')
  %u - Day of the week (Monday is 1, 1..7)
  %w - Day of the week (Sunday is 0, 0..6)

ISO 8601 week-based year and week number:
The week 1 of YYYY starts with a Monday and includes YYYY-01-04.
The days in the year before the first week are in the last week of
the previous year.
  %G - The week-based year
  %g - The last 2 digits of the week-based year (00..99)
  %V - Week number of the week-based year (01..53)

Week number:
The week 1 of YYYY starts with a Sunday or Monday (according to %U
or %W).  The days in the year before the first week are in week 0.
  %U - Week number of the year.  The week starts with Sunday.  (00..53)
  %W - Week number of the year.  The week starts with Monday.  (00..53)

Seconds since the Unix Epoch:
  %s - Number of seconds since 1970-01-01 00:00:00 UTC.
  %Q - Number of milliseconds since 1970-01-01 00:00:00 UTC.

Literal string:
  %n - Newline character (\n)
  %t - Tab character (\t)
  %% - Literal ``%'' character

Combination:
  %c - date and time (%a %b %e %T %Y)
  %D - Date (%m/%d/%y)
  %F - The ISO 8601 date format (%Y-%m-%d)
  %v - VMS date (%e-%b-%Y)
  %x - Same as %D
  %X - Same as %T
  %r - 12-hour time (%I:%M:%S %p)
  %R - 24-hour time (%H:%M)
  %T - 24-hour time (%H:%M:%S)
  %+ - date(1) (%a %b %e %H:%M:%S %Z %Y)

This method is similar to the strftime() function defined in ISO C and POSIX. Several directives (%a, %A, %b, %B, %c, %p, %r, %x, %X, %E*, %O* and %Z) are locale dependent in the function. However, this method is locale independent. So, the result may differ even if the same format string is used in other systems such as C. It is good practice to avoid %x and %X because there are corresponding locale independent representations, %D and %T.

Examples:

d = DateTime.new(2007,11,19,8,37,48,"-06:00")
                          #=> #<DateTime: 2007-11-19T08:37:48-0600 ...>
d.strftime("Printed on %m/%d/%Y")   #=> "Printed on 11/19/2007"
d.strftime("at %I:%M%p")            #=> "at 08:37AM"

Various ISO 8601 formats:

%Y%m%d           => 20071119                  Calendar date (basic)
%F               => 2007-11-19                Calendar date (extended)
%Y-%m            => 2007-11                   Calendar date, reduced accuracy, specific month
%Y               => 2007                      Calendar date, reduced accuracy, specific year
%C               => 20                        Calendar date, reduced accuracy, specific century
%Y%j             => 2007323                   Ordinal date (basic)
%Y-%j            => 2007-323                  Ordinal date (extended)
%GW%V%u          => 2007W471                  Week date (basic)
%G-W%V-%u        => 2007-W47-1                Week date (extended)
%GW%V            => 2007W47                   Week date, reduced accuracy, specific week (basic)
%G-W%V           => 2007-W47                  Week date, reduced accuracy, specific week (extended)
%H%M%S           => 083748                    Local time (basic)
%T               => 08:37:48                  Local time (extended)
%H%M             => 0837                      Local time, reduced accuracy, specific minute (basic)
%H:%M            => 08:37                     Local time, reduced accuracy, specific minute (extended)
%H               => 08                        Local time, reduced accuracy, specific hour
%H%M%S,%L        => 083748,000                Local time with decimal fraction, comma as decimal sign (basic)
%T,%L            => 08:37:48,000              Local time with decimal fraction, comma as decimal sign (extended)
%H%M%S.%L        => 083748.000                Local time with decimal fraction, full stop as decimal sign (basic)
%T.%L            => 08:37:48.000              Local time with decimal fraction, full stop as decimal sign (extended)
%H%M%S%z         => 083748-0600               Local time and the difference from UTC (basic)
%T%:z            => 08:37:48-06:00            Local time and the difference from UTC (extended)
%Y%m%dT%H%M%S%z  => 20071119T083748-0600      Date and time of day for calendar date (basic)
%FT%T%:z         => 2007-11-19T08:37:48-06:00 Date and time of day for calendar date (extended)
%Y%jT%H%M%S%z    => 2007323T083748-0600       Date and time of day for ordinal date (basic)
%Y-%jT%T%:z      => 2007-323T08:37:48-06:00   Date and time of day for ordinal date (extended)
%GW%V%uT%H%M%S%z => 2007W471T083748-0600      Date and time of day for week date (basic)
%G-W%V-%uT%T%:z  => 2007-W47-1T08:37:48-06:00 Date and time of day for week date (extended)
%Y%m%dT%H%M      => 20071119T0837             Calendar date and local time (basic)
%FT%R            => 2007-11-19T08:37          Calendar date and local time (extended)
%Y%jT%H%MZ       => 2007323T0837Z             Ordinal date and UTC of day (basic)
%Y-%jT%RZ        => 2007-323T08:37Z           Ordinal date and UTC of day (extended)
%GW%V%uT%H%M%z   => 2007W471T0837-0600        Week date and local time and difference from UTC (basic)
%G-W%V-%uT%R%:z  => 2007-W47-1T08:37-06:00    Week date and local time and difference from UTC (extended)

#to_date ⇒ `date`

Returns a ::Date object which denotes self.

[ GitHub ]

# File 'ext/date/date_core.c', line 8878


static VALUE
datetime_to_date(VALUE self)
{
    get_d1a(self);

    if (simple_dat_p(adat)) {
	VALUE new = d_lite_s_alloc_simple(cDate);
	{
	    get_d1b(new);
	    bdat->s = adat->s;
	    bdat->s.jd = m_local_jd(adat);
	    return new;
	}
    }
    else {
	VALUE new = d_lite_s_alloc_simple(cDate);
	{
	    get_d1b(new);
	    copy_complex_to_simple(new, &bdat->s, &adat->c);
	    bdat->s.jd = m_local_jd(adat);
	    bdat->s.flags &= ~(HAVE_DF | HAVE_TIME | COMPLEX_DAT);
	    return new;
	}
    }
}

#to_datetime ⇒ `self`

Returns self.

[ GitHub ]

# File 'ext/date/date_core.c', line 8910


static VALUE
datetime_to_datetime(VALUE self)
{
    return self;
}

#to_s ⇒ `String`

Returns a string in an ISO 8601 format. (This method doesn’t use the expanded representations.)

DateTime.new(2001,2,3,4,5,6,'-7').to_s
                         #=> "2001-02-03T04:05:06-07:00"

[ GitHub ]

# File 'ext/date/date_core.c', line 8414


static VALUE
dt_lite_to_s(VALUE self)
{
    return strftimev("%Y-%m-%dT%H:%M:%S%:z", self, set_tmx);
}

#to_time ⇒ Time

Returns a ::Time object which denotes self.

[ GitHub ]

# File 'ext/date/date_core.c', line 8848


static VALUE
datetime_to_time(VALUE self)
{
    volatile VALUE dup = dup_obj(self);
    {
	VALUE t;

	get_d1(dup);

	t = rb_funcall(rb_cTime,
		   rb_intern("new"),
                   7,
		   m_real_year(dat),
		   INT2FIX(m_mon(dat)),
		   INT2FIX(m_mday(dat)),
		   INT2FIX(m_hour(dat)),
		   INT2FIX(m_min(dat)),
		   f_add(INT2FIX(m_sec(dat)),
			 m_sf_in_sec(dat)),
		   INT2FIX(m_of(dat)));
	return t;
    }
}

#iso8601([n = 0]) ⇒ `String` #xmlschema([n = 0]) ⇒ `String`

Alias for #iso8601.

#zone ⇒ `String`

Returns the timezone.

DateTime.parse('04pm+0730').zone          #=> "+07:30"

[ GitHub ]

# File 'ext/date/date_core.c', line 5415


static VALUE
d_lite_zone(VALUE self)
{
    get_d1(self);
    return m_zone(dat);
}

Class: DateTime

Overview

When should you use DateTime and when should you use Time?

Constant Summary

::Date - Inherited

Class Method Summary

::Date - Inherited

Instance Attribute Summary

::Date - Inherited

Instance Method Summary

::Date - Inherited

Constructor Details

.civil([year=-4712[, month=1[, mday=1[, hour=0[, minute=0[, second=0[, offset=0[, start=Date::ITALY]]]]]]]]) ⇒ DateTime .new([year=-4712[, month=1[, mday=1[, hour=0[, minute=0[, second=0[, offset=0[, start=Date::ITALY]]]]]]]]) ⇒ DateTime Also known as: .civil

Class Method Details

._strptime(string[, format='%FT%T%z']) ⇒ Hash

.civil([year=-4712[, month=1[, mday=1[, hour=0[, minute=0[, second=0[, offset=0[, start=Date::ITALY]]]]]]]]) ⇒ DateTime .new([year=-4712[, month=1[, mday=1[, hour=0[, minute=0[, second=0[, offset=0[, start=Date::ITALY]]]]]]]]) ⇒ DateTime

.commercial([cwyear=-4712[, cweek=1[, cwday=1[, hour=0[, minute=0[, second=0[, offset=0[, start=Date::ITALY]]]]]]]]) ⇒ DateTime

.httpdate(string='Mon, 01 Jan -4712 00:00:00 GMT'[, start=Date::ITALY]) ⇒ DateTime

.iso8601(string='-4712-01-01T00:00:00+00:00'[, start=Date::ITALY], limit: 128) ⇒ DateTime

.jd([jd=0[, hour=0[, minute=0[, second=0[, offset=0[, start=Date::ITALY]]]]]]) ⇒ DateTime

.jisx0301(string='-4712-01-01T00:00:00+00:00'[, start=Date::ITALY], limit: 128) ⇒ DateTime

.now([start = Date::ITALY]) ⇒ DateTime

.nth_kday(*args)

.ordinal([year=-4712[, yday=1[, hour=0[, minute=0[, second=0[, offset=0[, start=Date::ITALY]]]]]]]) ⇒ DateTime

.parse(string='-4712-01-01T00:00:00+00:00'[, comp=true[, start=Date::ITALY]], limit: 128) ⇒ DateTime

.rfc2822(string='Mon, 1 Jan -4712 00:00:00 +0000'[, start=Date::ITALY], limit: 128) ⇒ DateTime .rfc822(string='Mon, 1 Jan -4712 00:00:00 +0000'[, start=Date::ITALY], limit: 128) ⇒ DateTime

.rfc3339(string='-4712-01-01T00:00:00+00:00'[, start=Date::ITALY], limit: 128) ⇒ DateTime

.rfc2822(string='Mon, 1 Jan -4712 00:00:00 +0000'[, start=Date::ITALY], limit: 128) ⇒ DateTime .rfc822(string='Mon, 1 Jan -4712 00:00:00 +0000'[, start=Date::ITALY], limit: 128) ⇒ DateTime Also known as: .rfc2822

.strptime([string='-4712-01-01T00:00:00+00:00'[, format='%FT%T%z'[ ,start=Date::ITALY]]]) ⇒ DateTime

.weeknum(*args)

.xmlschema(string='-4712-01-01T00:00:00+00:00'[, start=Date::ITALY], limit: 128) ⇒ DateTime

Instance Method Details

#hour ⇒ Fixnum

#iso8601([n = 0]) ⇒ String #xmlschema([n = 0]) ⇒ String Also known as: #xmlschema

#jisx0301([n = 0]) ⇒ String

#min ⇒ Fixnum #minute ⇒ Fixnum Also known as: #minute

#min ⇒ Fixnum #minute ⇒ Fixnum

#new_offset([offset = 0]) ⇒ date

#offset ⇒ Rational

#rfc3339([n = 0]) ⇒ String

#sec ⇒ Fixnum #second ⇒ Fixnum Also known as: #second

#sec_fraction ⇒ Rational #second_fraction ⇒ Rational Also known as: #second_fraction

#sec ⇒ Fixnum #second ⇒ Fixnum

#sec_fraction ⇒ Rational #second_fraction ⇒ Rational

#strftime([format = '%FT%T%:z']) ⇒ String

#to_date ⇒ date

#to_datetime ⇒ self

#to_s ⇒ String

#to_time ⇒ Time

#iso8601([n = 0]) ⇒ String #xmlschema([n = 0]) ⇒ String

#zone ⇒ String

`::Date` - Inherited

`::Date` - Inherited

`::Date` - Inherited

`::Date` - Inherited

.civil([year=-4712[, month=1[, mday=1[, hour=0[, minute=0[, second=0[, offset=0[, start=Date::ITALY]]]]]]]]) ⇒ `DateTime` .new([year=-4712[, month=1[, mday=1[, hour=0[, minute=0[, second=0[, offset=0[, start=Date::ITALY]]]]]]]]) ⇒ `DateTime`
Also known as: .civil

._strptime(string[, format='%FT%T%z']) ⇒ `Hash`

.civil([year=-4712[, month=1[, mday=1[, hour=0[, minute=0[, second=0[, offset=0[, start=Date::ITALY]]]]]]]]) ⇒ `DateTime` .new([year=-4712[, month=1[, mday=1[, hour=0[, minute=0[, second=0[, offset=0[, start=Date::ITALY]]]]]]]]) ⇒ `DateTime`

.commercial([cwyear=-4712[, cweek=1[, cwday=1[, hour=0[, minute=0[, second=0[, offset=0[, start=Date::ITALY]]]]]]]]) ⇒ `DateTime`

.httpdate(string='Mon, 01 Jan -4712 00:00:00 GMT'[, start=Date::ITALY]) ⇒ `DateTime`

.iso8601(string='-4712-01-01T00:00:00+00:00'[, start=Date::ITALY], limit: 128) ⇒ `DateTime`

.jd([jd=0[, hour=0[, minute=0[, second=0[, offset=0[, start=Date::ITALY]]]]]]) ⇒ `DateTime`

.jisx0301(string='-4712-01-01T00:00:00+00:00'[, start=Date::ITALY], limit: 128) ⇒ `DateTime`

.now([start = Date::ITALY]) ⇒ `DateTime`

.ordinal([year=-4712[, yday=1[, hour=0[, minute=0[, second=0[, offset=0[, start=Date::ITALY]]]]]]]) ⇒ `DateTime`

.parse(string='-4712-01-01T00:00:00+00:00'[, comp=true[, start=Date::ITALY]], limit: 128) ⇒ `DateTime`

.rfc2822(string='Mon, 1 Jan -4712 00:00:00 +0000'[, start=Date::ITALY], limit: 128) ⇒ `DateTime` .rfc822(string='Mon, 1 Jan -4712 00:00:00 +0000'[, start=Date::ITALY], limit: 128) ⇒ `DateTime`

.rfc3339(string='-4712-01-01T00:00:00+00:00'[, start=Date::ITALY], limit: 128) ⇒ `DateTime`

.rfc2822(string='Mon, 1 Jan -4712 00:00:00 +0000'[, start=Date::ITALY], limit: 128) ⇒ `DateTime` .rfc822(string='Mon, 1 Jan -4712 00:00:00 +0000'[, start=Date::ITALY], limit: 128) ⇒ `DateTime`
Also known as: .rfc2822

.strptime([string='-4712-01-01T00:00:00+00:00'[, format='%FT%T%z'[ ,start=Date::ITALY]]]) ⇒ `DateTime`

.xmlschema(string='-4712-01-01T00:00:00+00:00'[, start=Date::ITALY], limit: 128) ⇒ `DateTime`

#hour ⇒ `Fixnum`

#iso8601([n = 0]) ⇒ `String` #xmlschema([n = 0]) ⇒ `String`
Also known as: #xmlschema

#jisx0301([n = 0]) ⇒ `String`

#min ⇒ `Fixnum` #minute ⇒ `Fixnum`
Also known as: #minute

#min ⇒ `Fixnum` #minute ⇒ `Fixnum`

#new_offset([offset = 0]) ⇒ `date`

#offset ⇒ `Rational`

#rfc3339([n = 0]) ⇒ `String`

#sec ⇒ `Fixnum` #second ⇒ `Fixnum`
Also known as: #second

#sec_fraction ⇒ `Rational` #second_fraction ⇒ `Rational`
Also known as: #second_fraction

#sec ⇒ `Fixnum` #second ⇒ `Fixnum`

#sec_fraction ⇒ `Rational` #second_fraction ⇒ `Rational`

#strftime([format = '%FT%T%:z']) ⇒ `String`

#to_date ⇒ `date`

#to_datetime ⇒ `self`

#to_s ⇒ `String`

#iso8601([n = 0]) ⇒ `String` #xmlschema([n = 0]) ⇒ `String`

#zone ⇒ `String`