1berry/ruby
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

[DOC] Enhanced RDoc for Time (#6320)

Browse Source 
Treats:
    #yday
    #dst?
    #zone
    #to_a
    #strftime
This commit is contained in:
Burdette Lamar 2022-09-03 08:36:44 -05:00 committed by GitHub
parent 2767cb2825
commit fe865c5262
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
Notes: git 2022-09-03 22:37:08 +09:00 
Merged-By: BurdetteLamar <BurdetteLamar@Yahoo.com>
1 changed files with 33 additions and 228 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

261
time.c
View File

@ -4685,12 +4685,12 @@ time_saturday(VALUE time)
/*
* 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)
/*
* call-seq:
* time.isdst -> true or false
* time.dst? -> true or false
* dst? -> true or false
*
* Returns +true+ if _time_ occurs during Daylight
* Saving Time in its time zone.
* Returns +true+ if +self+ is in daylight saving time, +false+ otherwise:
*
* # 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
* 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
*
* # 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
* Time#isdst is an alias for Time#dst?.
*/
static VALUE
@ -4745,13 +4736,10 @@ time_isdst(VALUE time)
* 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)
/*
* call-seq:
* time.gmt_offset -> integer
* time.gmtoff -> integer
* time.utc_offset -> integer
* utc_offset -> integer
*
* Returns the offset in seconds between the timezone of _time_
* and UTC.
* Returns the offset in seconds between the timezones of UTC and +self+:
*
* 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.utc(2000, 1, 1).utc_offset # => 0
* Time.local(2000, 1, 1).utc_offset # => -21600 # -6*3600, or minus six hours.
*
* Time#gmt_offset and Time#gmtoff are aliases for Time#utc_offset.
*/
VALUE
@ -4808,19 +4793,17 @@ rb_time_utc_offset(VALUE time)
/*
* 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)
/*
* 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 is similar to strftime() function defined in ISO C and POSIX.
*
* While all directives are locale independent since Ruby 1.9, %Z is platform
* dependent.
* So, the result may differ even if the same format string is used in other
* systems such as C.
*
* %z is recommended over %Z.
* %Z doesn't identify the timezone.
* For example, "CST" is used at America/Chicago (-06:00),
* America/Havana (-05:00), Asia/Harbin (+08:00), Australia/Darwin (+09:30)
* and Australia/Adelaide (+10:30).
* Also, %Z is highly dependent on the operating system.
* For example, it may generate a non ASCII string on Japanese Windows,
* i.e. the result can be different to "JST".
* So the numeric time zone offset, %z, is recommended.
*
* Examples:
*
* t = Time.new(2007,11,19,8,37,48,"-06:00") #=> 2007-11-19 08:37:48 -0600
* t.strftime("Printed on %m/%d/%Y") #=> "Printed on 11/19/2007"
* t.strftime("at %I:%M %p") #=> "at 08:37 AM"
*
* Various ISO 8601 formats:
* %Y%m%d => 20071119 Calendar date (basic)
* %F => 2007-11-19 Calendar date (extended)
* %Y-%m => 2007-11 Calendar date, reduced accuracy, specific month
* %Y => 2007 Calendar date, reduced accuracy, specific year
* %C => 20 Calendar date, reduced accuracy, specific century
* %Y%j => 2007323 Ordinal date (basic)
* %Y-%j => 2007-323 Ordinal date (extended)
* %GW%V%u => 2007W471 Week date (basic)
* %G-W%V-%u => 2007-W47-1 Week date (extended)
* %GW%V => 2007W47 Week date, reduced accuracy, specific week (basic)
* %G-W%V => 2007-W47 Week date, reduced accuracy, specific week (extended)
* %H%M%S => 083748 Local time (basic)
* %T => 08:37:48 Local time (extended)
* %H%M => 0837 Local time, reduced accuracy, specific minute (basic)
* %H:%M => 08:37 Local time, reduced accuracy, specific minute (extended)
* %H => 08 Local time, reduced accuracy, specific hour
* %H%M%S,%L => 083748,000 Local time with decimal fraction, comma as decimal sign (basic)
* %T,%L => 08:37:48,000 Local time with decimal fraction, comma as decimal sign (extended)
* %H%M%S.%L => 083748.000 Local time with decimal fraction, full stop as decimal sign (basic)
* %T.%L => 08:37:48.000 Local time with decimal fraction, full stop as decimal sign (extended)
* %H%M%S%z => 083748-0600 Local time and the difference from UTC (basic)
* %T%:z => 08:37:48-06:00 Local time and the difference from UTC (extended)
* %Y%m%dT%H%M%S%z => 20071119T083748-0600 Date and time of day for calendar date (basic)
* %FT%T%:z => 2007-11-19T08:37:48-06:00 Date and time of day for calendar date (extended)
* %Y%jT%H%M%S%z => 2007323T083748-0600 Date and time of day for ordinal date (basic)
* %Y-%jT%T%:z => 2007-323T08:37:48-06:00 Date and time of day for ordinal date (extended)
* %GW%V%uT%H%M%S%z => 2007W471T083748-0600 Date and time of day for week date (basic)
* %G-W%V-%uT%T%:z => 2007-W47-1T08:37:48-06:00 Date and time of day for week date (extended)
* %Y%m%dT%H%M => 20071119T0837 Calendar date and local time (basic)
* %FT%R => 2007-11-19T08:37 Calendar date and local time (extended)
* %Y%jT%H%MZ => 2007323T0837Z Ordinal date and UTC of day (basic)
* %Y-%jT%RZ => 2007-323T08:37Z Ordinal date and UTC of day (extended)
* %GW%V%uT%H%M%z => 2007W471T0837-0600 Week date and local time and difference from UTC (basic)
* %G-W%V-%uT%R%:z => 2007-W47-1T08:37-06:00 Week date and local time and difference from UTC (extended)
* strftime(format_string) -> string
*
* Returns a string representation of +self+,
* formatted according to the given string +format+.
* See {Formats for Dates and Times}[rdoc-ref:doc/strftime_formatting.rdoc].
*/
static VALUE