Class: Time
Overview
Time is an abstraction of dates and times. Time is stored internally as the number of seconds with fraction since the Epoch, January 1, 1970 00:00 UTC. Also see the library module Date. The Time class treats GMT (Greenwich Mean Time) and UTC (Coordinated Universal Time) as equivalent. GMT is the older way of referring to these baseline times but persists in the names of calls on POSIX systems.
All times may have fraction. Be aware of this fact when comparing times with each other – times that are apparently equal when displayed may be different when compared.
Since Ruby 1.9.2, Time implementation uses a signed 63 bit integer, Bignum or Rational. The integer is a number of nanoseconds since the Epoch which can represent 1823-11-12 to 2116-02-20. When Bignum or Rational is used (before 1823, after 2116, under nanosecond), Time works slower as when integer is used.
Examples
All of these examples were done using the EST timezone which is GMT-5.
Creating a new Time instance
You can create a new instance of Time with Time::new. This will use the current system time. Time::now is an alias for this. You can also pass parts of the time to Time::new such as year, month, minute, etc. When you want to construct a time this way you must pass at least a year. If you pass the year with nothing else time will default to January 1 of that year at 00:00:00 with the current system timezone. Here are some examples:
Time.new(2002) #=> 2002-01-01 00:00:00 -0500
Time.new(2002, 10) #=> 2002-10-01 00:00:00 -0500
Time.new(2002, 10, 31) #=> 2002-10-31 00:00:00 -0500
Time.new(2002, 10, 31, 2, 2, 2, "+02:00") #=> 2002-10-31 02:02:02 +0200
You can also use #gm, #local and #utc to infer GMT, local and UTC timezones instead of using the current system setting.
You can also create a new time using Time::at which takes the number of seconds (or fraction of seconds) since the Unix Epoch.
Time.at(628232400) #=> 1989-11-28 00:00:00 -0500
Working with an instance of Time
Once you have an instance of Time there is a multitude of things you can do with it. Below are some examples. For all of the following examples, we will work on the assumption that you have done the following:
t = Time.new(1993, 02, 24, 12, 0, 0, "+09:00")
Was that a monday?
t.monday? #=> false
What year was that again?
t.year #=> 1993
Was is daylight savings at the time?
t.dst? #=> false
What’s the day a year later?
t + (60*60*24*365) #=> 1994-02-24 12:00:00 +0900
How many seconds was that since the Unix Epoch?
t.to_i #=> 730522800
You can also do standard functions like compare two times.
t1 = Time.new(2010)
t2 = Time.new(2011)
t1 == t2 #=> false
t1 == t1 #=> true
t1 < t2 #=> true
t1 > t2 #=> false
Time.new(2010,10,31).between?(t1, t2) #=> true
Class Method Summary collapse
-
.at(*args) ⇒ Object
Creates a new Time object with the value given by
time
, the given number ofseconds_with_frac
, orseconds
andmicroseconds_with_frac
since the Epoch. -
.gm(*args) ⇒ Object
Creates a Time object based on given values, interpreted as UTC (GMT).
-
.local(*args) ⇒ Object
Same as Time::gm, but interprets the values in the local time zone.
-
.mktime(*args) ⇒ Object
Same as Time::gm, but interprets the values in the local time zone.
-
.now ⇒ Time
Creates a new Time object for the current time.
-
.utc(*args) ⇒ Object
Creates a Time object based on given values, interpreted as UTC (GMT).
Instance Method Summary collapse
-
#+(numeric) ⇒ Time
Addition — Adds some number of seconds (possibly fractional) to time and returns that value as a new Time object.
-
#-(time2) ⇒ Object
Difference — Returns a new Time object that represents the difference between time and
other_time
, or subtracts the given number of seconds innumeric
from time. -
#<=>(other_time) ⇒ -1, ...
Comparison—Compares
time
withother_time
. -
#_dump(*args) ⇒ Object
private
:nodoc:.
-
#asctime ⇒ Object
Returns a canonical string representation of time.
-
#ctime ⇒ Object
Returns a canonical string representation of time.
-
#day ⇒ Object
Returns the day of the month (1..n) for time.
-
#dst? ⇒ Boolean
Returns
true
if time occurs during Daylight Saving Time in its time zone. -
#eql?(other_time) ⇒ Boolean
Returns
true
if time andother_time
are both Time objects with the same seconds and fractional seconds. -
#friday? ⇒ Boolean
Returns
true
if time represents Friday. -
#getgm ⇒ Object
Returns a new Time object representing time in UTC.
-
#getlocal(*args) ⇒ Object
Returns a new Time object representing time in local time (using the local time zone in effect for this process).
-
#getutc ⇒ Object
Returns a new Time object representing time in UTC.
-
#gmt? ⇒ Boolean
Returns
true
if time represents a time in UTC (GMT). -
#gmt_offset ⇒ Object
Returns the offset in seconds between the timezone of time and UTC.
-
#gmtime ⇒ Object
Converts time to UTC (GMT), modifying the receiver.
-
#gmtoff ⇒ Object
Returns the offset in seconds between the timezone of time and UTC.
-
#hash ⇒ Fixnum
Returns a hash code for this Time object.
-
#hour ⇒ Fixnum
Returns the hour of the day (0..23) for time.
-
#initialize(*args) ⇒ Object
constructor
Returns a Time object.
-
#initialize_copy(time) ⇒ Object
:nodoc:.
-
#inspect ⇒ Object
Returns a string representing time.
-
#isdst ⇒ Object
Returns
true
if time occurs during Daylight Saving Time in its time zone. -
#localtime(*args) ⇒ Object
Converts time to local time (using the local time zone in effect for this process) modifying the receiver.
-
#marshal_dump ⇒ Object
private
:nodoc:.
-
#marshal_load(str) ⇒ Object
private
:nodoc:.
-
#mday ⇒ Object
Returns the day of the month (1..n) for time.
-
#min ⇒ Fixnum
Returns the minute of the hour (0..59) for time.
-
#mon ⇒ Object
Returns the month of the year (1..12) for time.
-
#monday? ⇒ Boolean
Returns
true
if time represents Monday. -
#month ⇒ Object
Returns the month of the year (1..12) for time.
-
#nsec ⇒ Object
Returns the number of nanoseconds for time.
-
#round([ndigits]) ⇒ Time
Rounds sub seconds to a given precision in decimal digits (0 digits by default).
-
#saturday? ⇒ Boolean
Returns
true
if time represents Saturday. -
#sec ⇒ Fixnum
Returns the second of the minute (0..60) for time.
-
#strftime(string) ⇒ String
Formats time according to the directives in the given format string.
-
#subsec ⇒ Numeric
Returns the fraction for time.
- #succ ⇒ Object
-
#sunday? ⇒ Boolean
Returns
true
if time represents Sunday. -
#thursday? ⇒ Boolean
Returns
true
if time represents Thursday. -
#to_a ⇒ Array
Returns a ten-element array of values for time:.
-
#to_f ⇒ Float
Returns the value of time as a floating point number of seconds since the Epoch.
-
#to_i ⇒ Object
Returns the value of time as an integer number of seconds since the Epoch.
-
#to_r ⇒ Object
Returns the value of time as a rational number of seconds since the Epoch.
-
#to_s ⇒ Object
Returns a string representing time.
-
#tuesday? ⇒ Boolean
Returns
true
if time represents Tuesday. -
#tv_nsec ⇒ Object
Returns the number of nanoseconds for time.
-
#tv_sec ⇒ Object
Returns the value of time as an integer number of seconds since the Epoch.
-
#tv_usec ⇒ Object
Returns the number of microseconds for time.
-
#usec ⇒ Object
Returns the number of microseconds for time.
-
#utc ⇒ Object
Converts time to UTC (GMT), modifying the receiver.
-
#utc? ⇒ Boolean
Returns
true
if time represents a time in UTC (GMT). -
#utc_offset ⇒ Object
Returns the offset in seconds between the timezone of time and UTC.
-
#wday ⇒ Fixnum
Returns an integer representing the day of the week, 0..6, with Sunday == 0.
-
#wednesday? ⇒ Boolean
Returns
true
if time represents Wednesday. -
#yday ⇒ Fixnum
Returns an integer representing the day of the year, 1..366.
-
#year ⇒ Fixnum
Returns the year for time (including the century).
-
#zone ⇒ String
Returns the name of the time zone used for time.
Methods included from Comparable
#<, #<=, #==, #>, #>=, #between?
Constructor Details
#new ⇒ Time #new(year, month = nil, day = nil, hour = nil, min = nil, sec = nil, utc_offset = nil) ⇒ Time
Returns a Time object.
It is initialized to the current system time if no argument is given.
Note: The new object will use the resolution available on your system clock, and may include fractional seconds.
If one or more arguments specified, the time is initialized to the specified time.
sec
may have fraction if it is a rational.
utc_offset
is the offset from UTC. It can be a string such as “+09:00” or a number of seconds such as 32400.
a = Time.new #=> 2007-11-19 07:50:02 -0600
b = Time.new #=> 2007-11-19 07:50:02 -0600
a == b #=> false
"%.6f" % a.to_f #=> "1195480202.282373"
"%.6f" % b.to_f #=> "1195480202.283415"
Time.new(2008,6,21, 13,30,0, "+09:00") #=> 2008-06-21 13:30:00 +0900
# A trip for RubyConf 2007
t1 = Time.new(2007,11,1,15,25,0, "+09:00") # JST (Narita)
t2 = Time.new(2007,11,1,12, 5,0, "-05:00") # CDT (Minneapolis)
t3 = Time.new(2007,11,1,13,25,0, "-05:00") # CDT (Minneapolis)
t4 = Time.new(2007,11,1,16,53,0, "-04:00") # EDT (Charlotte)
t5 = Time.new(2007,11,5, 9,24,0, "-05:00") # EST (Charlotte)
t6 = Time.new(2007,11,5,11,21,0, "-05:00") # EST (Detroit)
t7 = Time.new(2007,11,5,13,45,0, "-05:00") # EST (Detroit)
t8 = Time.new(2007,11,6,17,10,0, "+09:00") # JST (Narita)
p((t2-t1)/3600.0) #=> 10.666666666666666
p((t4-t3)/3600.0) #=> 2.466666666666667
p((t6-t5)/3600.0) #=> 1.95
p((t8-t7)/3600.0) #=> 13.416666666666666
2207 2208 2209 2210 2211 2212 2213 2214 |
# File 'time.c', line 2207
static VALUE
time_init(int argc, VALUE *argv, VALUE time)
{
if (argc == 0)
return time_init_0(time);
else
return time_init_1(argc, argv, time);
}
|
Class Method Details
.at(time) ⇒ Time .at(seconds_with_frac) ⇒ Time .at(seconds, microseconds_with_frac) ⇒ Time
Creates a new Time object with the value given by time
, the given number of seconds_with_frac
, or seconds
and microseconds_with_frac
since the Epoch. seconds_with_frac
and microseconds_with_frac
can be an Integer, Float, Rational, or other Numeric. non-portable feature allows the offset to be negative on some systems.
If a numeric argument is given, the result is in local time.
Time.at(0) #=> 1969-12-31 18:00:00 -0600
Time.at(Time.at(0)) #=> 1969-12-31 18:00:00 -0600
Time.at(946702800) #=> 1999-12-31 23:00:00 -0600
Time.at(-284061600) #=> 1960-12-31 00:00:00 -0600
Time.at(946684800.2).usec #=> 200000
Time.at(946684800, 123456.789).nsec #=> 123456789
2478 2479 2480 2481 2482 2483 2484 2485 2486 2487 2488 2489 2490 2491 2492 2493 2494 2495 2496 2497 2498 2499 2500 2501 2502 2503 |
# File 'time.c', line 2478
static VALUE
time_s_at(int argc, VALUE *argv, VALUE klass)
{
VALUE time, t;
wideval_t timew;
if (rb_scan_args(argc, argv, "11", &time, &t) == 2) {
time = num_exact(time);
t = num_exact(t);
timew = wadd(rb_time_magnify(v2w(time)), wmulquoll(v2w(t), TIME_SCALE, 1000000));
t = time_new_timew(klass, timew);
}
else if (IsTimeval(time)) {
struct time_object *tobj, *tobj2;
GetTimeval(time, tobj);
t = time_new_timew(klass, tobj->timew);
GetTimeval(t, tobj2);
TIME_COPY_GMT(tobj2, tobj);
}
else {
timew = rb_time_magnify(v2w(num_exact(time)));
t = time_new_timew(klass, timew);
}
return t;
}
|
.utc(year) ⇒ Time .utc(year, month) ⇒ Time .utc(year, month, day) ⇒ Time .utc(year, month, day, hour) ⇒ Time .utc(year, month, day, hour, min) ⇒ Time .utc(year, month, day, hour, min, sec_with_frac) ⇒ Time .utc(year, month, day, hour, min, sec, usec_with_frac) ⇒ Time .utc(sec, min, hour, day, month, year, dummy, dummy, dummy, dummy) ⇒ Time .gm(year) ⇒ Time .gm(year, month) ⇒ Time .gm(year, month, day) ⇒ Time .gm(year, month, day, hour) ⇒ Time .gm(year, month, day, hour, min) ⇒ Time .gm(year, month, day, hour, min, sec_with_frac) ⇒ Time .gm(year, month, day, hour, min, sec, usec_with_frac) ⇒ Time .gm(sec, min, hour, day, month, year, dummy, dummy, dummy, dummy) ⇒ Time
Creates a Time object based on given values, interpreted as UTC (GMT). The year must be specified. Other values default to the minimum value for that field (and may be nil
or omitted). Months may be specified by numbers from 1 to 12, or by the three-letter English month names. Hours are specified on a 24-hour clock (0..23). Raises an ArgumentError if any values are out of range. Will also accept ten arguments in the order output by Time#to_a.
sec_with_frac
and usec_with_frac
can have a fractional part.
Time.utc(2000,"jan",1,20,15,1) #=> 2000-01-01 20:15:01 UTC
Time.gm(2000,"jan",1,20,15,1) #=> 2000-01-01 20:15:01 UTC
3111 3112 3113 3114 3115 |
# File 'time.c', line 3111
static VALUE
time_s_mkutc(int argc, VALUE *argv, VALUE klass)
{
return time_utc_or_local(argc, argv, TRUE, klass);
}
|
.local(year) ⇒ Time .local(year, month) ⇒ Time .local(year, month, day) ⇒ Time .local(year, month, day, hour) ⇒ Time .local(year, month, day, hour, min) ⇒ Time .local(year, month, day, hour, min, sec_with_frac) ⇒ Time .local(year, month, day, hour, min, sec, usec_with_frac) ⇒ Time .local(sec, min, hour, day, month, year, dummy, dummy, isdst, dummy) ⇒ Time .mktime(year) ⇒ Time .mktime(year, month) ⇒ Time .mktime(year, month, day) ⇒ Time .mktime(year, month, day, hour) ⇒ Time .mktime(year, month, day, hour, min) ⇒ Time .mktime(year, month, day, hour, min, sec_with_frac) ⇒ Time .mktime(year, month, day, hour, min, sec, usec_with_frac) ⇒ Time .mktime(sec, min, hour, day, month, year, dummy, dummy, isdst, dummy) ⇒ Time
Same as Time::gm, but interprets the values in the local time zone.
Time.local(2000,"jan",1,20,15,1) #=> 2000-01-01 20:15:01 -0600
3142 3143 3144 3145 3146 |
# File 'time.c', line 3142
static VALUE
time_s_mktime(int argc, VALUE *argv, VALUE klass)
{
return time_utc_or_local(argc, argv, FALSE, klass);
}
|
.local(year) ⇒ Time .local(year, month) ⇒ Time .local(year, month, day) ⇒ Time .local(year, month, day, hour) ⇒ Time .local(year, month, day, hour, min) ⇒ Time .local(year, month, day, hour, min, sec_with_frac) ⇒ Time .local(year, month, day, hour, min, sec, usec_with_frac) ⇒ Time .local(sec, min, hour, day, month, year, dummy, dummy, isdst, dummy) ⇒ Time .mktime(year) ⇒ Time .mktime(year, month) ⇒ Time .mktime(year, month, day) ⇒ Time .mktime(year, month, day, hour) ⇒ Time .mktime(year, month, day, hour, min) ⇒ Time .mktime(year, month, day, hour, min, sec_with_frac) ⇒ Time .mktime(year, month, day, hour, min, sec, usec_with_frac) ⇒ Time .mktime(sec, min, hour, day, month, year, dummy, dummy, isdst, dummy) ⇒ Time
3142 3143 3144 3145 3146 |
# File 'time.c', line 3142
static VALUE
time_s_mktime(int argc, VALUE *argv, VALUE klass)
{
return time_utc_or_local(argc, argv, FALSE, klass);
}
|
.now ⇒ Time
Creates a new Time object for the current time. This is same as Time.new without arguments.
Time.now #=> 2009-06-24 12:39:54 +0900
2449 2450 2451 2452 2453 |
# File 'time.c', line 2449
static VALUE
time_s_now(VALUE klass)
{
return rb_class_new_instance(0, NULL, klass);
}
|
.utc(year) ⇒ Time .utc(year, month) ⇒ Time .utc(year, month, day) ⇒ Time .utc(year, month, day, hour) ⇒ Time .utc(year, month, day, hour, min) ⇒ Time .utc(year, month, day, hour, min, sec_with_frac) ⇒ Time .utc(year, month, day, hour, min, sec, usec_with_frac) ⇒ Time .utc(sec, min, hour, day, month, year, dummy, dummy, dummy, dummy) ⇒ Time .gm(year) ⇒ Time .gm(year, month) ⇒ Time .gm(year, month, day) ⇒ Time .gm(year, month, day, hour) ⇒ Time .gm(year, month, day, hour, min) ⇒ Time .gm(year, month, day, hour, min, sec_with_frac) ⇒ Time .gm(year, month, day, hour, min, sec, usec_with_frac) ⇒ Time .gm(sec, min, hour, day, month, year, dummy, dummy, dummy, dummy) ⇒ Time
Creates a Time object based on given values, interpreted as UTC (GMT). The year must be specified. Other values default to the minimum value for that field (and may be nil
or omitted). Months may be specified by numbers from 1 to 12, or by the three-letter English month names. Hours are specified on a 24-hour clock (0..23). Raises an ArgumentError if any values are out of range. Will also accept ten arguments in the order output by Time#to_a.
sec_with_frac
and usec_with_frac
can have a fractional part.
Time.utc(2000,"jan",1,20,15,1) #=> 2000-01-01 20:15:01 UTC
Time.gm(2000,"jan",1,20,15,1) #=> 2000-01-01 20:15:01 UTC
3111 3112 3113 3114 3115 |
# File 'time.c', line 3111
static VALUE
time_s_mkutc(int argc, VALUE *argv, VALUE klass)
{
return time_utc_or_local(argc, argv, TRUE, klass);
}
|
Instance Method Details
#+(numeric) ⇒ Time
3717 3718 3719 3720 3721 3722 3723 3724 3725 3726 3727 |
# File 'time.c', line 3717
static VALUE
time_plus(VALUE time1, VALUE time2)
{
struct time_object *tobj;
GetTimeval(time1, tobj);
if (IsTimeval(time2)) {
rb_raise(rb_eTypeError, "time + time?");
}
return time_add(tobj, time2, 1);
}
|
#-(other_time) ⇒ Float #-(numeric) ⇒ Time
Difference — Returns a new Time object that represents the difference between time and other_time
, or subtracts the given number of seconds in numeric
from time.
t = Time.now #=> 2007-11-19 08:23:10 -0600
t2 = t + 2592000 #=> 2007-12-19 08:23:10 -0600
t2 - t #=> 2592000.0
t2 - 2592000 #=> 2007-11-19 08:23:10 -0600
3744 3745 3746 3747 3748 3749 3750 3751 3752 3753 3754 3755 3756 3757 |
# File 'time.c', line 3744
static VALUE
time_minus(VALUE time1, VALUE time2)
{
struct time_object *tobj;
GetTimeval(time1, tobj);
if (IsTimeval(time2)) {
struct time_object *tobj2;
GetTimeval(time2, tobj2);
return rb_Float(rb_time_unmagnify_to_float(wsub(tobj->timew, tobj2->timew)));
}
return time_add(tobj, time2, -1);
}
|
#<=>(other_time) ⇒ -1, ...
Comparison—Compares time
with other_time
.
-1, 0, +1 or nil depending on whether time
is less than, equal to, or greater than other_time
.
nil
is returned if the two values are incomparable.
t = Time.now #=> 2007-11-19 08:12:12 -0600
t2 = t + 2592000 #=> 2007-12-19 08:12:12 -0600
t <=> t2 #=> -1
t2 <=> t #=> 1
t = Time.now #=> 2007-11-19 08:13:38 -0600
t2 = t + 0.1 #=> 2007-11-19 08:13:38 -0600
t.nsec #=> 98222999
t2.nsec #=> 198222999
t <=> t2 #=> -1
t2 <=> t #=> 1
t <=> t #=> 0
3328 3329 3330 3331 3332 3333 3334 3335 3336 3337 3338 3339 3340 3341 3342 3343 3344 3345 |
# File 'time.c', line 3328
static VALUE
time_cmp(VALUE time1, VALUE time2)
{
struct time_object *tobj1, *tobj2;
int n;
GetTimeval(time1, tobj1);
if (IsTimeval(time2)) {
GetTimeval(time2, tobj2);
n = wcmp(tobj1->timew, tobj2->timew);
}
else {
return rb_invcmp(time1, time2);
}
if (n == 0) return INT2FIX(0);
if (n > 0) return INT2FIX(1);
return INT2FIX(-1);
}
|
#_dump(*args) ⇒ Object (private)
:nodoc:
4709 4710 4711 4712 4713 4714 4715 4716 4717 4718 |
# File 'time.c', line 4709
static VALUE
time_dump(int argc, VALUE *argv, VALUE time)
{
VALUE str;
rb_scan_args(argc, argv, "01", 0);
str = time_mdump(time);
return str;
}
|
#asctime ⇒ String #ctime ⇒ String
3651 3652 3653 3654 3655 |
# File 'time.c', line 3651
static VALUE
time_asctime(VALUE time)
{
return strftimev("%a %b %e %T %Y", time, rb_usascii_encoding());
}
|
#asctime ⇒ String #ctime ⇒ String
3651 3652 3653 3654 3655 |
# File 'time.c', line 3651
static VALUE
time_asctime(VALUE time)
{
return strftimev("%a %b %e %T %Y", time, rb_usascii_encoding());
}
|
#day ⇒ Fixnum #mday ⇒ Fixnum
3940 3941 3942 3943 3944 3945 3946 3947 3948 |
# File 'time.c', line 3940
static VALUE
time_mday(VALUE time)
{
struct time_object *tobj;
GetTimeval(time, tobj);
MAKE_TM(time, tobj);
return INT2FIX(tobj->vtm.mday);
}
|
#isdst ⇒ Boolean #dst? ⇒ Boolean
Returns true
if time occurs during Daylight Saving Time in its time zone.
# CST6CDT:
Time.local(2000, 1, 1).zone #=> "CST"
Time.local(2000, 1, 1).isdst #=> false
Time.local(2000, 1, 1).dst? #=> false
Time.local(2000, 7, 1).zone #=> "CDT"
Time.local(2000, 7, 1).isdst #=> true
Time.local(2000, 7, 1).dst? #=> true
# Asia/Tokyo:
Time.local(2000, 1, 1).zone #=> "JST"
Time.local(2000, 1, 1).isdst #=> false
Time.local(2000, 1, 1).dst? #=> false
Time.local(2000, 7, 1).zone #=> "JST"
Time.local(2000, 7, 1).isdst #=> false
Time.local(2000, 7, 1).dst? #=> false
4184 4185 4186 4187 4188 4189 4190 4191 4192 |
# File 'time.c', line 4184
static VALUE
time_isdst(VALUE time)
{
struct time_object *tobj;
GetTimeval(time, tobj);
MAKE_TM(time, tobj);
return tobj->vtm.isdst ? Qtrue : Qfalse;
}
|
#eql?(other_time) ⇒ Boolean
Returns true
if time and other_time
are both Time objects with the same seconds and fractional seconds.
3355 3356 3357 3358 3359 3360 3361 3362 3363 3364 3365 3366 |
# File 'time.c', line 3355
static VALUE
time_eql(VALUE time1, VALUE time2)
{
struct time_object *tobj1, *tobj2;
GetTimeval(time1, tobj1);
if (IsTimeval(time2)) {
GetTimeval(time2, tobj2);
return rb_equal(w2v(tobj1->timew), w2v(tobj2->timew));
}
return Qfalse;
}
|
#friday? ⇒ Boolean
4117 4118 4119 4120 4121 |
# File 'time.c', line 4117
static VALUE
time_friday(VALUE time)
{
wday_p(5);
}
|
#getgm ⇒ Time #getutc ⇒ Time
3625 3626 3627 3628 3629 |
# File 'time.c', line 3625
static VALUE
time_getgmtime(VALUE time)
{
return time_gmtime(time_dup(time));
}
|
#getlocal ⇒ Time #getlocal(utc_offset) ⇒ Time
Returns a new Time object representing time in local time (using the local time zone in effect for this process).
If utc_offset
is given, it is used instead of the local time.
t = Time.utc(2000,1,1,20,15,1) #=> 2000-01-01 20:15:01 UTC
t.utc? #=> true
l = t.getlocal #=> 2000-01-01 14:15:01 -0600
l.utc? #=> false
t == l #=> true
j = t.getlocal("+09:00") #=> 2000-01-02 05:15:01 +0900
j.utc? #=> false
t == j #=> true
3593 3594 3595 3596 3597 3598 3599 3600 3601 3602 3603 3604 3605 3606 3607 3608 3609 |
# File 'time.c', line 3593
static VALUE
time_getlocaltime(int argc, VALUE *argv, VALUE time)
{
VALUE off;
rb_scan_args(argc, argv, "01", &off);
if (!NIL_P(off)) {
off = utc_offset_arg(off);
validate_utc_offset(off);
time = time_dup(time);
time_set_utc_offset(time, off);
return time_fixoff(time);
}
return time_localtime(time_dup(time));
}
|
#getgm ⇒ Time #getutc ⇒ Time
3625 3626 3627 3628 3629 |
# File 'time.c', line 3625
static VALUE
time_getgmtime(VALUE time)
{
return time_gmtime(time_dup(time));
}
|
#utc? ⇒ Boolean #gmt? ⇒ Boolean
Returns true
if time represents a time in UTC (GMT).
t = Time.now #=> 2007-11-19 08:15:23 -0600
t.utc? #=> false
t = Time.gm(2000,"jan",1,20,15,1) #=> 2000-01-01 20:15:01 UTC
t.utc? #=> true
t = Time.now #=> 2007-11-19 08:16:03 -0600
t.gmt? #=> false
t = Time.gm(2000,1,1,20,15,1) #=> 2000-01-01 20:15:01 UTC
t.gmt? #=> true
3386 3387 3388 3389 3390 3391 3392 3393 3394 |
# File 'time.c', line 3386
static VALUE
time_utc_p(VALUE time)
{
struct time_object *tobj;
GetTimeval(time, tobj);
if (TIME_UTC_P(tobj)) return Qtrue;
return Qfalse;
}
|
#gmt_offset ⇒ Fixnum #gmtoff ⇒ Fixnum #utc_offset ⇒ Fixnum
4252 4253 4254 4255 4256 4257 4258 4259 4260 4261 4262 4263 4264 4265 4266 |
# File 'time.c', line 4252
static VALUE
time_utc_offset(VALUE time)
{
struct time_object *tobj;
GetTimeval(time, tobj);
MAKE_TM(time, tobj);
if (TIME_UTC_P(tobj)) {
return INT2FIX(0);
}
else {
return tobj->vtm.utc_offset;
}
}
|
#gmtime ⇒ Time #utc ⇒ Time
3515 3516 3517 3518 3519 3520 3521 3522 3523 3524 3525 3526 3527 3528 3529 3530 3531 3532 3533 3534 3535 3536 3537 |
# File 'time.c', line 3515
static VALUE
time_gmtime(VALUE time)
{
struct time_object *tobj;
struct vtm vtm;
GetTimeval(time, tobj);
if (TIME_UTC_P(tobj)) {
if (tobj->tm_got)
return time;
}
else {
time_modify(time);
}
if (!gmtimew(tobj->timew, &vtm))
rb_raise(rb_eArgError, "gmtime error");
tobj->vtm = vtm;
tobj->tm_got = 1;
TIME_SET_UTC(tobj);
return time;
}
|
#gmt_offset ⇒ Fixnum #gmtoff ⇒ Fixnum #utc_offset ⇒ Fixnum
4252 4253 4254 4255 4256 4257 4258 4259 4260 4261 4262 4263 4264 4265 4266 |
# File 'time.c', line 4252
static VALUE
time_utc_offset(VALUE time)
{
struct time_object *tobj;
GetTimeval(time, tobj);
MAKE_TM(time, tobj);
if (TIME_UTC_P(tobj)) {
return INT2FIX(0);
}
else {
return tobj->vtm.utc_offset;
}
}
|
#hash ⇒ Fixnum
Returns a hash code for this Time object.
See also Object#hash.
3405 3406 3407 3408 3409 3410 3411 3412 |
# File 'time.c', line 3405
static VALUE
time_hash(VALUE time)
{
struct time_object *tobj;
GetTimeval(time, tobj);
return rb_hash(w2v(tobj->timew));
}
|
#hour ⇒ Fixnum
3918 3919 3920 3921 3922 3923 3924 3925 3926 |
# File 'time.c', line 3918
static VALUE
time_hour(VALUE time)
{
struct time_object *tobj;
GetTimeval(time, tobj);
MAKE_TM(time, tobj);
return INT2FIX(tobj->vtm.hour);
}
|
#initialize_copy(time) ⇒ Object
:nodoc:
3415 3416 3417 3418 3419 3420 3421 3422 3423 3424 3425 3426 |
# File 'time.c', line 3415
static VALUE
time_init_copy(VALUE copy, VALUE time)
{
struct time_object *tobj, *tcopy;
if (!OBJ_INIT_COPY(copy, time)) return copy;
GetTimeval(time, tobj);
GetNewTimeval(copy, tcopy);
MEMCPY(tcopy, tobj, struct time_object, 1);
return copy;
}
|
#inspect ⇒ String #to_s ⇒ String
Returns a string representing time. Equivalent to calling #strftime with the appropriate format string.
t = Time.now
t.to_s => "2012-11-10 18:16:12 +0100"
t.strftime "%Y-%m-%d %H:%M:%S %z" => "2012-11-10 18:16:12 +0100"
t.utc.to_s => "2012-11-10 17:16:12 UTC"
t.strftime "%Y-%m-%d %H:%M:%S UTC" => "2012-11-10 17:16:12 UTC"
3673 3674 3675 3676 3677 3678 3679 3680 3681 3682 3683 |
# File 'time.c', line 3673
static VALUE
time_to_s(VALUE time)
{
struct time_object *tobj;
GetTimeval(time, tobj);
if (TIME_UTC_P(tobj))
return strftimev("%Y-%m-%d %H:%M:%S UTC", time, rb_usascii_encoding());
else
return strftimev("%Y-%m-%d %H:%M:%S %z", time, rb_usascii_encoding());
}
|
#isdst ⇒ Boolean #dst? ⇒ Boolean
Returns true
if time occurs during Daylight Saving Time in its time zone.
# CST6CDT:
Time.local(2000, 1, 1).zone #=> "CST"
Time.local(2000, 1, 1).isdst #=> false
Time.local(2000, 1, 1).dst? #=> false
Time.local(2000, 7, 1).zone #=> "CDT"
Time.local(2000, 7, 1).isdst #=> true
Time.local(2000, 7, 1).dst? #=> true
# Asia/Tokyo:
Time.local(2000, 1, 1).zone #=> "JST"
Time.local(2000, 1, 1).isdst #=> false
Time.local(2000, 1, 1).dst? #=> false
Time.local(2000, 7, 1).zone #=> "JST"
Time.local(2000, 7, 1).isdst #=> false
Time.local(2000, 7, 1).dst? #=> false
4184 4185 4186 4187 4188 4189 4190 4191 4192 |
# File 'time.c', line 4184
static VALUE
time_isdst(VALUE time)
{
struct time_object *tobj;
GetTimeval(time, tobj);
MAKE_TM(time, tobj);
return tobj->vtm.isdst ? Qtrue : Qfalse;
}
|
#localtime ⇒ Time #localtime(utc_offset) ⇒ Time
Converts time to local time (using the local time zone in effect for this process) modifying the receiver.
If utc_offset
is given, it is used instead of the local time.
t = Time.utc(2000, "jan", 1, 20, 15, 1) #=> 2000-01-01 20:15:01 UTC
t.utc? #=> true
t.localtime #=> 2000-01-01 14:15:01 -0600
t.utc? #=> false
t.localtime("+09:00") #=> 2000-01-02 05:15:01 +0900
t.utc? #=> false
3480 3481 3482 3483 3484 3485 3486 3487 3488 3489 3490 3491 3492 3493 3494 3495 |
# File 'time.c', line 3480
static VALUE
time_localtime_m(int argc, VALUE *argv, VALUE time)
{
VALUE off;
rb_scan_args(argc, argv, "01", &off);
if (!NIL_P(off)) {
off = utc_offset_arg(off);
validate_utc_offset(off);
time_set_utc_offset(time, off);
return time_fixoff(time);
}
return time_localtime(time);
}
|
#marshal_dump ⇒ Object (private)
:nodoc:
4608 4609 4610 4611 4612 4613 4614 4615 4616 4617 4618 4619 4620 4621 4622 4623 4624 4625 4626 4627 4628 4629 4630 4631 4632 4633 4634 4635 4636 4637 4638 4639 4640 4641 4642 4643 4644 4645 4646 4647 4648 4649 4650 4651 4652 4653 4654 4655 4656 4657 4658 4659 4660 4661 4662 4663 4664 4665 4666 4667 4668 4669 4670 4671 4672 4673 4674 4675 4676 4677 4678 4679 4680 4681 4682 4683 4684 4685 4686 4687 4688 4689 4690 4691 4692 4693 4694 4695 4696 4697 4698 4699 4700 4701 4702 4703 4704 4705 4706 |
# File 'time.c', line 4608
static VALUE
time_mdump(VALUE time)
{
struct time_object *tobj;
unsigned long p, s;
char buf[8];
int i;
VALUE str;
struct vtm vtm;
long year;
long usec, nsec;
VALUE subsecx, nano, subnano, v;
GetTimeval(time, tobj);
gmtimew(tobj->timew, &vtm);
if (FIXNUM_P(vtm.year)) {
year = FIX2LONG(vtm.year);
if (year < 1900 || 1900+0xffff < year)
rb_raise(rb_eArgError, "year too big to marshal: %ld UTC", year);
}
else {
rb_raise(rb_eArgError, "year too big to marshal");
}
subsecx = vtm.subsecx;
nano = mulquo(subsecx, INT2FIX(1000000000), INT2FIX(TIME_SCALE));
divmodv(nano, INT2FIX(1), &v, &subnano);
nsec = FIX2LONG(v);
usec = nsec / 1000;
nsec = nsec % 1000;
nano = add(LONG2FIX(nsec), subnano);
p = 0x1UL << 31 | /* 1 */
TIME_UTC_P(tobj) << 30 | /* 1 */
(year-1900) << 14 | /* 16 */
(vtm.mon-1) << 10 | /* 4 */
vtm.mday << 5 | /* 5 */
vtm.hour; /* 5 */
s = (unsigned long)vtm.min << 26 | /* 6 */
vtm.sec << 20 | /* 6 */
usec; /* 20 */
for (i=0; i<4; i++) {
buf[i] = (unsigned char)p;
p = RSHIFT(p, 8);
}
for (i=4; i<8; i++) {
buf[i] = (unsigned char)s;
s = RSHIFT(s, 8);
}
str = rb_str_new(buf, 8);
rb_copy_generic_ivar(str, time);
if (!rb_equal(nano, INT2FIX(0))) {
if (RB_TYPE_P(nano, T_RATIONAL)) {
rb_ivar_set(str, id_nano_num, RRATIONAL(nano)->num);
rb_ivar_set(str, id_nano_den, RRATIONAL(nano)->den);
}
else {
rb_ivar_set(str, id_nano_num, nano);
rb_ivar_set(str, id_nano_den, INT2FIX(1));
}
}
if (nsec) { /* submicro is only for Ruby 1.9.1 compatibility */
/*
* submicro is formatted in fixed-point packed BCD (without sign).
* It represent digits under microsecond.
* For nanosecond resolution, 3 digits (2 bytes) are used.
* However it can be longer.
* Extra digits are ignored for loading.
*/
char buf[2];
int len = (int)sizeof(buf);
buf[1] = (char)((nsec % 10) << 4);
nsec /= 10;
buf[0] = (char)(nsec % 10);
nsec /= 10;
buf[0] |= (char)((nsec % 10) << 4);
if (buf[1] == 0)
len = 1;
rb_ivar_set(str, id_submicro, rb_str_new(buf, len));
}
if (!TIME_UTC_P(tobj)) {
VALUE off = time_utc_offset(time), div, mod;
divmodv(off, INT2FIX(1), &div, &mod);
if (rb_equal(mod, INT2FIX(0)))
off = rb_Integer(div);
rb_ivar_set(str, id_offset, off);
}
if (tobj->vtm.zone) {
rb_ivar_set(str, id_zone, time_zone_name(tobj->vtm.zone));
}
return str;
}
|
#marshal_load(str) ⇒ Object (private)
:nodoc:
4721 4722 4723 4724 4725 4726 4727 4728 4729 4730 4731 4732 4733 4734 4735 4736 4737 4738 4739 4740 4741 4742 4743 4744 4745 4746 4747 4748 4749 4750 4751 4752 4753 4754 4755 4756 4757 4758 4759 4760 4761 4762 4763 4764 4765 4766 4767 4768 4769 4770 4771 4772 4773 4774 4775 4776 4777 4778 4779 4780 4781 4782 4783 4784 4785 4786 4787 4788 4789 4790 4791 4792 4793 4794 4795 4796 4797 4798 4799 4800 4801 4802 4803 4804 4805 4806 4807 4808 4809 4810 4811 4812 4813 4814 4815 4816 4817 4818 4819 4820 4821 4822 4823 4824 4825 4826 4827 4828 4829 4830 4831 4832 4833 4834 4835 4836 4837 4838 4839 4840 4841 4842 4843 |
# File 'time.c', line 4721
static VALUE
time_mload(VALUE time, VALUE str)
{
struct time_object *tobj;
unsigned long p, s;
time_t sec;
long usec;
unsigned char *buf;
struct vtm vtm;
int i, gmt;
long nsec;
VALUE submicro, nano_num, nano_den, offset, zone;
wideval_t timew;
st_data_t data;
time_modify(time);
#define get_attr(attr, iffound) \
attr = rb_attr_get(str, id_##attr); \
if (!NIL_P(attr)) { \
data = id_##attr; \
iffound; \
st_delete(rb_generic_ivar_table(str), &data, 0); \
}
get_attr(nano_num, {});
get_attr(nano_den, {});
get_attr(submicro, {});
get_attr(offset, (offset = rb_rescue(validate_utc_offset, offset, NULL, Qnil)));
get_attr(zone, (zone = rb_rescue(validate_zone_name, zone, NULL, Qnil)));
#undef get_attr
rb_copy_generic_ivar(time, str);
StringValue(str);
buf = (unsigned char *)RSTRING_PTR(str);
if (RSTRING_LEN(str) != 8) {
rb_raise(rb_eTypeError, "marshaled time format differ");
}
p = s = 0;
for (i=0; i<4; i++) {
p |= (unsigned long)buf[i]<<(8*i);
}
for (i=4; i<8; i++) {
s |= (unsigned long)buf[i]<<(8*(i-4));
}
if ((p & (1UL<<31)) == 0) {
gmt = 0;
offset = Qnil;
sec = p;
usec = s;
nsec = usec * 1000;
timew = wadd(rb_time_magnify(TIMET2WV(sec)), wmulquoll(WINT2FIXWV(usec), TIME_SCALE, 1000000));
}
else {
p &= ~(1UL<<31);
gmt = (int)((p >> 30) & 0x1);
vtm.year = INT2FIX(((int)(p >> 14) & 0xffff) + 1900);
vtm.mon = ((int)(p >> 10) & 0xf) + 1;
vtm.mday = (int)(p >> 5) & 0x1f;
vtm.hour = (int) p & 0x1f;
vtm.min = (int)(s >> 26) & 0x3f;
vtm.sec = (int)(s >> 20) & 0x3f;
vtm.utc_offset = INT2FIX(0);
vtm.yday = vtm.wday = 0;
vtm.isdst = 0;
vtm.zone = "";
usec = (long)(s & 0xfffff);
nsec = usec * 1000;
vtm.subsecx = mulquo(LONG2FIX(nsec), INT2FIX(TIME_SCALE), LONG2FIX(1000000000));
if (nano_num != Qnil) {
VALUE nano = quo(num_exact(nano_num), num_exact(nano_den));
vtm.subsecx = add(vtm.subsecx, mulquo(nano, INT2FIX(TIME_SCALE), LONG2FIX(1000000000)));
}
else if (submicro != Qnil) { /* for Ruby 1.9.1 compatibility */
unsigned char *ptr;
long len;
int digit;
ptr = (unsigned char*)StringValuePtr(submicro);
len = RSTRING_LEN(submicro);
nsec = 0;
if (0 < len) {
if (10 <= (digit = ptr[0] >> 4)) goto end_submicro;
nsec += digit * 100;
if (10 <= (digit = ptr[0] & 0xf)) goto end_submicro;
nsec += digit * 10;
}
if (1 < len) {
if (10 <= (digit = ptr[1] >> 4)) goto end_submicro;
nsec += digit;
}
vtm.subsecx = add(vtm.subsecx, mulquo(LONG2FIX(nsec), INT2FIX(TIME_SCALE), LONG2FIX(1000000000)));
end_submicro: ;
}
timew = timegmw(&vtm);
}
GetNewTimeval(time, tobj);
tobj->gmt = 0;
tobj->tm_got = 0;
tobj->timew = timew;
if (gmt) {
TIME_SET_UTC(tobj);
}
else if (!NIL_P(offset)) {
time_set_utc_offset(time, offset);
time_fixoff(time);
}
if (!NIL_P(zone)) {
zone = rb_str_new_frozen(zone);
tobj->vtm.zone = StringValueCStr(zone);
rb_ivar_set(time, id_zone, zone);
}
return time;
}
|
#day ⇒ Fixnum #mday ⇒ Fixnum
3940 3941 3942 3943 3944 3945 3946 3947 3948 |
# File 'time.c', line 3940
static VALUE
time_mday(VALUE time)
{
struct time_object *tobj;
GetTimeval(time, tobj);
MAKE_TM(time, tobj);
return INT2FIX(tobj->vtm.mday);
}
|
#min ⇒ Fixnum
3898 3899 3900 3901 3902 3903 3904 3905 3906 |
# File 'time.c', line 3898
static VALUE
time_min(VALUE time)
{
struct time_object *tobj;
GetTimeval(time, tobj);
MAKE_TM(time, tobj);
return INT2FIX(tobj->vtm.min);
}
|
#mon ⇒ Fixnum #month ⇒ Fixnum
3962 3963 3964 3965 3966 3967 3968 3969 3970 |
# File 'time.c', line 3962
static VALUE
time_mon(VALUE time)
{
struct time_object *tobj;
GetTimeval(time, tobj);
MAKE_TM(time, tobj);
return INT2FIX(tobj->vtm.mon);
}
|
#monday? ⇒ Boolean
4053 4054 4055 4056 4057 |
# File 'time.c', line 4053
static VALUE
time_monday(VALUE time)
{
wday_p(1);
}
|
#mon ⇒ Fixnum #month ⇒ Fixnum
3962 3963 3964 3965 3966 3967 3968 3969 3970 |
# File 'time.c', line 3962
static VALUE
time_mon(VALUE time)
{
struct time_object *tobj;
GetTimeval(time, tobj);
MAKE_TM(time, tobj);
return INT2FIX(tobj->vtm.mon);
}
|
#nsec ⇒ Integer #tv_nsec ⇒ Integer
Returns the number of nanoseconds for time.
t = Time.now #=> 2007-11-17 15:18:03 +0900
"%10.9f" % t.to_f #=> "1195280283.536151409"
t.nsec #=> 536151406
The lowest digits of #to_f and #nsec are different because IEEE 754 double is not accurate enough to represent the exact number of nanoseconds since the Epoch.
The more accurate value is returned by #nsec.
3266 3267 3268 3269 3270 3271 3272 3273 |
# File 'time.c', line 3266
static VALUE
time_nsec(VALUE time)
{
struct time_object *tobj;
GetTimeval(time, tobj);
return rb_to_int(w2v(wmulquoll(wmod(tobj->timew, WINT2WV(TIME_SCALE)), 1000000000, TIME_SCALE)));
}
|
#round([ndigits]) ⇒ Time
Rounds sub seconds to a given precision in decimal digits (0 digits by default). It returns a new Time object. ndigits
should be zero or positive integer.
require 'time'
t = Time.utc(2010,3,30, 5,43,"25.123456789".to_r)
p t.iso8601(10) #=> "2010-03-30T05:43:25.1234567890Z"
p t.round.iso8601(10) #=> "2010-03-30T05:43:25.0000000000Z"
p t.round(0).iso8601(10) #=> "2010-03-30T05:43:25.0000000000Z"
p t.round(1).iso8601(10) #=> "2010-03-30T05:43:25.1000000000Z"
p t.round(2).iso8601(10) #=> "2010-03-30T05:43:25.1200000000Z"
p t.round(3).iso8601(10) #=> "2010-03-30T05:43:25.1230000000Z"
p t.round(4).iso8601(10) #=> "2010-03-30T05:43:25.1235000000Z"
p t.round(5).iso8601(10) #=> "2010-03-30T05:43:25.1234600000Z"
p t.round(6).iso8601(10) #=> "2010-03-30T05:43:25.1234570000Z"
p t.round(7).iso8601(10) #=> "2010-03-30T05:43:25.1234568000Z"
p t.round(8).iso8601(10) #=> "2010-03-30T05:43:25.1234567900Z"
p t.round(9).iso8601(10) #=> "2010-03-30T05:43:25.1234567890Z"
p t.round(10).iso8601(10) #=> "2010-03-30T05:43:25.1234567890Z"
t = Time.utc(1999,12,31, 23,59,59)
p((t + 0.4).round.iso8601(3)) #=> "1999-12-31T23:59:59.000Z"
p((t + 0.49).round.iso8601(3)) #=> "1999-12-31T23:59:59.000Z"
p((t + 0.5).round.iso8601(3)) #=> "2000-01-01T00:00:00.000Z"
p((t + 1.4).round.iso8601(3)) #=> "2000-01-01T00:00:00.000Z"
p((t + 1.49).round.iso8601(3)) #=> "2000-01-01T00:00:00.000Z"
p((t + 1.5).round.iso8601(3)) #=> "2000-01-01T00:00:01.000Z"
t = Time.utc(1999,12,31, 23,59,59)
p (t + 0.123456789).round(4).iso8601(6) #=> "1999-12-31T23:59:59.123500Z"
3827 3828 3829 3830 3831 3832 3833 3834 3835 3836 3837 3838 3839 3840 3841 3842 3843 3844 3845 3846 3847 3848 3849 3850 3851 3852 3853 3854 3855 3856 3857 3858 3859 3860 3861 3862 |
# File 'time.c', line 3827
static VALUE
time_round(int argc, VALUE *argv, VALUE time)
{
VALUE ndigits, v, a, b, den;
long nd;
struct time_object *tobj;
rb_scan_args(argc, argv, "01", &ndigits);
if (NIL_P(ndigits))
ndigits = INT2FIX(0);
else
ndigits = rb_to_int(ndigits);
nd = NUM2LONG(ndigits);
if (nd < 0)
rb_raise(rb_eArgError, "negative ndigits given");
GetTimeval(time, tobj);
v = w2v(rb_time_unmagnify(tobj->timew));
a = INT2FIX(1);
b = INT2FIX(10);
while (0 < nd) {
if (nd & 1)
a = mul(a, b);
b = mul(b, b);
nd = nd >> 1;
}
den = quo(INT2FIX(1), a);
v = mod(v, den);
if (lt(v, quo(den, INT2FIX(2))))
return time_add(tobj, v, -1);
else
return time_add(tobj, sub(den, v), 1);
}
|
#saturday? ⇒ Boolean
4133 4134 4135 4136 4137 |
# File 'time.c', line 4133
static VALUE
time_saturday(VALUE time)
{
wday_p(6);
}
|
#sec ⇒ Fixnum
Returns the second of the minute (0..60) for time.
Note: Seconds range from zero to 60 to allow the system to inject leap seconds. See en.wikipedia.org/wiki/Leap_second for further details.
t = Time.now #=> 2007-11-19 08:25:02 -0600
t.sec #=> 2
3878 3879 3880 3881 3882 3883 3884 3885 3886 |
# File 'time.c', line 3878
static VALUE
time_sec(VALUE time)
{
struct time_object *tobj;
GetTimeval(time, tobj);
MAKE_TM(time, tobj);
return INT2FIX(tobj->vtm.sec);
}
|
#strftime(string) ⇒ String
Formats time 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.
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
_ 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 if provided, will pad result at least 4 digits.
-0001, 0000, 1995, 2009, 14292, etc.
%C - year / 100 (rounded down such as 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)
The digits under millisecond are truncated to not produce 1000.
%N - Fractional seconds digits, default is 9 digits (nanosecond)
%3N millisecond (3 digits)
%6N microsecond (6 digits)
%9N nanosecond (9 digits)
%12N picosecond (12 digits)
%15N femtosecond (15 digits)
%18N attosecond (18 digits)
%21N zeptosecond (21 digits)
%24N yoctosecond (24 digits)
The digits under the specified length are truncated to avoid
carry up.
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 - Abbreviated time zone name or similar information. (OS dependent)
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 first week 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 first week of YYYY that 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 Epoch:
%s - Number of seconds 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-%4Y)
%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)
This method is similar to strftime() function defined in ISO C and POSIX.
While all directives are locale independent since Ruby 1.9, %Z is platform dependent. So, the result may differ even if the same format string is used in other systems such as C.
%z is recommended over %Z. %Z doesn’t identify the timezone. For example, “CST” is used at America/Chicago (-06:00), America/Havana (-05:00), Asia/Harbin (+08:00), Australia/Darwin (+09:30) and Australia/Adelaide (+10:30). Also, %Z is highly dependent on the operating system. For example, it may generate a non ASCII string on Japanese Windows. i.e. the result can be different to “JST”. So the numeric time zone offset, %z, is recommended.
Examples:
t = Time.new(2007,11,19,8,37,48,"-06:00") #=> 2007-11-19 08:37:48 -0600
t.strftime("Printed on %m/%d/%Y") #=> "Printed on 11/19/2007"
t.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)
4556 4557 4558 4559 4560 4561 4562 4563 4564 4565 4566 4567 4568 4569 4570 4571 4572 4573 4574 4575 4576 4577 4578 4579 4580 4581 4582 4583 4584 4585 4586 4587 4588 4589 4590 4591 4592 4593 4594 4595 4596 4597 4598 4599 4600 4601 4602 4603 4604 4605 |
# File 'time.c', line 4556
static VALUE
time_strftime(VALUE time, VALUE format)
{
struct time_object *tobj;
char buffer[SMALLBUF], *buf = buffer;
const char *fmt;
long len;
rb_encoding *enc;
VALUE str;
GetTimeval(time, tobj);
MAKE_TM(time, tobj);
StringValue(format);
if (!rb_enc_str_asciicompat_p(format)) {
rb_raise(rb_eArgError, "format should have ASCII compatible encoding");
}
format = rb_str_new4(format);
fmt = RSTRING_PTR(format);
len = RSTRING_LEN(format);
enc = rb_enc_get(format);
if (len == 0) {
rb_warning("strftime called with empty format string");
}
else if (fmt[len] || memchr(fmt, '\0', len)) {
/* Ruby string may contain \0's. */
const char *p = fmt, *pe = fmt + len;
str = rb_str_new(0, 0);
while (p < pe) {
len = rb_strftime_alloc(&buf, format, p, enc,
&tobj->vtm, tobj->timew, TIME_UTC_P(tobj));
rb_str_cat(str, buf, len);
p += strlen(p);
if (buf != buffer) {
xfree(buf);
buf = buffer;
}
for (fmt = p; p < pe && !*p; ++p);
if (p > fmt) rb_str_cat(str, fmt, p - fmt);
}
return str;
}
else {
len = rb_strftime_alloc(&buf, format, RSTRING_PTR(format), enc,
&tobj->vtm, tobj->timew, TIME_UTC_P(tobj));
}
str = rb_enc_str_new(buf, len, enc);
if (buf != buffer) xfree(buf);
return str;
}
|
#subsec ⇒ Numeric
Returns the fraction for time.
The return value can be a rational number.
t = Time.now #=> 2009-03-26 22:33:12 +0900
"%10.9f" % t.to_f #=> "1238074392.940563917"
t.subsec #=> (94056401/100000000)
The lowest digits of #to_f and #subsec are different because IEEE 754 double is not accurate enough to represent the rational number.
The more accurate value is returned by #subsec.
3294 3295 3296 3297 3298 3299 3300 3301 |
# File 'time.c', line 3294
static VALUE
time_subsec(VALUE time)
{
struct time_object *tobj;
GetTimeval(time, tobj);
return quo(w2v(wmod(tobj->timew, WINT2FIXWV(TIME_SCALE))), INT2FIX(TIME_SCALE));
}
|
#succ ⇒ Object
#sunday? ⇒ Boolean
4037 4038 4039 4040 4041 |
# File 'time.c', line 4037
static VALUE
time_sunday(VALUE time)
{
wday_p(0);
}
|
#thursday? ⇒ Boolean
4101 4102 4103 4104 4105 |
# File 'time.c', line 4101
static VALUE
time_thursday(VALUE time)
{
wday_p(4);
}
|
#to_a ⇒ Array
Returns a ten-element array of values for time:
[sec, min, hour, day, month, year, wday, yday, isdst, zone]
See the individual methods for an explanation of the valid ranges of each value. The ten elements can be passed directly to Time::utc or Time::local to create a new Time object.
t = Time.now #=> 2007-11-19 08:36:01 -0600
now = t.to_a #=> [1, 36, 8, 19, 11, 2007, 1, 323, false, "CST"]
4285 4286 4287 4288 4289 4290 4291 4292 4293 4294 4295 4296 4297 4298 4299 4300 4301 4302 4303 |
# File 'time.c', line 4285
static VALUE
time_to_a(VALUE time)
{
struct time_object *tobj;
GetTimeval(time, tobj);
MAKE_TM(time, tobj);
return rb_ary_new3(10,
INT2FIX(tobj->vtm.sec),
INT2FIX(tobj->vtm.min),
INT2FIX(tobj->vtm.hour),
INT2FIX(tobj->vtm.mday),
INT2FIX(tobj->vtm.mon),
tobj->vtm.year,
INT2FIX(tobj->vtm.wday),
INT2FIX(tobj->vtm.yday),
tobj->vtm.isdst?Qtrue:Qfalse,
time_zone(time));
}
|
#to_f ⇒ Float
3185 3186 3187 3188 3189 3190 3191 3192 |
# File 'time.c', line 3185
static VALUE
time_to_f(VALUE time)
{
struct time_object *tobj;
GetTimeval(time, tobj);
return rb_Float(rb_time_unmagnify_to_float(tobj->timew));
}
|
#to_i ⇒ Integer #tv_sec ⇒ Integer
3161 3162 3163 3164 3165 3166 3167 3168 |
# File 'time.c', line 3161
static VALUE
time_to_i(VALUE time)
{
struct time_object *tobj;
GetTimeval(time, tobj);
return w2v(wdiv(tobj->timew, WINT2FIXWV(TIME_SCALE)));
}
|
#to_r ⇒ Object
3209 3210 3211 3212 3213 3214 3215 3216 3217 3218 3219 3220 3221 |
# File 'time.c', line 3209
static VALUE
time_to_r(VALUE time)
{
struct time_object *tobj;
VALUE v;
GetTimeval(time, tobj);
v = w2v(rb_time_unmagnify(tobj->timew));
if (!RB_TYPE_P(v, T_RATIONAL)) {
v = rb_Rational1(v);
}
return v;
}
|
#inspect ⇒ String #to_s ⇒ String
Returns a string representing time. Equivalent to calling #strftime with the appropriate format string.
t = Time.now
t.to_s => "2012-11-10 18:16:12 +0100"
t.strftime "%Y-%m-%d %H:%M:%S %z" => "2012-11-10 18:16:12 +0100"
t.utc.to_s => "2012-11-10 17:16:12 UTC"
t.strftime "%Y-%m-%d %H:%M:%S UTC" => "2012-11-10 17:16:12 UTC"
3673 3674 3675 3676 3677 3678 3679 3680 3681 3682 3683 |
# File 'time.c', line 3673
static VALUE
time_to_s(VALUE time)
{
struct time_object *tobj;
GetTimeval(time, tobj);
if (TIME_UTC_P(tobj))
return strftimev("%Y-%m-%d %H:%M:%S UTC", time, rb_usascii_encoding());
else
return strftimev("%Y-%m-%d %H:%M:%S %z", time, rb_usascii_encoding());
}
|
#tuesday? ⇒ Boolean
4069 4070 4071 4072 4073 |
# File 'time.c', line 4069
static VALUE
time_tuesday(VALUE time)
{
wday_p(2);
}
|
#nsec ⇒ Integer #tv_nsec ⇒ Integer
Returns the number of nanoseconds for time.
t = Time.now #=> 2007-11-17 15:18:03 +0900
"%10.9f" % t.to_f #=> "1195280283.536151409"
t.nsec #=> 536151406
The lowest digits of #to_f and #nsec are different because IEEE 754 double is not accurate enough to represent the exact number of nanoseconds since the Epoch.
The more accurate value is returned by #nsec.
3266 3267 3268 3269 3270 3271 3272 3273 |
# File 'time.c', line 3266
static VALUE
time_nsec(VALUE time)
{
struct time_object *tobj;
GetTimeval(time, tobj);
return rb_to_int(w2v(wmulquoll(wmod(tobj->timew, WINT2WV(TIME_SCALE)), 1000000000, TIME_SCALE)));
}
|
#to_i ⇒ Integer #tv_sec ⇒ Integer
3161 3162 3163 3164 3165 3166 3167 3168 |
# File 'time.c', line 3161
static VALUE
time_to_i(VALUE time)
{
struct time_object *tobj;
GetTimeval(time, tobj);
return w2v(wdiv(tobj->timew, WINT2FIXWV(TIME_SCALE)));
}
|
#usec ⇒ Integer #tv_usec ⇒ Integer
3235 3236 3237 3238 3239 3240 3241 3242 3243 3244 3245 3246 |
# File 'time.c', line 3235
static VALUE
time_usec(VALUE time)
{
struct time_object *tobj;
wideval_t w, q, r;
GetTimeval(time, tobj);
w = wmod(tobj->timew, WINT2WV(TIME_SCALE));
wmuldivmod(w, WINT2FIXWV(1000000), WINT2FIXWV(TIME_SCALE), &q, &r);
return rb_to_int(w2v(q));
}
|
#usec ⇒ Integer #tv_usec ⇒ Integer
3235 3236 3237 3238 3239 3240 3241 3242 3243 3244 3245 3246 |
# File 'time.c', line 3235
static VALUE
time_usec(VALUE time)
{
struct time_object *tobj;
wideval_t w, q, r;
GetTimeval(time, tobj);
w = wmod(tobj->timew, WINT2WV(TIME_SCALE));
wmuldivmod(w, WINT2FIXWV(1000000), WINT2FIXWV(TIME_SCALE), &q, &r);
return rb_to_int(w2v(q));
}
|
#gmtime ⇒ Time #utc ⇒ Time
3515 3516 3517 3518 3519 3520 3521 3522 3523 3524 3525 3526 3527 3528 3529 3530 3531 3532 3533 3534 3535 3536 3537 |
# File 'time.c', line 3515
static VALUE
time_gmtime(VALUE time)
{
struct time_object *tobj;
struct vtm vtm;
GetTimeval(time, tobj);
if (TIME_UTC_P(tobj)) {
if (tobj->tm_got)
return time;
}
else {
time_modify(time);
}
if (!gmtimew(tobj->timew, &vtm))
rb_raise(rb_eArgError, "gmtime error");
tobj->vtm = vtm;
tobj->tm_got = 1;
TIME_SET_UTC(tobj);
return time;
}
|
#utc? ⇒ Boolean #gmt? ⇒ Boolean
Returns true
if time represents a time in UTC (GMT).
t = Time.now #=> 2007-11-19 08:15:23 -0600
t.utc? #=> false
t = Time.gm(2000,"jan",1,20,15,1) #=> 2000-01-01 20:15:01 UTC
t.utc? #=> true
t = Time.now #=> 2007-11-19 08:16:03 -0600
t.gmt? #=> false
t = Time.gm(2000,1,1,20,15,1) #=> 2000-01-01 20:15:01 UTC
t.gmt? #=> true
3386 3387 3388 3389 3390 3391 3392 3393 3394 |
# File 'time.c', line 3386
static VALUE
time_utc_p(VALUE time)
{
struct time_object *tobj;
GetTimeval(time, tobj);
if (TIME_UTC_P(tobj)) return Qtrue;
return Qfalse;
}
|
#gmt_offset ⇒ Fixnum #gmtoff ⇒ Fixnum #utc_offset ⇒ Fixnum
4252 4253 4254 4255 4256 4257 4258 4259 4260 4261 4262 4263 4264 4265 4266 |
# File 'time.c', line 4252
static VALUE
time_utc_offset(VALUE time)
{
struct time_object *tobj;
GetTimeval(time, tobj);
MAKE_TM(time, tobj);
if (TIME_UTC_P(tobj)) {
return INT2FIX(0);
}
else {
return tobj->vtm.utc_offset;
}
}
|
#wday ⇒ Fixnum
4010 4011 4012 4013 4014 4015 4016 4017 4018 |
# File 'time.c', line 4010
static VALUE
time_wday(VALUE time)
{
struct time_object *tobj;
GetTimeval(time, tobj);
MAKE_TM(time, tobj);
return INT2FIX((int)tobj->vtm.wday);
}
|
#wednesday? ⇒ Boolean
4085 4086 4087 4088 4089 |
# File 'time.c', line 4085
static VALUE
time_wednesday(VALUE time)
{
wday_p(3);
}
|
#yday ⇒ Fixnum
4149 4150 4151 4152 4153 4154 4155 4156 4157 |
# File 'time.c', line 4149
static VALUE
time_yday(VALUE time)
{
struct time_object *tobj;
GetTimeval(time, tobj);
MAKE_TM(time, tobj);
return INT2FIX(tobj->vtm.yday);
}
|
#year ⇒ Fixnum
3982 3983 3984 3985 3986 3987 3988 3989 3990 |
# File 'time.c', line 3982
static VALUE
time_year(VALUE time)
{
struct time_object *tobj;
GetTimeval(time, tobj);
MAKE_TM(time, tobj);
return tobj->vtm.year;
}
|
#zone ⇒ String
4220 4221 4222 4223 4224 4225 4226 4227 4228 4229 4230 4231 4232 4233 4234 4235 |
# File 'time.c', line 4220
static VALUE
time_zone(VALUE time)
{
struct time_object *tobj;
GetTimeval(time, tobj);
MAKE_TM(time, tobj);
if (TIME_UTC_P(tobj)) {
return rb_usascii_str_new_cstr("UTC");
}
if (tobj->vtm.zone == NULL)
return Qnil;
return time_zone_name(tobj->vtm.zone);
}
|