In Files

• date/date_core.c

Quicksearch

DateTime

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 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 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 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.

Public Class Methods

_strptime(string[, format='%FT%T%z']) → hash click to toggle source

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.

`See also strptime(3) and strftime.`
```
static VALUE
datetime_s__strptime(int argc, VALUE *argv, VALUE klass)
{
return date_s__strptime_internal(argc, argv, klass, "%FT%T%z");
}
```
civil([year=-4712[, month=1[, mday=1[, hour=0[, minute=0[, second=0[, offset=0[, start=Date::ITALY]]]]]]]]) → datetime click to toggle source

Creates a date-time 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 ...>
```
```
static VALUE
datetime_s_civil(int argc, VALUE *argv, VALUE klass)
{
VALUE vy, vm, vd, vh, vmin, vs, vof, vsg, y, fr, fr2, ret;
int m, d, h, min, s, rof;
double sg;

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

y = INT2FIX(-4712);
m = 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:
m = NUM2INT(vm);
case 1:
y = vy;
}

if (guess_style(y, sg) < 0) {
VALUE nth;
int ry, rm, rd, rh, rmin, rs;

if (!valid_gregorian_p(y, m, d,
&nth, &ry,
&rm, &rd))
rb_raise(rb_eArgError, "invalid date");
if (!c_valid_time_p(h, min, s, &rh, &rmin, &rs))
rb_raise(rb_eArgError, "invalid date");
canon24oc();

ret = d_complex_new_internal(klass,
nth, 0,
0, INT2FIX(0),
rof, sg,
ry, rm, rd,
rh, rmin, rs,
HAVE_CIVIL | HAVE_TIME);
}
else {
VALUE nth;
int ry, rm, rd, rh, rmin, rs, rjd, rjd2, ns;

if (!valid_civil_p(y, m, d, sg,
&nth, &ry,
&rm, &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,
ry, rm, rd,
rh, rmin, rs,
HAVE_JD | HAVE_CIVIL | HAVE_TIME);
}
return ret;
}
```
commercial([cwyear=-4712[, cweek=1[, cwday=1[, hour=0[, minute=0[, second=0[, offset=0[, start=Date::ITALY]]]]]]]]) → datetime click to toggle source

Creates a date-time 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 ...>
```
```
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);
}
return ret;
}
```
httpdate(string='Mon, 01 Jan -4712 00:00:00 GMT'[, start=ITALY]) → datetime click to toggle source

Creates a new Date 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 ...>
```
```
static VALUE
datetime_s_httpdate(int argc, VALUE *argv, VALUE klass)
{
VALUE str, sg;

rb_scan_args(argc, argv, "02", &str, &sg);

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

{
VALUE hash = date_s__httpdate(klass, str);
return dt_new_by_frags(klass, hash, sg);
}
}
```
iso8601(string='-4712-01-01T00:00:00+00:00'[, start=ITALY]) → datetime click to toggle source

Creates a new Date 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 ...>
```
```
static VALUE
datetime_s_iso8601(int argc, VALUE *argv, VALUE klass)
{
VALUE str, sg;

rb_scan_args(argc, argv, "02", &str, &sg);

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

{
VALUE hash = date_s__iso8601(klass, str);
return dt_new_by_frags(klass, hash, sg);
}
}
```
jd([jd=0[, hour=0[, minute=0[, second=0[, offset=0[, start=Date::ITALY]]]]]]) → datetime click to toggle source

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 ...>
```
```
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);
}
return ret;
}
```
jisx0301(string='-4712-01-01T00:00:00+00:00'[, start=ITALY]) → datetime click to toggle source

Creates a new Date 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 ...>
```
```
static VALUE
datetime_s_jisx0301(int argc, VALUE *argv, VALUE klass)
{
VALUE str, sg;

rb_scan_args(argc, argv, "02", &str, &sg);

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

{
VALUE hash = date_s__jisx0301(klass, str);
return dt_new_by_frags(klass, hash, sg);
}
}
```
new([year=-4712[, month=1[, mday=1[, hour=0[, minute=0[, second=0[, offset=0[, start=Date::ITALY]]]]]]]]) → datetime click to toggle source

Creates a date-time 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 ...>
```
```
static VALUE
datetime_s_civil(int argc, VALUE *argv, VALUE klass)
{
VALUE vy, vm, vd, vh, vmin, vs, vof, vsg, y, fr, fr2, ret;
int m, d, h, min, s, rof;
double sg;

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

y = INT2FIX(-4712);
m = 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:
m = NUM2INT(vm);
case 1:
y = vy;
}

if (guess_style(y, sg) < 0) {
VALUE nth;
int ry, rm, rd, rh, rmin, rs;

if (!valid_gregorian_p(y, m, d,
&nth, &ry,
&rm, &rd))
rb_raise(rb_eArgError, "invalid date");
if (!c_valid_time_p(h, min, s, &rh, &rmin, &rs))
rb_raise(rb_eArgError, "invalid date");
canon24oc();

ret = d_complex_new_internal(klass,
nth, 0,
0, INT2FIX(0),
rof, sg,
ry, rm, rd,
rh, rmin, rs,
HAVE_CIVIL | HAVE_TIME);
}
else {
VALUE nth;
int ry, rm, rd, rh, rmin, rs, rjd, rjd2, ns;

if (!valid_civil_p(y, m, d, sg,
&nth, &ry,
&rm, &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,
ry, rm, rd,
rh, rmin, rs,
HAVE_JD | HAVE_CIVIL | HAVE_TIME);
}
return ret;
}
```
now([start=Date::ITALY]) → datetime click to toggle source

Creates a date-time object denoting the present time.

```DateTime.now              #=> #<DateTime: 2011-06-11T21:20:44+09:00 ...>
```
```
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_VAR_TIMEZONE)
#ifdef HAVE_VAR_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;
}
```
ordinal([year=-4712[, yday=1[, hour=0[, minute=0[, second=0[, offset=0[, start=Date::ITALY]]]]]]]) → datetime click to toggle source

Creates a date-time 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 ...>
```
```
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);
}
return ret;
}
```
parse(string='-4712-01-01T00:00:00+00:00'[, comp=true[, start=ITALY]]) → datetime click to toggle source

Parses the given representation of date and time, and creates a date 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 ...>
```
```
static VALUE
datetime_s_parse(int argc, VALUE *argv, VALUE klass)
{
VALUE str, comp, sg;

rb_scan_args(argc, argv, "03", &str, &comp, &sg);

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);
}

{
VALUE argv2[2], hash;

argv2[0] = str;
argv2[1] = comp;
hash = date_s__parse(2, argv2, klass);
return dt_new_by_frags(klass, hash, sg);
}
}
```
rfc2822(string='Mon, 1 Jan -4712 00:00:00 +0000'[, start=ITALY]) → datetime click to toggle source

Creates a new Date 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 ...>
```
```
static VALUE
datetime_s_rfc2822(int argc, VALUE *argv, VALUE klass)
{
VALUE str, sg;

rb_scan_args(argc, argv, "02", &str, &sg);

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

{
VALUE hash = date_s__rfc2822(klass, str);
return dt_new_by_frags(klass, hash, sg);
}
}
```
rfc3339(string='-4712-01-01T00:00:00+00:00'[, start=ITALY]) → datetime click to toggle source

Creates a new Date 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 ...>
```
```
static VALUE
datetime_s_rfc3339(int argc, VALUE *argv, VALUE klass)
{
VALUE str, sg;

rb_scan_args(argc, argv, "02", &str, &sg);

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

{
VALUE hash = date_s__rfc3339(klass, str);
return dt_new_by_frags(klass, hash, sg);
}
}
```
rfc822(string='Mon, 1 Jan -4712 00:00:00 +0000'[, start=ITALY]) → datetime click to toggle source

Creates a new Date 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 ...>
```
```
static VALUE
datetime_s_rfc2822(int argc, VALUE *argv, VALUE klass)
{
VALUE str, sg;

rb_scan_args(argc, argv, "02", &str, &sg);

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

{
VALUE hash = date_s__rfc2822(klass, str);
return dt_new_by_frags(klass, hash, sg);
}
}
```
strptime([string='-4712-01-01T00:00:00+00:00'[, format='%FT%T%z'[ ,start=ITALY]]]) → datetime click to toggle source

Parses the given representation of date and time with the given template, and creates a date 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 ...>
```

```
static VALUE
datetime_s_strptime(int argc, VALUE *argv, VALUE klass)
{
VALUE str, fmt, sg;

rb_scan_args(argc, argv, "03", &str, &fmt, &sg);

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

{
VALUE argv2[2], hash;

argv2[0] = str;
argv2[1] = fmt;
hash = date_s__strptime(2, argv2, klass);
return dt_new_by_frags(klass, hash, sg);
}
}
```
xmlschema(string='-4712-01-01T00:00:00+00:00'[, start=ITALY]) → datetime click to toggle source

Creates a new Date 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 ...>
```
```
static VALUE
datetime_s_xmlschema(int argc, VALUE *argv, VALUE klass)
{
VALUE str, sg;

rb_scan_args(argc, argv, "02", &str, &sg);

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

{
VALUE hash = date_s__xmlschema(klass, str);
return dt_new_by_frags(klass, hash, sg);
}
}
```

Public Instance Methods

iso8601([n=0]) → string click to toggle source
xmlschema([n=0]) → string

This method is equivalent to strftime(‘%FT%T’). The optional argument n is length of fractional seconds.

```DateTime.parse('2001-02-03T04:05:06.123456789+07:00').iso8601(9)
#=> "2001-02-03T04:05:06.123456789+07:00"
```
```
static VALUE
dt_lite_iso8601(int argc, VALUE *argv, VALUE self)
{
VALUE n;

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

if (argc < 1)
n = INT2FIX(0);

iso8601_timediv(self, n));
}
```
jisx0301([n=0]) → string click to toggle source

Returns a string in a JIS X 0301 format. The optional argument n is length of fractional seconds.

```DateTime.parse('2001-02-03T04:05:06.123456789+07:00').jisx0301(9)
#=> "H13.02.03T04:05:06.123456789+07:00"
```
```
static VALUE
dt_lite_jisx0301(int argc, VALUE *argv, VALUE self)
{
VALUE n, s;

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

if (argc < 1)
n = INT2FIX(0);

{
get_d1(self);
s = jisx0301_date(m_real_local_jd(dat),
m_real_year(dat));
return rb_str_append(strftimev(RSTRING_PTR(s), self, set_tmx),
iso8601_timediv(self, n));
}
}
```
rfc3339([n=0]) → string click to toggle source

This method is equivalent to strftime(‘%FT%T’). The optional argument n is length of fractional seconds.

```DateTime.parse('2001-02-03T04:05:06.123456789+07:00').rfc3339(9)
#=> "2001-02-03T04:05:06.123456789+07:00"
```
```
static VALUE
dt_lite_rfc3339(int argc, VALUE *argv, VALUE self)
{
return dt_lite_iso8601(argc, argv, self);
}
```
strftime([format='%FT%T%:z']) → string click to toggle source
```Formats date according to the directives in the given format
string.
The directives begins with a percent (%) character.
Any text not listed as a directive will be passed through to the
output string.

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

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

Flags:
-  don't pad a numerical output.
^  upcase the result string.
#  change case.
:  use colons for %z.

The minimum field width specifies the minimum width.

The modifier is "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)
%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)
%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..59)

%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 - Time zone abbreviation name or something similar information.

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 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 a 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)```

```
static VALUE
dt_lite_strftime(int argc, VALUE *argv, VALUE self)
{
return date_strftime_internal(argc, argv, self,
"%Y-%m-%dT%H:%M:%S%:z", set_tmx);
}
```
to_date → date click to toggle source

Returns a Date object which denotes self.

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

VALUE new = d_lite_s_alloc_simple(cDate);
{
get_d1b(new);
return new;
}
}
else {
VALUE new = d_lite_s_alloc_simple(cDate);
{
get_d1b(new);
bdat->s.flags &= ~(HAVE_DF | HAVE_TIME | COMPLEX_DAT);
return new;
}
}
}
```
to_datetime → self click to toggle source

Returns self.

```
static VALUE
datetime_to_datetime(VALUE self)
{
return self;
}
```
to_s → string click to toggle source

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"
```
```
static VALUE
dt_lite_to_s(VALUE self)
{
return strftimev("%Y-%m-%dT%H:%M:%S%:z", self, set_tmx);
}
```
to_time → time click to toggle source

Returns a Time object which denotes self.

```
static VALUE
datetime_to_time(VALUE self)
{
volatile VALUE dup = dup_obj_with_new_offset(self, 0);
{
VALUE t;

get_d1(dup);

t = f_utc6(rb_cTime,
m_real_year(dat),
INT2FIX(m_mon(dat)),
INT2FIX(m_mday(dat)),
INT2FIX(m_hour(dat)),
INT2FIX(m_min(dat)),
m_sf_in_sec(dat)));
return f_getlocal(t);
}
}
```
iso8601([n=0]) → string click to toggle source
xmlschema([n=0]) → string

This method is equivalent to strftime(‘%FT%T’). The optional argument n is length of fractional seconds.

```DateTime.parse('2001-02-03T04:05:06.123456789+07:00').iso8601(9)
#=> "2001-02-03T04:05:06.123456789+07:00"
```
```
static VALUE
dt_lite_iso8601(int argc, VALUE *argv, VALUE self)
{
VALUE n;

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

if (argc < 1)
n = INT2FIX(0);