From 11cdca27d8671e65c8da5065f6fd233d219aa1c4 Mon Sep 17 00:00:00 2001 From: Bernd Homuth Date: Sat, 24 Nov 2012 22:25:54 +0100 Subject: [PATCH] More format changes to time.c --- time.c | 21 +- time_patch0001.diff | 113 +++++++++++ time_patch0002.diff | 537 ++++++++++++++++++++++++++++++++++++++++++++++++++++ time_patch0003.diff | 223 ++++++++++++++++++++++ 4 files changed, 884 insertions(+), 10 deletions(-) create mode 100644 time_patch0001.diff create mode 100644 time_patch0002.diff create mode 100644 time_patch0003.diff diff --git a/time.c b/time.c index 592965e..f56b8ff 100644 --- a/time.c +++ b/time.c @@ -2227,11 +2227,12 @@ time_init_1(int argc, VALUE *argv, VALUE time) * *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. + * If one or more arguments specified, the time is initialized to the specified + * time. * - * _utc_offset_ is the offset from UTC. + * +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 @@ -2488,7 +2489,7 @@ rb_time_timespec(VALUE time) * call-seq: * 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 */ @@ -3489,7 +3490,7 @@ time_localtime(VALUE 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. + * 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 @@ -3600,7 +3601,7 @@ time_fixoff(VALUE 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. + * 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 @@ -3731,7 +3732,7 @@ time_add(struct time_object *tobj, VALUE offset, int sign) * call-seq: * time + numeric -> time * - * Addition---Adds some number of seconds (possibly fractional) to + * Addition --- Adds some number of seconds (possibly fractional) to * _time_ and returns that value as a new Time object. * * t = Time.now #=> 2007-11-19 08:22:21 -0600 @@ -3755,7 +3756,7 @@ time_plus(VALUE time1, VALUE time2) * time - other_time -> float * time - numeric -> time * - * Difference---Returns a new Time object that represents the difference + * 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_. * @@ -3817,7 +3818,7 @@ rb_time_succ(VALUE 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. + * +ndigits+ should be zero or positive integer. * * require 'time' * diff --git a/time_patch0001.diff b/time_patch0001.diff new file mode 100644 index 0000000..ad415ac --- /dev/null +++ b/time_patch0001.diff @@ -0,0 +1,113 @@ +From e96d86df690b5e4c6020d115d224b7b3b185e7cd Mon Sep 17 00:00:00 2001 +From: Bernd Homuth +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 + diff --git a/time_patch0002.diff b/time_patch0002.diff new file mode 100644 index 0000000..78a5c03 --- /dev/null +++ b/time_patch0002.diff @@ -0,0 +1,537 @@ +From 921e29ced5884f8b02dc9aa4851d77c30d743312 Mon Sep 17 00:00:00 2001 +From: Bernd Homuth +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 Time.new. 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 Time object. ++ * Returns a Time object. + * + * It is initialized to the current system time if no argument. + * Note: 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 time, +- * the given number of seconds_with_frac, or +- * seconds and microseconds_with_frac from the Epoch. +- * seconds_with_frac and microseconds_with_frac +- * 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 nil 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 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. ++ * 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 Time::gm, 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 time 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 time 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 time 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 time. ++ * 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 time. ++ * 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 time. ++ * 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 true if time and other_time are +- * both Time 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 true if time 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 time 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 time 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 new_time object representing time 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 new_time object representing time 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 time. ++ * 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 +- * time 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 time. ++ * 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 time. ++ * Returns the second of the minute (0..60) for _time_. + * + * [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 time. ++ * 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 time. ++ * 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 time. ++ * 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 time. ++ * 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 time (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 true if time 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 true if time 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 true if time 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 true if time 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 true if time 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 true if time 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 true if time 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 true if time 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 time. 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 time ++ * 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 array of values for time: +- * {[ sec, min, hour, day, month, year, wday, yday, isdst, zone +- * ]}. 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 Time::utc or Time::local to create a +- * new Time. ++ * 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 time 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: +- * - 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 + diff --git a/time_patch0003.diff b/time_patch0003.diff new file mode 100644 index 0000000..16d538e --- /dev/null +++ b/time_patch0003.diff @@ -0,0 +1,223 @@ +From 98a8afe3f80d82ffddacd7eaf4bbc16c72d9f2be Mon Sep 17 00:00:00 2001 +From: Bernd Homuth +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. +- * Note: 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 time with other_time. ++ * 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 time. Equivalent to calling +- * Time#strftime with a format string of +- * ``%Y-%m-%d %H:%M:%S %z'' +- * for a local time and +- * ``%Y-%m-%d %H:%M:%S UTC'' +- * 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 +- * numeric from 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 +@@ -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 time + 1 ++ * ++ * 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_. + * +- * [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.] ++ * *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 + -- 1.7.11.1