Ruby » Ruby master

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

* Creates a new Time object for the current time.

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

* Addition --- Adds some number of seconds (possibly fractional) to

* Difference --- Returns a new Time object that represents the difference

* +ndigits+ should be zero or positive integer.

From e96d86df690b5e4c6020d115d224b7b3b185e7cd Mon Sep 17 00:00:00 2001

From: Bernd Homuth <dev@hmt.im>

Date: Sat, 24 Nov 2012 10:32:49 +0100

Subject: [PATCH] language fixes in time.c

---

time.c | 32 ++++++++++++++++----------------

1 file changed, 16 insertions(+), 16 deletions(-)

diff --git a/time.c b/time.c

index fbae712..426db16 100644

--- a/time.c

+++ b/time.c

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

/*

- * The idea is come from Perl:

+ * The idea is borrowed from Perl:

* http://use.perl.org/articles/08/02/07/197204.shtml

*

- * compat_common_month_table is generated by following program.

- * This table finds the last month which start the same day of a week.

- * The year 2037 is not used because

+ * compat_common_month_table is generated by the following program.

+ * This table finds the last month which starts at the same day of a week.

+ * The year 2037 is not used because:

* http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=522949

*

* #!/usr/bin/ruby

@@ -1502,8 +1502,8 @@ guess_local_offset(struct vtm *vtm_utc, int *isdst_ret, const char **zone_ret)

VALUE timev;

int y, wday;

- /* The first DST is at 1916 in German.

- * So we don't need to care DST before that. */

+ /* Daylight Saving Time was introduced in 1916.

+ * So we don't need to care about DST before that. */

if (lt(vtm_utc->year, INT2FIX(1916))) {

VALUE off = INT2FIX(0);

int isdst = 0;

@@ -1537,7 +1537,7 @@ guess_local_offset(struct vtm *vtm_utc, int *isdst_ret, const char **zone_ret)

return off;

}

- /* It is difficult to guess future. */

+ /* It is difficult to guess the future. */

vtm2 = *vtm_utc;

@@ -2232,7 +2232,7 @@ time_init_1(int argc, VALUE *argv, VALUE time)

* _sec_ may have fraction if it is a rational.

*

* _utc_offset_ is the offset from UTC.

- * It is a string such as "+09:00" or a number of seconds such as 32400.

+ * 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

@@ -3202,7 +3202,7 @@ time_to_i(VALUE time)

* t.to_i #=> 1270968744

*

* 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

@@ -4448,7 +4448,7 @@ strftimev(const char *fmt, VALUE time, rb_encoding *enc)

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

+ * %Z - Abbreviated time zone name or similar information.

*

* Weekday:

* %A - The full weekday name (``Sunday'')

@@ -4459,7 +4459,7 @@ strftimev(const char *fmt, VALUE time, rb_encoding *enc)

* %w - Day of the week (Sunday is 0, 0..6)

*

* ISO 8601 week-based year and week number:

- * The week 1 of YYYY starts with a Monday and includes YYYY-01-04.

+ * The 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

@@ -4467,10 +4467,10 @@ strftimev(const char *fmt, VALUE time, rb_encoding *enc)

* %V - Week number of the week-based year (01..53)

*

* Week number:

- * The week 1 of YYYY starts with a Sunday or Monday (according to %U

- * or %W). The days in the year before the first week are in week 0.

- * %U - Week number of the year. The week starts with Sunday. (00..53)

- * %W - Week number of the year. The week starts with Monday. (00..53)

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

@@ -4930,7 +4930,7 @@ time_load(VALUE klass, VALUE str)

*

* 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

*

--

1.7.11.1

From 921e29ced5884f8b02dc9aa4851d77c30d743312 Mon Sep 17 00:00:00 2001

From: Bernd Homuth <dev@hmt.im>

Date: Sat, 24 Nov 2012 10:51:40 +0100

Subject: [PATCH] reformat docs in time.c

---

time.c | 168 ++++++++++++++++++++++++++++++++---------------------------------

1 file changed, 84 insertions(+), 84 deletions(-)

diff --git a/time.c b/time.c

index 426db16..97d37ed 100644

--- a/time.c

+++ b/time.c

@@ -1943,7 +1943,7 @@ timew2timespec_exact(wideval_t timew, struct timespec *ts)

/*

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

*/

@@ -2220,7 +2220,7 @@ time_init_1(int argc, VALUE *argv, VALUE time)

* Time.new -> 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.

* <b>Note:</b> The object created will be created using the

@@ -2505,21 +2505,21 @@ time_s_now(VALUE klass)

* Time.at(seconds_with_frac) -> time

* Time.at(seconds, microseconds_with_frac) -> time

*

- * Creates a new time object with the value given by <i>time</i>,

- * the given number of <i>seconds_with_frac</i>, or

- * <i>seconds</i> and <i>microseconds_with_frac</i> from the Epoch.

- * <i>seconds_with_frac</i> and <i>microseconds_with_frac</i>

- * can be Integer, Float, Rational, or other Numeric.

+ * 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 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

+ * 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

*/

static VALUE

@@ -3120,13 +3120,13 @@ time_utc_or_local(int argc, VALUE *argv, int utc_p, VALUE klass)

*

* Creates a time 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 <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

* 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

- * also accept ten arguments in the order output by

- * <code>Time#to_a</code>.

- * <i>sec_with_frac</i> and <i>usec_with_frac</i> can have a fractional part.

+ * 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

@@ -3156,7 +3156,7 @@ time_s_mkutc(int argc, VALUE *argv, VALUE klass)

* 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

*

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

*

* Time.local(2000,"jan",1,20,15,1) #=> 2000-01-01 20:15:01 -0600

@@ -3173,7 +3173,7 @@ time_s_mktime(int argc, VALUE *argv, VALUE klass)

* time.to_i -> 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.

*

* t = Time.now

@@ -3194,7 +3194,7 @@ time_to_i(VALUE time)

* call-seq:

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

*

* t = Time.now

@@ -3218,15 +3218,15 @@ time_to_f(VALUE time)

* call-seq:

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

*

* t = Time.now

* p t.to_r #=> (1270968792716287611/1000000000)

*

* This methods is intended to be used to get an accurate value

- * representing nanoseconds from the Epoch. You can use this

- * to convert time to another Epoch.

+ * representing the nanoseconds since the Epoch. You can use this method

+ * to convert _time_ to another Epoch.

*/

static VALUE

@@ -3248,7 +3248,7 @@ time_to_r(VALUE time)

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

* "%10.6f" % t.to_f #=> "1195481006.775195"

@@ -3273,13 +3273,13 @@ time_usec(VALUE time)

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

* "%10.9f" % t.to_f #=> "1195280283.536151409"

* 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

* nanoseconds from the Epoch.

* The accurate value is returned by nsec.

@@ -3298,7 +3298,7 @@ time_nsec(VALUE time)

* call-seq:

* time.subsec -> number

*

- * Returns just the fraction for <i>time</i>.

+ * Returns the fraction for _time_.

*

* The result is possibly rational.

*

@@ -3306,7 +3306,7 @@ time_nsec(VALUE time)

* "%10.9f" % t.to_f #=> "1238074392.940563917"

* 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

* the rational.

* The accurate value is returned by subsec.

@@ -3369,9 +3369,8 @@ time_cmp(VALUE time1, VALUE time2)

* call-seq:

* time.eql?(other_time)

*

- * Return <code>true</code> if <i>time</i> and <i>other_time</i> are

- * both <code>Time</code> objects with the same seconds and fractional

- * seconds.

+ * Returns +true+ if _time_ and +other_time+ are

+ * both Time objects with the same seconds and fractional seconds.

*/

static VALUE

@@ -3392,8 +3391,7 @@ time_eql(VALUE time1, VALUE time2)

* time.utc? -> true or false

* time.gmt? -> true or false

*

- * Returns <code>true</code> if <i>time</i> represents a time in UTC

- * (GMT).

+ * Returns +true+ if _time_ represents a time in UTC (GMT).

*

* t = Time.now #=> 2007-11-19 08:15:23 -0600

* t.utc? #=> false

@@ -3420,7 +3418,7 @@ time_utc_p(VALUE time)

* call-seq:

* time.hash -> fixnum

*

- * Return a hash code for this time object.

+ * Returns a hash code for this Time object.

*/

static VALUE

@@ -3483,7 +3481,7 @@ time_localtime(VALUE time)

* time.localtime -> 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.

*

* If _utc_offset_ is given, it is used instead of the local time.

@@ -3520,7 +3518,7 @@ time_localtime_m(int argc, VALUE *argv, VALUE time)

* time.gmtime -> 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.gmt? #=> false

@@ -3594,7 +3592,7 @@ time_fixoff(VALUE time)

* time.getlocal -> 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).

*

* If _utc_offset_ is given, it is used instead of the local time.

@@ -3634,8 +3632,7 @@ time_getlocaltime(int argc, VALUE *argv, VALUE time)

* time.getgm -> new_time

* time.getutc -> new_time

*

- * Returns a new <code>new_time</code> object representing <i>time</i> in

- * UTC.

+ * Returns a new Time object representing _time_ in UTC.

*

* t = Time.local(2000,1,1,20,15,1) #=> 2000-01-01 20:15:01 -0600

* t.gmt? #=> false

@@ -3665,7 +3662,7 @@ static VALUE strftimev(const char *fmt, VALUE time, rb_encoding *enc);

* time.asctime -> 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"

*/

@@ -3730,7 +3727,7 @@ time_add(struct time_object *tobj, VALUE offset, int sign)

* time + numeric -> time

*

* 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 + (60 * 60 * 24) #=> 2007-11-20 08:22:21 -0600

@@ -3782,7 +3779,7 @@ time_minus(VALUE time1, VALUE time2)

* call-seq:

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

*

* t = Time.now #=> 2007-11-19 08:23:57 -0600

@@ -3810,7 +3807,7 @@ rb_time_succ(VALUE time)

* time.round([ndigits]) -> new_time

*

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

*

* require 'time'

@@ -3883,7 +3880,7 @@ time_round(int argc, VALUE *argv, VALUE time)

* call-seq:

* 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

* leap seconds. See http://en.wikipedia.org/wiki/Leap_second for further

@@ -3907,7 +3904,7 @@ time_sec(VALUE time)

* call-seq:

* 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.min #=> 25

@@ -3927,7 +3924,7 @@ time_min(VALUE time)

* call-seq:

* 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.hour #=> 8

@@ -3948,7 +3945,7 @@ time_hour(VALUE time)

* time.day -> 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.day #=> 19

@@ -3970,7 +3967,7 @@ time_mday(VALUE time)

* time.mon -> 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.mon #=> 11

@@ -3991,7 +3988,7 @@ time_mon(VALUE time)

* call-seq:

* 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.year #=> 2007

@@ -4046,7 +4043,7 @@ time_wday(VALUE time)

* call-seq:

* 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.sunday? #=> true

@@ -4062,7 +4059,7 @@ time_sunday(VALUE time)

* call-seq:

* 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

* p t.monday? #=> true

@@ -4078,7 +4075,7 @@ time_monday(VALUE time)

* call-seq:

* 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

* p t.tuesday? #=> true

@@ -4094,7 +4091,7 @@ time_tuesday(VALUE time)

* call-seq:

* 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

* p t.wednesday? #=> true

@@ -4110,7 +4107,7 @@ time_wednesday(VALUE time)

* call-seq:

* 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

* p t.thursday? #=> true

@@ -4126,7 +4123,7 @@ time_thursday(VALUE time)

* call-seq:

* 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.friday? #=> true

@@ -4142,7 +4139,7 @@ time_friday(VALUE time)

* call-seq:

* 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.saturday? #=> true

@@ -4179,7 +4176,7 @@ time_yday(VALUE time)

* time.isdst -> 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.

*

* # CST6CDT:

@@ -4213,7 +4210,7 @@ time_isdst(VALUE time)

* call-seq:

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

*

* t = Time.gm(2000, "jan", 1, 20, 15, 1)

@@ -4244,7 +4241,7 @@ time_zone(VALUE time)

* time.gmtoff -> 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.

*

* t = Time.gm(2000,1,1,20,15,1) #=> 2000-01-01 20:15:01 UTC

@@ -4273,12 +4270,14 @@ time_utc_offset(VALUE time)

* call-seq:

* time.to_a -> array

*

- * Returns a ten-element <i>array</i> of values for <i>time</i>:

- * {<code>[ sec, min, hour, day, month, year, wday, yday, isdst, zone

- * ]</code>}. See the individual methods for an explanation of the

+ * 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 <code>Time::utc</code> or <code>Time::local</code> to create a

- * new <code>Time</code>.

+ * 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"]

@@ -4372,30 +4371,30 @@ strftimev(const char *fmt, VALUE time, rb_encoding *enc)

* call-seq:

* time.strftime( string ) -> string

*

- * Formats <i>time</i> according to the directives in the given format

- * string.

- * The directives begins with a percent (%) character.

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

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

+ * - 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 modifier is "E" and "O".

+ * The modifiers are "E" and "O".

* They are ignored.

*

* Format directives:

@@ -4849,7 +4848,7 @@ end_submicro: ;

* call-seq:

* Time._load(string) -> time

*

- * Unmarshal a dumped +Time+ object.

+ * Unmarshal a dumped Time object.

*/

static VALUE

@@ -4873,7 +4872,8 @@ time_load(VALUE klass, VALUE str)

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

+ * 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),

@@ -4885,9 +4885,9 @@ time_load(VALUE klass, VALUE str)

*

* == 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 a synonym for this. You can also

- * pass parts of the time to Time.new such as year, month, minute, etc. When

+ * 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 with default to January 1 of that year

* at 00:00:00 with the current system timezone. Here are some examples:

@@ -4900,7 +4900,7 @@ time_load(VALUE klass, VALUE str)

* 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

+ * You can also create a new time using Time::at which takes the number of

* seconds (or fraction of seconds) since the {Unix

* Epoch}[http://en.wikipedia.org/wiki/Unix_time].

*

@@ -4908,8 +4908,8 @@ time_load(VALUE klass, VALUE str)

*

* == 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

+ * 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")

--

1.7.11.1

From 98a8afe3f80d82ffddacd7eaf4bbc16c72d9f2be Mon Sep 17 00:00:00 2001

From: Bernd Homuth <dev@hmt.im>

Date: Sat, 24 Nov 2012 10:58:26 +0100

Subject: [PATCH] changes to time.c docs

---

time.c | 87 ++++++++++++++++++++++++++++++++++++------------------------------

1 file changed, 47 insertions(+), 40 deletions(-)

diff --git a/time.c b/time.c

index 97d37ed..592965e 100644

--- a/time.c

+++ b/time.c

@@ -2222,10 +2222,10 @@ time_init_1(int argc, VALUE *argv, VALUE time)

*

* Returns a Time object.

*

- * It is initialized to the current system time if no argument.

- * <b>Note:</b> The object created will be created using the

- * resolution available on your system clock, and so may include

- * fractional seconds.

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

@@ -3118,7 +3118,7 @@ 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(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

* 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

@@ -3281,8 +3281,9 @@ time_usec(VALUE time)

*

* The lowest digits of #to_f and #nsec are different because

* IEEE 754 double is not accurate enough to represent

- * nanoseconds from the Epoch.

- * The accurate value is returned by nsec.

+ * the exact number of nanoseconds since the Epoch.

+ *

+ * The more accurate value is returned by #nsec.

*/

static VALUE

@@ -3300,7 +3301,7 @@ time_nsec(VALUE time)

*

* 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

* "%10.9f" % t.to_f #=> "1238074392.940563917"

@@ -3308,8 +3309,9 @@ time_nsec(VALUE time)

*

* The lowest digits of #to_f and #subsec are different because

* IEEE 754 double is not accurate enough to represent

- * the rational.

- * The accurate value is returned by subsec.

+ * the rational number.

+ *

+ * The more accurate value is returned by #subsec.

*/

static VALUE

@@ -3325,7 +3327,10 @@ time_subsec(VALUE time)

* call-seq:

* 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

* t2 = t + 2592000 #=> 2007-12-19 08:12:12 -0600

@@ -3678,15 +3683,15 @@ time_asctime(VALUE time)

* time.inspect -> string

* time.to_s -> string

*

- * Returns a string representing <i>time</i>. Equivalent to calling

- * <code>Time#strftime</code> with a format string of

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

+ * 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"

*

- * Time.now.to_s #=> "2007-10-05 16:09:51 +0900"

- * Time.now.utc.to_s #=> "2007-10-05 07:09:51 UTC"

+ * 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

@@ -3750,9 +3755,9 @@ time_plus(VALUE time1, VALUE time2)

* time - other_time -> float

* time - numeric -> time

*

- * Difference---Returns a new time that represents the difference

- * between two times, or subtracts the given number of seconds in

- * <i>numeric</i> from <i>time</i>.

+ * 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

@@ -3784,6 +3789,10 @@ time_minus(VALUE time1, VALUE time2)

*

* t = Time.now #=> 2007-11-19 08:23:57 -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

@@ -3882,9 +3891,9 @@ time_round(int argc, VALUE *argv, VALUE time)

*

* Returns the second of the minute (0..60) for _time_.

*

- * <em>[Yes, seconds range from zero to 60. This allows the system to inject

- * leap seconds. See http://en.wikipedia.org/wiki/Leap_second for further

- * details.]</em>

+ * *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

+ * details.

*

* t = Time.now #=> 2007-11-19 08:25:02 -0600

* t.sec #=> 2

@@ -4402,7 +4411,7 @@ strftimev(const char *fmt, VALUE time, rb_encoding *enc)

* Date (Year, Month, Day):

* %Y - Year with century (can be negative, 4 digits at least)

* -0001, 0000, 1995, 2009, 14292, etc.

- * %C - year / 100 (round down. 20 in 2009)

+ * %C - year / 100 (rounded down such as 20 in 2009)

* %y - year % 100 (00..99)

*

* %m - Month of the year, zero-padded (01..12)

@@ -4491,21 +4500,18 @@ strftimev(const char *fmt, VALUE time, rb_encoding *enc)

* %T - 24-hour time (%H:%M:%S)

*

* This method is similar to strftime() function defined in ISO C and POSIX.

- * Several directives (%a, %A, %b, %B, %c, %p, %r, %x, %X, %E*, %O* and %Z)

- * are locale dependent in the function.

- * However this method is locale independent since Ruby 1.9.

- * (%Z is platform dependent, though.)

- * So, the result may differ even if a same format string is used in other

+ *

+ * While all directives are locale independant since Ruby 1.9 %Z is platform

+ * dependant.

+ * So, the result may differ even if the same format string is used in other

* systems such as C.

- * It is good practice to avoid %x and %X because there are corresponding

- * locale independent representations, %D and %T.

*

* %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 for OS.

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

@@ -4863,7 +4869,7 @@ time_load(VALUE klass, VALUE str)

/*

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

* GMT is the older way of referring to these baseline times but persists in

* the names of calls on POSIX systems.

@@ -4876,8 +4882,8 @@ time_load(VALUE klass, VALUE str)

* 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 than the integer is used.

+ * When Bignum or Rational is used (before 1823, after 2116, under

+ * nanosecond), Time works slower as when integer is used.

*

* = Examples

*

@@ -4889,7 +4895,7 @@ time_load(VALUE klass, VALUE str)

* 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 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:

*

* Time.new(2002) #=> 2002-01-01 00:00:00 -0500

@@ -4897,8 +4903,9 @@ time_load(VALUE klass, VALUE str)

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

--

1.7.11.1