ruby-changes:73400
From: Burdette <ko1@a...>
Date: Sat, 3 Sep 2022 22:37:03 +0900 (JST)
Subject: [ruby-changes:73400] fe865c5262 (master): [DOC] Enhanced RDoc for Time (#6320)
https://git.ruby-lang.org/ruby.git/commit/?id=fe865c5262 From fe865c5262bb2daea64f488b9247780e5fae7ac7 Mon Sep 17 00:00:00 2001 From: Burdette Lamar <BurdetteLamar@Y...> Date: Sat, 3 Sep 2022 08:36:44 -0500 Subject: [DOC] Enhanced RDoc for Time (#6320) Treats: #yday #dst? #zone #to_a #strftime --- time.c | 267 +++++++++-------------------------------------------------------- 1 file changed, 36 insertions(+), 231 deletions(-) diff --git a/time.c b/time.c index a02e53d7f1..26083b0d5d 100644 --- a/time.c +++ b/time.c @@ -4685,12 +4685,12 @@ time_saturday(VALUE time) https://github.com/ruby/ruby/blob/trunk/time.c#L4685 /* * call-seq: - * time.yday -> integer + * yday -> integer * - * Returns an integer representing the day of the year, 1..366. + * Returns the integer day of the year of +self+, in range (1..366). * - * t = Time.now #=> 2007-11-19 08:32:31 -0600 - * t.yday #=> 323 + * Time.new(2000, 1, 1).yday # => 1 + * Time.new(2000, 12, 31).yday # => 366 */ static VALUE @@ -4705,27 +4705,18 @@ time_yday(VALUE time) https://github.com/ruby/ruby/blob/trunk/time.c#L4705 /* * call-seq: - * time.isdst -> true or false - * time.dst? -> true or false - * - * Returns +true+ if _time_ occurs during Daylight - * Saving Time in its time zone. - * - * # CST6CDT: - * Time.local(2000, 1, 1).zone #=> "CST" - * Time.local(2000, 1, 1).isdst #=> false - * Time.local(2000, 1, 1).dst? #=> false - * Time.local(2000, 7, 1).zone #=> "CDT" - * Time.local(2000, 7, 1).isdst #=> true - * Time.local(2000, 7, 1).dst? #=> true - * - * # Asia/Tokyo: - * Time.local(2000, 1, 1).zone #=> "JST" - * Time.local(2000, 1, 1).isdst #=> false - * Time.local(2000, 1, 1).dst? #=> false - * Time.local(2000, 7, 1).zone #=> "JST" - * Time.local(2000, 7, 1).isdst #=> false - * Time.local(2000, 7, 1).dst? #=> false + * dst? -> true or false + * + * Returns +true+ if +self+ is in daylight saving time, +false+ otherwise: + * + * t = Time.local(2000, 1, 1) # => 2000-01-01 00:00:00 -0600 + * t.zone # => "Central Standard Time" + * t.dst? # => false + * t = Time.local(2000, 7, 1) # => 2000-07-01 00:00:00 -0500 + * t.zone # => "Central Daylight Time" + * t.dst? # => true + * + * Time#isdst is an alias for Time#dst?. */ static VALUE @@ -4745,13 +4736,10 @@ time_isdst(VALUE time) https://github.com/ruby/ruby/blob/trunk/time.c#L4736 * call-seq: * time.zone -> string or timezone * - * Returns the name of the time zone used for _time_. As of Ruby - * 1.8, returns ``UTC'' rather than ``GMT'' for UTC times. + * Returns the string name of the time zone for +self+: * - * t = Time.gm(2000, "jan", 1, 20, 15, 1) - * t.zone #=> "UTC" - * t = Time.local(2000, "jan", 1, 20, 15, 1) - * t.zone #=> "CST" + * Time.utc(2000, 1, 1).zone # => "UTC" + * Time.new(2000, 1, 1).zone # => "Central Standard Time" */ static VALUE @@ -4777,17 +4765,14 @@ time_zone(VALUE time) https://github.com/ruby/ruby/blob/trunk/time.c#L4765 /* * call-seq: - * time.gmt_offset -> integer - * time.gmtoff -> integer - * time.utc_offset -> integer + * utc_offset -> integer + * + * Returns the offset in seconds between the timezones of UTC and +self+: * - * Returns the offset in seconds between the timezone of _time_ - * and UTC. + * Time.utc(2000, 1, 1).utc_offset # => 0 + * Time.local(2000, 1, 1).utc_offset # => -21600 # -6*3600, or minus six hours. * - * t = Time.gm(2000,1,1,20,15,1) #=> 2000-01-01 20:15:01 UTC - * t.gmt_offset #=> 0 - * l = t.getlocal #=> 2000-01-01 14:15:01 -0600 - * l.gmt_offset #=> -21600 + * Time#gmt_offset and Time#gmtoff are aliases for Time#utc_offset. */ VALUE @@ -4808,19 +4793,17 @@ rb_time_utc_offset(VALUE time) https://github.com/ruby/ruby/blob/trunk/time.c#L4793 /* * call-seq: - * time.to_a -> array + * to_a -> array * - * Returns a ten-element _array_ of values for _time_: + * Returns a 10-element array of values representing +self+: * - * [sec, min, hour, day, month, year, wday, yday, isdst, zone] + * Time.utc(2000, 1, 1).to_a + * # => [0, 0, 0, 1, 1, 2000, 6, 1, false, "UTC"] + * # [sec, min, hour, day, mon, year, wday, yday, dst?, zone] * - * See the individual methods for an explanation of the - * valid ranges of each value. The ten elements can be passed directly - * to Time.utc or Time.local to create a - * new Time object. + * The returned array is suitable for use as an argument 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"] */ static VALUE @@ -4876,189 +4859,11 @@ strftime_cstr(const char *fmt, size_t len, VALUE time, rb_encoding *enc) https://github.com/ruby/ruby/blob/trunk/time.c#L4859 /* * call-seq: - * time.strftime( string ) -> string - * - * Formats _time_ according to the directives in the given format string. - * - * The directives begin with a percent (%) character. - * Any text not listed as a directive will be passed through to the - * output string. - * - * The directive consists of a percent (%) character, - * zero or more flags, optional minimum field width, - * optional modifier and a conversion specifier - * as follows: - * - * %<flags><width><modifier><conversion> - * - * Flags: - * - don't pad a numerical output - * _ use spaces for padding - * 0 use zeros for padding - * ^ upcase the result string - * # change case - * : use colons for %z - * - * The minimum field width specifies the minimum width. - * - * The modifiers are "E" and "O". - * They are ignored. - * - * Format directives: - * - * Date (Year, Month, Day): - * %Y - Year with century if provided, will pad result at least 4 digits. - * -0001, 0000, 1995, 2009, 14292, etc. - * %C - year / 100 (rounded down such as 20 in 2009) - * %y - year % 100 (00..99) - * - * %m - Month of the year, zero-padded (01..12) - * %_m blank-padded ( 1..12) - * %-m no-padded (1..12) - * %B - The full month name (``January'') - * %^B uppercased (``JANUARY'') - * %b - The abbreviated month name (``Jan'') - * %^b uppercased (``JAN'') - * %h - Equivalent to %b - * - * %d - Day of the month, zero-padded (01..31) - * %-d no-padded (1..31) - * %e - Day of the month, blank-padded ( 1..31) - * - * %j - Day of the year (001..366) - * - * Time (Hour, Minute, Second, Subsecond): - * %H - Hour of the day, 24-hour clock, zero-padded (00..23) - * %k - Hour of the day, 24-hour clock, blank-padded ( 0..23) - * %I - Hour of the day, 12-hour clock, zero-padded (01..12) - * %l - Hour of the day, 12-hour clock, blank-padded ( 1..12) - * %P - Meridian indicator, lowercase (``am'' or ``pm'') - * %p - Meridian indicator, uppercase (``AM'' or ``PM'') - * - * %M - Minute of the hour (00..59) - * - * %S - Second of the minute (00..60) - * - * %L - Millisecond of the second (000..999) - * The digits under millisecond are truncated to not produce 1000. - * %N - Fractional seconds digits, default is 9 digits (nanosecond) - * %3N millisecond (3 digits) - * %6N microsecond (6 digits) - * %9N nanosecond (9 digits) - * %12N picosecond (12 digits) - * %15N femtosecond (15 digits) - * %18N attosecond (18 digits) - * %21N zeptosecond (21 digits) - * %24N yoctosecond (24 digits) - * The digits under the specified length are truncated to avoid - * carry up. - * - * Time zone: - * %z - Time zone as hour and minute offset from UTC (e.g. +0900) - * %:z - hour and minute offset from UTC with a colon (e.g. +09:00) - * %::z - hour, minute and second offset from UTC (e.g. +09:00:00) - * %Z - Abbreviated time zone name or similar information. (OS dependent) - * - * Weekday: - * %A - The full weekday name (``Sunday'') - * %^A uppercased (``SUNDAY'') - * %a - The abbreviated name (``Sun'') - * %^a uppercased (``SUN'') - * %u - Day of the week (Monday is 1, 1..7) - * %w - Day of the week (Sunday is 0, 0..6) - * - * ISO 8601 week-based year and week number: - * The first week of YYYY starts with a Monday and includes YYYY-01-04. - * The days in the year before the first week are in the last week of - * the previous year. - * %G - The week-based year - * %g - The last 2 digits of the week-based year (00..99) - * %V - Week number of the week-based year (01..53) - * - * Week number: - * The first week of YYYY that starts with a Sunday or Monday (according to %U - * or %W). The days in the year before the first week are in week 0. - * %U - Week number of the year. The week starts with Sunday. (00..53) - * %W - Week number of the year. The week starts with Monday. (00..53) - * - * Seconds since the Epoch: - * %s - Number of seconds since 1970-01-01 00:00:00 UTC. - * - * Literal string: - * %n - Newline character (\n) - * %t - Tab character (\t) - * %% - Literal ``%'' character - * - * Combination: - * %c - date and time (%a %b %e %T %Y) - * %D - Date (%m/%d/%y) - * %F - The ISO 8601 date format (%Y-%m-%d) - * %v - VMS date (%e-%^b-%4Y) - * %x - Same as %D - * %X - Same as %T - * %r - 12-hour time (%I:%M:%S %p) - * %R - 24-hour time (%H:%M) - * %T - 24-hour time (%H:%M:%S) - * - * This method (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/