kotovalexarian-likes-github/ruby--ruby
1
0
Fork 0
mirror of https://github.com/ruby/ruby.git synced 2022-11-09 12:17:21 -05:00
Code Releases Activity

* time.c: Documentation improvements, grammar and formatting

Browse source 
Patch by Bernd Homuth [ruby-core:49203] [Bug #7326]


git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@38032 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
This commit is contained in:
zzak 2012-11-30 04:53:09 +00:00
parent 24c0d0764b
commit 088b04e8a4
2 changed files with 162 additions and 149 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

5
ChangeLog
View file

@ -1,3 +1,8 @@
Fri Nov 30 13:52:00 2012 Zachary Scott <zachary@zacharyscott.net>
* time.c: Documentation improvements, grammar and formatting
Patch by Bernd Homuth [ruby-core:49203] [Bug #7326]
Fri Nov 30 13:48:33 2012 Eric Hodel <drbrain@segment7.net> Fri Nov 30 13:48:33 2012 Eric Hodel <drbrain@segment7.net>
* lib/rdoc.rb: Set version to 4.0.0.preview2 * lib/rdoc.rb: Set version to 4.0.0.preview2

306
time.c
View file

@ -1399,12 +1399,12 @@ gmtimew(wideval_t timew, struct vtm *result)
static struct tm *localtime_with_gmtoff_zone(const time_t *t, struct tm *result, long *gmtoff, const char **zone); static struct tm *localtime_with_gmtoff_zone(const time_t *t, struct tm *result, long *gmtoff, const char **zone);
/* /*
* The idea is come from Perl: * The idea is borrowed from Perl:
* http://use.perl.org/articles/08/02/07/197204.shtml * http://use.perl.org/articles/08/02/07/197204.shtml
* *
* compat_common_month_table is generated by following program. * compat_common_month_table is generated by the following program.
* This table finds the last month which start the same day of a week. * This table finds the last month which starts at the same day of a week.
* The year 2037 is not used because * The year 2037 is not used because:
* http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=522949 * http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=522949
* *
* #!/usr/bin/ruby * #!/usr/bin/ruby
@ -1502,8 +1502,8 @@ guess_local_offset(struct vtm *vtm_utc, int *isdst_ret, const char **zone_ret)
VALUE timev; VALUE timev;
int y, wday; int y, wday;
/* The first DST is at 1916 in German. /* Daylight Saving Time was introduced in 1916.
* So we don't need to care DST before that. */ * So we don't need to care about DST before that. */
if (lt(vtm_utc->year, INT2FIX(1916))) { if (lt(vtm_utc->year, INT2FIX(1916))) {
VALUE off = INT2FIX(0); VALUE off = INT2FIX(0);
int isdst = 0; int isdst = 0;
@ -1537,7 +1537,7 @@ guess_local_offset(struct vtm *vtm_utc, int *isdst_ret, const char **zone_ret)
return off; return off;
} }
/* It is difficult to guess future. */ /* It is difficult to guess the future. */
vtm2 = *vtm_utc; vtm2 = *vtm_utc;
@ -1943,7 +1943,7 @@ timew2timespec_exact(wideval_t timew, struct timespec *ts)
/* /*
* Document-method: now * Document-method: now
* *
* Synonym for <code>Time.new</code>. Returns a +Time+ object * Alias for Time::new. Returns a Time object
* initialized to the current system time. * initialized to the current system time.
*/ */
@ -2220,19 +2220,20 @@ time_init_1(int argc, VALUE *argv, VALUE time)
* Time.new -> time * Time.new -> time
* Time.new(year, month=nil, day=nil, hour=nil, min=nil, sec=nil, utc_offset=nil) -> time * Time.new(year, month=nil, day=nil, hour=nil, min=nil, sec=nil, utc_offset=nil) -> time
* *
* Returns a <code>Time</code> object. * Returns a Time object.
* *
* It is initialized to the current system time if no argument. * It is initialized to the current system time if no argument is given.
* <b>Note:</b> The object created will be created using the
* resolution available on your system clock, and so may include
* fractional seconds.
* *
* If one or more arguments specified, the time is initialized * *Note:* The new object will use the resolution available on your
* to the specified time. * system clock, and may include fractional seconds.
* _sec_ may have fraction if it is a rational.
* *
* _utc_offset_ is the offset from UTC. * If one or more arguments specified, the time is initialized to the specified
* It is a string such as "+09:00" or a number of seconds such as 32400. * 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 * a = Time.new #=> 2007-11-19 07:50:02 -0600
* b = Time.new #=> 2007-11-19 07:50:02 -0600 * b = Time.new #=> 2007-11-19 07:50:02 -0600
@ -2488,7 +2489,7 @@ rb_time_timespec(VALUE time)
* call-seq: * call-seq:
* Time.now -> time * Time.now -> time
* *
* Creates a new time object for the current time. * Creates a new Time object for the current time.
* *
* Time.now #=> 2009-06-24 12:39:54 +0900 * Time.now #=> 2009-06-24 12:39:54 +0900
*/ */
@ -2505,21 +2506,21 @@ time_s_now(VALUE klass)
* Time.at(seconds_with_frac) -> time * Time.at(seconds_with_frac) -> time
* Time.at(seconds, microseconds_with_frac) -> time * Time.at(seconds, microseconds_with_frac) -> time
* *
* Creates a new time object with the value given by <i>time</i>, * Creates a new Time object with the value given by +time+,
* the given number of <i>seconds_with_frac</i>, or * the given number of +seconds_with_frac+, or
* <i>seconds</i> and <i>microseconds_with_frac</i> from the Epoch. * +seconds+ and +microseconds_with_frac+ since the Epoch.
* <i>seconds_with_frac</i> and <i>microseconds_with_frac</i> * +seconds_with_frac+ and +microseconds_with_frac+
* can be Integer, Float, Rational, or other Numeric. * can be an Integer, Float, Rational, or other Numeric.
* non-portable feature allows the offset to be negative on some systems. * non-portable feature allows the offset to be negative on some systems.
* *
* If a numeric argument is given, the result is in local time. * If a numeric argument is given, the result is in local time.
* *
* Time.at(0) #=> 1969-12-31 18:00:00 -0600 * Time.at(0) #=> 1969-12-31 18:00:00 -0600
* Time.at(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(946702800) #=> 1999-12-31 23:00:00 -0600
* Time.at(-284061600) #=> 1960-12-31 00:00:00 -0600 * Time.at(-284061600) #=> 1960-12-31 00:00:00 -0600
* Time.at(946684800.2).usec #=> 200000 * Time.at(946684800.2).usec #=> 200000
* Time.at(946684800, 123456.789).nsec #=> 123456789 * Time.at(946684800, 123456.789).nsec #=> 123456789
*/ */
static VALUE static VALUE
@ -3118,15 +3119,15 @@ time_utc_or_local(int argc, VALUE *argv, int utc_p, VALUE klass)
* Time.gm(year, month, day, hour, min, sec, usec_with_frac) -> time * Time.gm(year, month, day, hour, min, sec, usec_with_frac) -> time
* Time.gm(sec, min, hour, day, month, year, wday, yday, isdst, tz) -> time * Time.gm(sec, min, hour, day, month, year, wday, yday, isdst, tz) -> time
* *
* Creates a time based on given values, interpreted as UTC (GMT). The * Creates a Time object based on given values, interpreted as UTC (GMT). The
* year must be specified. Other values default to the minimum value * year must be specified. Other values default to the minimum value
* for that field (and may be <code>nil</code> or omitted). Months may * 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 * 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 * month names. Hours are specified on a 24-hour clock (0..23). Raises
* an <code>ArgumentError</code> if any values are out of range. Will * an ArgumentError if any values are out of range. Will
* also accept ten arguments in the order output by * also accept ten arguments in the order output by Time#to_a.
* <code>Time#to_a</code>. *
* <i>sec_with_frac</i> and <i>usec_with_frac</i> can have a fractional part. * +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.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 * Time.gm(2000,"jan",1,20,15,1) #=> 2000-01-01 20:15:01 UTC
@ -3156,7 +3157,7 @@ time_s_mkutc(int argc, VALUE *argv, VALUE klass)
* Time.mktime(year, month, day, hour, min, sec, usec_with_frac) -> time * Time.mktime(year, month, day, hour, min, sec, usec_with_frac) -> time
* Time.mktime(sec, min, hour, day, month, year, wday, yday, isdst, tz) -> time * Time.mktime(sec, min, hour, day, month, year, wday, yday, isdst, tz) -> time
* *
* Same as <code>Time::gm</code>, but interprets the values in the * Same as Time::gm, but interprets the values in the
* local time zone. * local time zone.
* *
* Time.local(2000,"jan",1,20,15,1) #=> 2000-01-01 20:15:01 -0600 * Time.local(2000,"jan",1,20,15,1) #=> 2000-01-01 20:15:01 -0600
@ -3173,7 +3174,7 @@ time_s_mktime(int argc, VALUE *argv, VALUE klass)
* time.to_i -> int * time.to_i -> int
* time.tv_sec -> int * time.tv_sec -> int
* *
* Returns the value of <i>time</i> as an integer number of seconds * Returns the value of _time_ as an integer number of seconds
* since the Epoch. * since the Epoch.
* *
* t = Time.now * t = Time.now
@ -3194,7 +3195,7 @@ time_to_i(VALUE time)
* call-seq: * call-seq:
* time.to_f -> float * time.to_f -> float
* *
* Returns the value of <i>time</i> as a floating point number of * Returns the value of _time_ as a floating point number of
* seconds since the Epoch. * seconds since the Epoch.
* *
* t = Time.now * t = Time.now
@ -3202,7 +3203,7 @@ time_to_i(VALUE time)
* t.to_i #=> 1270968744 * t.to_i #=> 1270968744
* *
* Note that IEEE 754 double is not accurate enough to represent * Note that IEEE 754 double is not accurate enough to represent
* number of nanoseconds from the Epoch. * the number of nanoseconds since the Epoch.
*/ */
static VALUE static VALUE
@ -3218,15 +3219,15 @@ time_to_f(VALUE time)
* call-seq: * call-seq:
* time.to_r -> a_rational * time.to_r -> a_rational
* *
* Returns the value of <i>time</i> as a rational number of seconds * Returns the value of _time_ as a rational number of seconds
* since the Epoch. * since the Epoch.
* *
* t = Time.now * t = Time.now
* p t.to_r #=> (1270968792716287611/1000000000) * p t.to_r #=> (1270968792716287611/1000000000)
* *
* This methods is intended to be used to get an accurate value * This methods is intended to be used to get an accurate value
* representing nanoseconds from the Epoch. You can use this * representing the nanoseconds since the Epoch. You can use this method
* to convert time to another Epoch. * to convert _time_ to another Epoch.
*/ */
static VALUE static VALUE
@ -3248,7 +3249,7 @@ time_to_r(VALUE time)
* time.usec -> int * time.usec -> int
* time.tv_usec -> int * time.tv_usec -> int
* *
* Returns just the number of microseconds for <i>time</i>. * Returns the number of microseconds for _time_.
* *
* t = Time.now #=> 2007-11-19 08:03:26 -0600 * t = Time.now #=> 2007-11-19 08:03:26 -0600
* "%10.6f" % t.to_f #=> "1195481006.775195" * "%10.6f" % t.to_f #=> "1195481006.775195"
@ -3273,16 +3274,17 @@ time_usec(VALUE time)
* time.nsec -> int * time.nsec -> int
* time.tv_nsec -> int * time.tv_nsec -> int
* *
* Returns just the number of nanoseconds for <i>time</i>. * Returns the number of nanoseconds for _time_.
* *
* t = Time.now #=> 2007-11-17 15:18:03 +0900 * t = Time.now #=> 2007-11-17 15:18:03 +0900
* "%10.9f" % t.to_f #=> "1195280283.536151409" * "%10.9f" % t.to_f #=> "1195280283.536151409"
* t.nsec #=> 536151406 * t.nsec #=> 536151406
* *
* The lowest digit of to_f and nsec is different because * The lowest digits of #to_f and #nsec are different because
* IEEE 754 double is not accurate enough to represent * IEEE 754 double is not accurate enough to represent
* nanoseconds from the Epoch. * the exact number of nanoseconds since the Epoch.
* The accurate value is returned by nsec. *
* The more accurate value is returned by #nsec.
*/ */
static VALUE static VALUE
@ -3298,18 +3300,19 @@ time_nsec(VALUE time)
* call-seq: * call-seq:
* time.subsec -> number * time.subsec -> number
* *
* Returns just the fraction for <i>time</i>. * Returns the fraction for _time_.
* *
* The result is possibly rational. * The return value can be a rational number.
* *
* t = Time.now #=> 2009-03-26 22:33:12 +0900 * t = Time.now #=> 2009-03-26 22:33:12 +0900
* "%10.9f" % t.to_f #=> "1238074392.940563917" * "%10.9f" % t.to_f #=> "1238074392.940563917"
* t.subsec #=> (94056401/100000000) * t.subsec #=> (94056401/100000000)
* *
* The lowest digit of to_f and subsec is different because * The lowest digits of #to_f and #subsec are different because
* IEEE 754 double is not accurate enough to represent * IEEE 754 double is not accurate enough to represent
* the rational. * the rational number.
* The accurate value is returned by subsec. *
* The more accurate value is returned by #subsec.
*/ */
static VALUE static VALUE
@ -3325,7 +3328,10 @@ time_subsec(VALUE time)
* call-seq: * call-seq:
* time <=> other_time -> -1, 0, +1 or nil * time <=> other_time -> -1, 0, +1 or nil
* *
* Comparison---Compares <i>time</i> with <i>other_time</i>. * Comparison---Compares _time_ with +other_time+.
* The return value is ++1+ if _time_ is greater than
* +other_time+, +0+ if _time_ is equal to +other_time+ and
* +-1+ if _time_ is smaller than +other_time+.
* *
* t = Time.now #=> 2007-11-19 08:12:12 -0600 * t = Time.now #=> 2007-11-19 08:12:12 -0600
* t2 = t + 2592000 #=> 2007-12-19 08:12:12 -0600 * t2 = t + 2592000 #=> 2007-12-19 08:12:12 -0600
@ -3369,9 +3375,8 @@ time_cmp(VALUE time1, VALUE time2)
* call-seq: * call-seq:
* time.eql?(other_time) * time.eql?(other_time)
* *
* Return <code>true</code> if <i>time</i> and <i>other_time</i> are * Returns +true+ if _time_ and +other_time+ are
* both <code>Time</code> objects with the same seconds and fractional * both Time objects with the same seconds and fractional seconds.
* seconds.
*/ */
static VALUE static VALUE
@ -3392,8 +3397,7 @@ time_eql(VALUE time1, VALUE time2)
* time.utc? -> true or false * time.utc? -> true or false
* time.gmt? -> true or false * time.gmt? -> true or false
* *
* Returns <code>true</code> if <i>time</i> represents a time in UTC * Returns +true+ if _time_ represents a time in UTC (GMT).
* (GMT).
* *
* t = Time.now #=> 2007-11-19 08:15:23 -0600 * t = Time.now #=> 2007-11-19 08:15:23 -0600
* t.utc? #=> false * t.utc? #=> false
@ -3420,7 +3424,7 @@ time_utc_p(VALUE time)
* call-seq: * call-seq:
* time.hash -> fixnum * time.hash -> fixnum
* *
* Return a hash code for this time object. * Returns a hash code for this Time object.
*/ */
static VALUE static VALUE
@ -3483,10 +3487,10 @@ time_localtime(VALUE time)
* time.localtime -> time * time.localtime -> time
* time.localtime(utc_offset) -> time * time.localtime(utc_offset) -> time
* *
* Converts <i>time</i> to local time (using the local time zone in * Converts _time_ to local time (using the local time zone in
* effect for this process) modifying the receiver. * effect for this process) modifying the receiver.
* *
* If _utc_offset_ is given, it is used instead of the local time. * 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 = Time.utc(2000, "jan", 1, 20, 15, 1) #=> 2000-01-01 20:15:01 UTC
* t.utc? #=> true * t.utc? #=> true
@ -3520,7 +3524,7 @@ time_localtime_m(int argc, VALUE *argv, VALUE time)
* time.gmtime -> time * time.gmtime -> time
* time.utc -> time * time.utc -> time
* *
* Converts <i>time</i> to UTC (GMT), modifying the receiver. * Converts _time_ to UTC (GMT), modifying the receiver.
* *
* t = Time.now #=> 2007-11-19 08:18:31 -0600 * t = Time.now #=> 2007-11-19 08:18:31 -0600
* t.gmt? #=> false * t.gmt? #=> false
@ -3594,10 +3598,10 @@ time_fixoff(VALUE time)
* time.getlocal -> new_time * time.getlocal -> new_time
* time.getlocal(utc_offset) -> new_time * time.getlocal(utc_offset) -> new_time
* *
* Returns a new <code>new_time</code> object representing <i>time</i> in * Returns a new Time object representing _time_ in
* local time (using the local time zone in effect for this process). * 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. * 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 = Time.utc(2000,1,1,20,15,1) #=> 2000-01-01 20:15:01 UTC
* t.utc? #=> true * t.utc? #=> true
@ -3634,8 +3638,7 @@ time_getlocaltime(int argc, VALUE *argv, VALUE time)
* time.getgm -> new_time * time.getgm -> new_time
* time.getutc -> new_time * time.getutc -> new_time
* *
* Returns a new <code>new_time</code> object representing <i>time</i> in * Returns a new Time object representing _time_ in UTC.
* UTC.
* *
* t = Time.local(2000,1,1,20,15,1) #=> 2000-01-01 20:15:01 -0600 * t = Time.local(2000,1,1,20,15,1) #=> 2000-01-01 20:15:01 -0600
* t.gmt? #=> false * t.gmt? #=> false
@ -3665,7 +3668,7 @@ static VALUE strftimev(const char *fmt, VALUE time, rb_encoding *enc);
* time.asctime -> string * time.asctime -> string
* time.ctime -> string * time.ctime -> string
* *
* Returns a canonical string representation of <i>time</i>. * Returns a canonical string representation of _time_.
* *
* Time.now.asctime #=> "Wed Apr 9 08:56:03 2003" * Time.now.asctime #=> "Wed Apr 9 08:56:03 2003"
*/ */
@ -3681,15 +3684,15 @@ time_asctime(VALUE time)
* time.inspect -> string * time.inspect -> string
* time.to_s -> string * time.to_s -> string
* *
* Returns a string representing <i>time</i>. Equivalent to calling * Returns a string representing _time_. Equivalent to calling
* <code>Time#strftime</code> with a format string of * #strftime with the appropriate format string.
* ``<code>%Y-%m-%d</code> <code>%H:%M:%S</code> <code>%z</code>''
* for a local time and
* ``<code>%Y-%m-%d</code> <code>%H:%M:%S</code> <code>UTC</code>''
* for a UTC time.
* *
* Time.now.to_s #=> "2007-10-05 16:09:51 +0900" * t = Time.now
* Time.now.utc.to_s #=> "2007-10-05 07:09:51 UTC" * 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"
*/ */
static VALUE static VALUE
@ -3729,8 +3732,8 @@ time_add(struct time_object *tobj, VALUE offset, int sign)
* call-seq: * call-seq:
* time + numeric -> time * time + numeric -> time
* *
* Addition---Adds some number of seconds (possibly fractional) to * Addition --- Adds some number of seconds (possibly fractional) to
* <i>time</i> and returns that value as a new time. * _time_ and returns that value as a new Time object.
* *
* t = Time.now #=> 2007-11-19 08:22:21 -0600 * t = Time.now #=> 2007-11-19 08:22:21 -0600
* t + (60 * 60 * 24) #=> 2007-11-20 08:22:21 -0600 * t + (60 * 60 * 24) #=> 2007-11-20 08:22:21 -0600
@ -3753,9 +3756,9 @@ time_plus(VALUE time1, VALUE time2)
* time - other_time -> float * time - other_time -> float
* time - numeric -> time * time - numeric -> time
* *
* Difference---Returns a new time that represents the difference * Difference --- Returns a new Time object that represents the difference
* between two times, or subtracts the given number of seconds in * between _time_ and +other_time+, or subtracts the given number
* <i>numeric</i> from <i>time</i>. * of seconds in +numeric+ from _time_.
* *
* t = Time.now #=> 2007-11-19 08:23:10 -0600 * t = Time.now #=> 2007-11-19 08:23:10 -0600
* t2 = t + 2592000 #=> 2007-12-19 08:23:10 -0600 * t2 = t + 2592000 #=> 2007-12-19 08:23:10 -0600
@ -3782,11 +3785,15 @@ time_minus(VALUE time1, VALUE time2)
* call-seq: * call-seq:
* time.succ -> new_time * time.succ -> new_time
* *
* Return a new time object, one second later than <code>time</code>. * Returns a new Time object, one second later than _time_.
* Time#succ is obsolete since 1.9.2 for time is not a discrete value. * Time#succ is obsolete since 1.9.2 for time is not a discrete value.
* *
* t = Time.now #=> 2007-11-19 08:23:57 -0600 * t = Time.now #=> 2007-11-19 08:23:57 -0600
* t.succ #=> 2007-11-19 08:23:58 -0600 * t.succ #=> 2007-11-19 08:23:58 -0600
*
* Use instead <code>time + 1</code>
*
* t + 1 #=> 2007-11-19 08:23:58 -0600
*/ */
VALUE VALUE
@ -3810,8 +3817,8 @@ rb_time_succ(VALUE time)
* time.round([ndigits]) -> new_time * time.round([ndigits]) -> new_time
* *
* Rounds sub seconds to a given precision in decimal digits (0 digits by default). * Rounds sub seconds to a given precision in decimal digits (0 digits by default).
* It returns a new time object. * It returns a new Time object.
* _ndigits_ should be zero or positive integer. * +ndigits+ should be zero or positive integer.
* *
* require 'time' * require 'time'
* *
@ -3883,11 +3890,11 @@ time_round(int argc, VALUE *argv, VALUE time)
* call-seq: * call-seq:
* time.sec -> fixnum * time.sec -> fixnum
* *
* Returns the second of the minute (0..60) for <i>time</i>. * Returns the second of the minute (0..60) for _time_.
* *
* <em>[Yes, seconds range from zero to 60. This allows the system to inject * *Note:* Seconds range from zero to 60 to allow the system to inject
* leap seconds. See http://en.wikipedia.org/wiki/Leap_second for further * leap seconds. See http://en.wikipedia.org/wiki/Leap_second for further
* details.]</em> * details.
* *
* t = Time.now #=> 2007-11-19 08:25:02 -0600 * t = Time.now #=> 2007-11-19 08:25:02 -0600
* t.sec #=> 2 * t.sec #=> 2
@ -3907,7 +3914,7 @@ time_sec(VALUE time)
* call-seq: * call-seq:
* time.min -> fixnum * time.min -> fixnum
* *
* Returns the minute of the hour (0..59) for <i>time</i>. * Returns the minute of the hour (0..59) for _time_.
* *
* t = Time.now #=> 2007-11-19 08:25:51 -0600 * t = Time.now #=> 2007-11-19 08:25:51 -0600
* t.min #=> 25 * t.min #=> 25
@ -3927,7 +3934,7 @@ time_min(VALUE time)
* call-seq: * call-seq:
* time.hour -> fixnum * time.hour -> fixnum
* *
* Returns the hour of the day (0..23) for <i>time</i>. * Returns the hour of the day (0..23) for _time_.
* *
* t = Time.now #=> 2007-11-19 08:26:20 -0600 * t = Time.now #=> 2007-11-19 08:26:20 -0600
* t.hour #=> 8 * t.hour #=> 8
@ -3948,7 +3955,7 @@ time_hour(VALUE time)
* time.day -> fixnum * time.day -> fixnum
* time.mday -> fixnum * time.mday -> fixnum
* *
* Returns the day of the month (1..n) for <i>time</i>. * Returns the day of the month (1..n) for _time_.
* *
* t = Time.now #=> 2007-11-19 08:27:03 -0600 * t = Time.now #=> 2007-11-19 08:27:03 -0600
* t.day #=> 19 * t.day #=> 19
@ -3970,7 +3977,7 @@ time_mday(VALUE time)
* time.mon -> fixnum * time.mon -> fixnum
* time.month -> fixnum * time.month -> fixnum
* *
* Returns the month of the year (1..12) for <i>time</i>. * Returns the month of the year (1..12) for _time_.
* *
* t = Time.now #=> 2007-11-19 08:27:30 -0600 * t = Time.now #=> 2007-11-19 08:27:30 -0600
* t.mon #=> 11 * t.mon #=> 11
@ -3991,7 +3998,7 @@ time_mon(VALUE time)
* call-seq: * call-seq:
* time.year -> fixnum * time.year -> fixnum
* *
* Returns the year for <i>time</i> (including the century). * Returns the year for _time_ (including the century).
* *
* t = Time.now #=> 2007-11-19 08:27:51 -0600 * t = Time.now #=> 2007-11-19 08:27:51 -0600
* t.year #=> 2007 * t.year #=> 2007
@ -4046,7 +4053,7 @@ time_wday(VALUE time)
* call-seq: * call-seq:
* time.sunday? -> true or false * time.sunday? -> true or false
* *
* Returns <code>true</code> if <i>time</i> represents Sunday. * Returns +true+ if _time_ represents Sunday.
* *
* t = Time.local(1990, 4, 1) #=> 1990-04-01 00:00:00 -0600 * t = Time.local(1990, 4, 1) #=> 1990-04-01 00:00:00 -0600
* t.sunday? #=> true * t.sunday? #=> true
@ -4062,7 +4069,7 @@ time_sunday(VALUE time)
* call-seq: * call-seq:
* time.monday? -> true or false * time.monday? -> true or false
* *
* Returns <code>true</code> if <i>time</i> represents Monday. * Returns +true+ if _time_ represents Monday.
* *
* t = Time.local(2003, 8, 4) #=> 2003-08-04 00:00:00 -0500 * t = Time.local(2003, 8, 4) #=> 2003-08-04 00:00:00 -0500
* p t.monday? #=> true * p t.monday? #=> true
@ -4078,7 +4085,7 @@ time_monday(VALUE time)
* call-seq: * call-seq:
* time.tuesday? -> true or false * time.tuesday? -> true or false
* *
* Returns <code>true</code> if <i>time</i> represents Tuesday. * Returns +true+ if _time_ represents Tuesday.
* *
* t = Time.local(1991, 2, 19) #=> 1991-02-19 00:00:00 -0600 * t = Time.local(1991, 2, 19) #=> 1991-02-19 00:00:00 -0600
* p t.tuesday? #=> true * p t.tuesday? #=> true
@ -4094,7 +4101,7 @@ time_tuesday(VALUE time)
* call-seq: * call-seq:
* time.wednesday? -> true or false * time.wednesday? -> true or false
* *
* Returns <code>true</code> if <i>time</i> represents Wednesday. * Returns +true+ if _time_ represents Wednesday.
* *
* t = Time.local(1993, 2, 24) #=> 1993-02-24 00:00:00 -0600 * t = Time.local(1993, 2, 24) #=> 1993-02-24 00:00:00 -0600
* p t.wednesday? #=> true * p t.wednesday? #=> true
@ -4110,7 +4117,7 @@ time_wednesday(VALUE time)
* call-seq: * call-seq:
* time.thursday? -> true or false * time.thursday? -> true or false
* *
* Returns <code>true</code> if <i>time</i> represents Thursday. * Returns +true+ if _time_ represents Thursday.
* *
* t = Time.local(1995, 12, 21) #=> 1995-12-21 00:00:00 -0600 * t = Time.local(1995, 12, 21) #=> 1995-12-21 00:00:00 -0600
* p t.thursday? #=> true * p t.thursday? #=> true
@ -4126,7 +4133,7 @@ time_thursday(VALUE time)
* call-seq: * call-seq:
* time.friday? -> true or false * time.friday? -> true or false
* *
* Returns <code>true</code> if <i>time</i> represents Friday. * Returns +true+ if _time_ represents Friday.
* *
* t = Time.local(1987, 12, 18) #=> 1987-12-18 00:00:00 -0600 * t = Time.local(1987, 12, 18) #=> 1987-12-18 00:00:00 -0600
* t.friday? #=> true * t.friday? #=> true
@ -4142,7 +4149,7 @@ time_friday(VALUE time)
* call-seq: * call-seq:
* time.saturday? -> true or false * time.saturday? -> true or false
* *
* Returns <code>true</code> if <i>time</i> represents Saturday. * Returns +true+ if _time_ represents Saturday.
* *
* t = Time.local(2006, 6, 10) #=> 2006-06-10 00:00:00 -0500 * t = Time.local(2006, 6, 10) #=> 2006-06-10 00:00:00 -0500
* t.saturday? #=> true * t.saturday? #=> true
@ -4179,7 +4186,7 @@ time_yday(VALUE time)
* time.isdst -> true or false * time.isdst -> true or false
* time.dst? -> true or false * time.dst? -> true or false
* *
* Returns <code>true</code> if <i>time</i> occurs during Daylight * Returns +true+ if _time_ occurs during Daylight
* Saving Time in its time zone. * Saving Time in its time zone.
* *
* # CST6CDT: * # CST6CDT:
@ -4213,7 +4220,7 @@ time_isdst(VALUE time)
* call-seq: * call-seq:
* time.zone -> string * time.zone -> string
* *
* Returns the name of the time zone used for <i>time</i>. As of Ruby * Returns the name of the time zone used for _time_. As of Ruby
* 1.8, returns ``UTC'' rather than ``GMT'' for UTC times. * 1.8, returns ``UTC'' rather than ``GMT'' for UTC times.
* *
* t = Time.gm(2000, "jan", 1, 20, 15, 1) * t = Time.gm(2000, "jan", 1, 20, 15, 1)
@ -4244,7 +4251,7 @@ time_zone(VALUE time)
* time.gmtoff -> fixnum * time.gmtoff -> fixnum
* time.utc_offset -> fixnum * time.utc_offset -> fixnum
* *
* Returns the offset in seconds between the timezone of <i>time</i> * Returns the offset in seconds between the timezone of _time_
* and UTC. * and UTC.
* *
* t = Time.gm(2000,1,1,20,15,1) #=> 2000-01-01 20:15:01 UTC * t = Time.gm(2000,1,1,20,15,1) #=> 2000-01-01 20:15:01 UTC
@ -4273,12 +4280,14 @@ time_utc_offset(VALUE time)
* call-seq: * call-seq:
* time.to_a -> array * time.to_a -> array
* *
* Returns a ten-element <i>array</i> of values for <i>time</i>: * Returns a ten-element _array_ of values for _time_:
* {<code>[ sec, min, hour, day, month, year, wday, yday, isdst, zone *
* ]</code>}. See the individual methods for an explanation of the * [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 * valid ranges of each value. The ten elements can be passed directly
* to <code>Time::utc</code> or <code>Time::local</code> to create a * to Time::utc or Time::local to create a
* new <code>Time</code>. * new Time object.
* *
* t = Time.now #=> 2007-11-19 08:36:01 -0600 * t = Time.now #=> 2007-11-19 08:36:01 -0600
* now = t.to_a #=> [1, 36, 8, 19, 11, 2007, 1, 323, false, "CST"] * now = t.to_a #=> [1, 36, 8, 19, 11, 2007, 1, 323, false, "CST"]
@ -4372,30 +4381,30 @@ strftimev(const char *fmt, VALUE time, rb_encoding *enc)
* call-seq: * call-seq:
* time.strftime( string ) -> string * time.strftime( string ) -> string
* *
* Formats <i>time</i> according to the directives in the given format * Formats _time_ according to the directives in the given format string.
* string. *
* The directives begins with a percent (%) character. * The directives begin with a percent (%) character.
* Any text not listed as a directive will be passed through to the * Any text not listed as a directive will be passed through to the
* output string. * output string.
* *
* The directive consists of a percent (%) character, * The directive consists of a percent (%) character,
* zero or more flags, optional minimum field width, * zero or more flags, optional minimum field width,
* optional modifier and a conversion specifier * optional modifier and a conversion specifier
* as follows. * as follows:
* *
* %<flags><width><modifier><conversion> * %<flags><width><modifier><conversion>
* *
* Flags: * Flags:
* - don't pad a numerical output. * - don't pad a numerical output
* _ use spaces for padding. * _ use spaces for padding
* 0 use zeros for padding. * 0 use zeros for padding
* ^ upcase the result string. * ^ upcase the result string
* # change case. * # change case
* : use colons for %z. * : use colons for %z
* *
* The minimum field width specifies the minimum width. * The minimum field width specifies the minimum width.
* *
* The modifier is "E" and "O". * The modifiers are "E" and "O".
* They are ignored. * They are ignored.
* *
* Format directives: * Format directives:
@ -4403,7 +4412,7 @@ strftimev(const char *fmt, VALUE time, rb_encoding *enc)
* Date (Year, Month, Day): * Date (Year, Month, Day):
* %Y - Year with century (can be negative, 4 digits at least) * %Y - Year with century (can be negative, 4 digits at least)
* -0001, 0000, 1995, 2009, 14292, etc. * -0001, 0000, 1995, 2009, 14292, etc.
* %C - year / 100 (round down. 20 in 2009) * %C - year / 100 (rounded down such as 20 in 2009)
* %y - year % 100 (00..99) * %y - year % 100 (00..99)
* *
* %m - Month of the year, zero-padded (01..12) * %m - Month of the year, zero-padded (01..12)
@ -4448,7 +4457,7 @@ strftimev(const char *fmt, VALUE time, rb_encoding *enc)
* %z - Time zone as hour and minute offset from UTC (e.g. +0900) * %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 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:00:00)
* %Z - Time zone abbreviation name or something similar information. * %Z - Abbreviated time zone name or similar information.
* *
* Weekday: * Weekday:
* %A - The full weekday name (``Sunday'') * %A - The full weekday name (``Sunday'')
@ -4459,7 +4468,7 @@ strftimev(const char *fmt, VALUE time, rb_encoding *enc)
* %w - Day of the week (Sunday is 0, 0..6) * %w - Day of the week (Sunday is 0, 0..6)
* *
* ISO 8601 week-based year and week number: * ISO 8601 week-based year and week number:
* The week 1 of YYYY starts with a Monday and includes YYYY-01-04. * 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 days in the year before the first week are in the last week of
* the previous year. * the previous year.
* %G - The week-based year * %G - The week-based year
@ -4467,10 +4476,10 @@ strftimev(const char *fmt, VALUE time, rb_encoding *enc)
* %V - Week number of the week-based year (01..53) * %V - Week number of the week-based year (01..53)
* *
* Week number: * Week number:
* The week 1 of YYYY starts with a Sunday or Monday (according to %U * 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. * 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) * %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) * %W - Week number of the year. The week starts with Monday. (00..53)
* *
* Seconds since the Epoch: * Seconds since the Epoch:
* %s - Number of seconds since 1970-01-01 00:00:00 UTC. * %s - Number of seconds since 1970-01-01 00:00:00 UTC.
@ -4492,21 +4501,18 @@ strftimev(const char *fmt, VALUE time, rb_encoding *enc)
* %T - 24-hour time (%H:%M:%S) * %T - 24-hour time (%H:%M:%S)
* *
* This method is similar to strftime() function defined in ISO C and POSIX. * 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. * While all directives are locale independant since Ruby 1.9 %Z is platform
* However this method is locale independent since Ruby 1.9. * dependant.
* (%Z is platform dependent, though.) * So, the result may differ even if the same format string is used in other
* So, the result may differ even if a same format string is used in other
* systems such as C. * systems such as C.
* It is good practice to avoid %x and %X because there are corresponding
* locale independent representations, %D and %T.
* *
* %z is recommended over %Z. * %z is recommended over %Z.
* %Z doesn't identify the timezone. * %Z doesn't identify the timezone.
* For example, "CST" is used at America/Chicago (-06:00), * For example, "CST" is used at America/Chicago (-06:00),
* America/Havana (-05:00), Asia/Harbin (+08:00), Australia/Darwin (+09:30) * America/Havana (-05:00), Asia/Harbin (+08:00), Australia/Darwin (+09:30)
* and Australia/Adelaide (+10:30). * and Australia/Adelaide (+10:30).
* Also, %Z is highly dependent for OS. * Also, %Z is highly dependent on the operating system.
* For example, it may generate a non ASCII string on Japanese Windows. * For example, it may generate a non ASCII string on Japanese Windows.
* i.e. the result can be different to "JST". * i.e. the result can be different to "JST".
* So the numeric time zone offset, %z, is recommended. * So the numeric time zone offset, %z, is recommended.
@ -4849,7 +4855,7 @@ end_submicro: ;
* call-seq: * call-seq:
* Time._load(string) -> time * Time._load(string) -> time
* *
* Unmarshal a dumped +Time+ object. * Unmarshal a dumped Time object.
*/ */
static VALUE static VALUE
@ -4864,7 +4870,7 @@ time_load(VALUE klass, VALUE str)
/* /*
* Time is an abstraction of dates and times. Time is stored internally as * 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 * the number of seconds with fraction since the _Epoch_, January 1, 1970
* 00:00 UTC. Also see the library modules Date. The Time class treats GMT * 00:00 UTC. Also see the library module Date. The Time class treats GMT
* (Greenwich Mean Time) and UTC (Coordinated Universal Time) as equivalent. * (Greenwich Mean Time) and UTC (Coordinated Universal Time) as equivalent.
* GMT is the older way of referring to these baseline times but persists in * GMT is the older way of referring to these baseline times but persists in
* the names of calls on POSIX systems. * the names of calls on POSIX systems.
@ -4873,11 +4879,12 @@ time_load(VALUE klass, VALUE str)
* with each other -- times that are apparently equal when displayed may be * with each other -- times that are apparently equal when displayed may be
* different when compared. * different when compared.
* *
* Since Ruby 1.9.2, Time implementation uses a signed 63 bit integer, Bignum or Rational. * 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 * The integer is a number of nanoseconds since the _Epoch_ which can
* represent 1823-11-12 to 2116-02-20. * represent 1823-11-12 to 2116-02-20.
* When Bignum or Rational is used (before 1823, after 2116, under nanosecond), * When Bignum or Rational is used (before 1823, after 2116, under
* Time works slower than the integer is used. * nanosecond), Time works slower as when integer is used.
* *
* = Examples * = Examples
* *
@ -4885,11 +4892,11 @@ time_load(VALUE klass, VALUE str)
* *
* == Creating a new Time instance * == Creating a new Time instance
* *
* You can create a new instance of time with Time.new. This will use the * You can create a new instance of Time with Time::new. This will use the
* current system time. Time.now is a synonym for this. You can also * 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 * 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 * you want to construct a time this way you must pass at least a year. If you
* pass the year with nothing else time with default to January 1 of that year * 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: * 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) #=> 2002-01-01 00:00:00 -0500
@ -4897,10 +4904,11 @@ time_load(VALUE klass, VALUE str)
* Time.new(2002, 10, 31) #=> 2002-10-31 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 * 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 * You can also use #gm, #local and
* timezones instead of using the current system setting. * #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 * You can also create a new time using Time::at which takes the number of
* seconds (or fraction of seconds) since the {Unix * seconds (or fraction of seconds) since the {Unix
* Epoch}[http://en.wikipedia.org/wiki/Unix_time]. * Epoch}[http://en.wikipedia.org/wiki/Unix_time].
* *
@ -4908,8 +4916,8 @@ time_load(VALUE klass, VALUE str)
* *
* == Working with an instance of Time * == Working with an instance of Time
* *
* Once you have an instance of time there is a multitude of things you can do * Once you have an instance of Time there is a multitude of things you can
* with it. Below are some examples. For all of the following examples, we * 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: * will work on the assumption that you have done the following:
* *
* t = Time.new(1993, 02, 24, 12, 0, 0, "+09:00") * t = Time.new(1993, 02, 24, 12, 0, 0, "+09:00")
@ -4930,7 +4938,7 @@ time_load(VALUE klass, VALUE str)
* *
* t + (60*60*24*365) #=> 1994-02-24 12:00:00 +0900 * t + (60*60*24*365) #=> 1994-02-24 12:00:00 +0900
* *
* How many second was that from the Unix Epoch? * How many seconds was that since the Unix Epoch?
* *
* t.to_i #=> 730522800 * t.to_i #=> 730522800
* *