mirror of
https://github.com/ruby/ruby.git
synced 2022-11-09 12:17:21 -05:00
[DOC] Enhanced RDoc for Time (#6277)
Deletes the :include: files in doc/time, which became no longer workable when @nobu pointed out that some (but not all) creator methods accept string values as well as integer-like values.
Changes to methods:
Time.utc
Time.local
Time.at
Time.new
This commit is contained in:
Burdette Lamar
GitHub
parent
b2d0f78869
commit
8706b74b90
Notes:
git
2022-08-26 03:02:42 +09:00
Merged-By: BurdetteLamar <BurdetteLamar@Yahoo.com>
11 changed files with 209 additions and 118 deletions
|
|
@ -1,4 +0,0 @@
|
|||
- <tt>in: zone</tt>: a timezone +zone+.
|
||||
|
||||
For forms of argument +zone+, see
|
||||
{Timezone Specifiers}[rdoc-ref:timezone_specifiers.rdoc].
|
||||
|
|
@ -1,8 +0,0 @@
|
|||
- +month+: a month value, which may be:
|
||||
- An integer month in the range <tt>1..12</tt>.
|
||||
- A 3-character string that matches regular expression
|
||||
<tt>/jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec/i</tt>.
|
||||
- +day+: an integer day in the range <tt>1..31</tt>
|
||||
(less than 31 for some months).
|
||||
- +hour+: an integer hour in the range <tt>0..23</tt>.
|
||||
- +min+: an integer minute in the range <tt>0..59</tt>.
|
||||
|
|
@ -1,2 +0,0 @@
|
|||
- +msec+ is the number of milliseconds (Integer, Float, or Rational)
|
||||
in the range <tt>0..1000</tt>.
|
||||
|
|
@ -1,2 +0,0 @@
|
|||
- +nsec+ is the number of nanoseconds (Integer, Float, or Rational)
|
||||
in the range <tt>0..1000000000</tt>.
|
||||
|
|
@ -1,2 +0,0 @@
|
|||
- +sec+ is the number of seconds (Integer, Float, or Rational)
|
||||
in the range <tt>0..60</tt>.
|
||||
|
|
@ -1 +0,0 @@
|
|||
- +sec_i+ is the integer number of seconds in the range <tt>0..60</tt>.
|
||||
|
|
@ -1,2 +0,0 @@
|
|||
- +usec+ is the number of microseconds (Integer, Float, or Rational)
|
||||
in the range <tt>0..1000000</tt>.
|
||||
|
|
@ -1 +0,0 @@
|
|||
- +year+: an integer year.
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
- +zone+: a timezone +zone+.
|
||||
- <tt>in: zone</tt>: a timezone +zone+.
|
||||
|
||||
For forms of +zone+, see
|
||||
{Timezone Specifiers}[rdoc-ref:timezone_specifiers.rdoc].
|
||||
145
time.c
145
time.c
|
|
@ -3348,32 +3348,100 @@ tmcmp(struct tm *a, struct tm *b)
|
|||
|
||||
/*
|
||||
* call-seq:
|
||||
* Time.utc(year, month = 1, day = 1, hour = 0, min = 0, sec_i = 0, usec = 0) -> new_time
|
||||
* Time.utc(sec_i, min, hour, day, month, year, dummy, dummy, dummy, dummy) -> new_time
|
||||
* Time.utc(year, month = 1, mday = 1, hour = 0, min = 0, sec = 0, usec = 0) -> new_time
|
||||
* Time.utc(sec, min, hour, mday, month, year, dummy, dummy, dummy, dummy) -> new_time
|
||||
*
|
||||
* Returns a new \Time object based the on given arguments;
|
||||
* its timezone is UTC.
|
||||
* Returns a new \Time object based the on given arguments,
|
||||
* in the UTC timezone.
|
||||
*
|
||||
* In the first form (up to seven arguments), argument +year+ is required.
|
||||
* With one to seven arguments given,
|
||||
* the arguments are interpreted as in the first calling sequence above:
|
||||
*
|
||||
* Time.utc(2000) # => 2000-01-01 00:00:00 UTC
|
||||
* Time.utc(0, 1, 2, 3, 4, 5, 6.5) # => 0000-01-02 03:04:05.0000065 UTC
|
||||
* Time.utc(year, month = 1, mday = 1, hour = 0, min = 0, sec = 0, usec = 0)
|
||||
*
|
||||
* In the second form, all ten arguments are required,
|
||||
* though the last four are ignored.
|
||||
* This form is useful for creating a time from a 10-element array
|
||||
* such as is returned by #to_a.
|
||||
* Examples:
|
||||
*
|
||||
* array = Time.now.to_a
|
||||
* # => [55, 14, 10, 7, 7, 2022, 4, 188, true, "Central Daylight Time"]
|
||||
* array[5] = 2000
|
||||
* Time.utc(*array) # => 2000-07-07 10:14:55 UTC
|
||||
* Time.utc(2000) # => 2000-01-01 00:00:00 UTC
|
||||
* Time.utc(-2000) # => -2000-01-01 00:00:00 UTC
|
||||
*
|
||||
* Parameters:
|
||||
* :include: doc/time/year.rdoc
|
||||
* :include: doc/time/mon-min.rdoc
|
||||
* :include: doc/time/sec_i.rdoc
|
||||
* :include: doc/time/usec.rdoc
|
||||
* There are no minimum and maximum values for the required argument +year+.
|
||||
*
|
||||
* For the optional arguments:
|
||||
*
|
||||
* - +month+: Month in range (1..12), or case-insensitive
|
||||
* 3-letter month name:
|
||||
*
|
||||
* Time.utc(2000, 1) # => 2000-01-01 00:00:00 UTC
|
||||
* Time.utc(2000, 12) # => 2000-12-01 00:00:00 UTC
|
||||
* Time.utc(2000, 'jan') # => 2000-01-01 00:00:00 UTC
|
||||
* Time.utc(2000, 'JAN') # => 2000-01-01 00:00:00 UTC
|
||||
*
|
||||
* - +mday+: Month day in range(1..31):
|
||||
*
|
||||
* Time.utc(2000, 1, 1) # => 2000-01-01 00:00:00 UTC
|
||||
* Time.utc(2000, 1, 31) # => 2000-01-31 00:00:00 UTC
|
||||
*
|
||||
* - +hour+: Hour in range (0..23), or 24 if +min+, +sec+, and +usec+
|
||||
* are zero:
|
||||
*
|
||||
* Time.utc(2000, 1, 1, 0) # => 2000-01-01 00:00:00 UTC
|
||||
* Time.utc(2000, 1, 1, 23) # => 2000-01-01 23:00:00 UTC
|
||||
* Time.utc(2000, 1, 1, 24) # => 2000-01-02 00:00:00 UTC
|
||||
*
|
||||
* - +min+: Minute in range (0..59):
|
||||
*
|
||||
* Time.utc(2000, 1, 1, 0, 0) # => 2000-01-01 00:00:00 UTC
|
||||
* Time.utc(2000, 1, 1, 0, 59) # => 2000-01-01 00:59:00 UTC
|
||||
*
|
||||
* - +sec+: Second in range (0..59), or 60 if +usec+ is zero:
|
||||
*
|
||||
* Time.utc(2000, 1, 1, 0, 0, 0) # => 2000-01-01 00:00:00 UTC
|
||||
* Time.utc(2000, 1, 1, 0, 0, 59) # => 2000-01-01 00:00:59 UTC
|
||||
* Time.utc(2000, 1, 1, 0, 0, 60) # => 2000-01-01 00:01:00 UTC
|
||||
*
|
||||
* - +usec+: Microsecond in range (0..999999):
|
||||
*
|
||||
* Time.utc(2000, 1, 1, 0, 0, 0, 0) # => 2000-01-01 00:00:00 UTC
|
||||
* Time.utc(2000, 1, 1, 0, 0, 0, 999999) # => 2000-01-01 00:00:00.999999 UTC
|
||||
*
|
||||
* The values may be:
|
||||
*
|
||||
* - Integers, as above.
|
||||
* - Numerics convertible to integers:
|
||||
*
|
||||
* Time.utc(Float(0.0), Rational(1, 1), 1.0, 0.0, 0.0, 0.0, 0.0)
|
||||
* # => 0000-01-01 00:00:00 UTC
|
||||
*
|
||||
* - \String integers:
|
||||
*
|
||||
* a = %w[0 1 1 0 0 0 0 0]
|
||||
* # => ["0", "1", "1", "0", "0", "0", "0", "0"]
|
||||
* Time.utc(*a) # => 0000-01-01 00:00:00 UTC
|
||||
*
|
||||
* When exactly ten arguments are given,
|
||||
* the arguments are interpreted as in the second calling sequence above:
|
||||
*
|
||||
* Time.utc(sec, min, hour, mday, month, year, dummy, dummy, dummy, dummy)
|
||||
*
|
||||
* where the +dummy+ arguments are ignored:
|
||||
*
|
||||
* a = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
|
||||
* # => [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
|
||||
* Time.utc(*a) # => 0005-04-03 02:01:00 UTC
|
||||
*
|
||||
* This form is useful for creating a \Time object from a 10-element
|
||||
* array returned by Time.to_a:
|
||||
*
|
||||
* t = Time.new(2000, 1, 2, 3, 4, 5, 6) # => 2000-01-02 03:04:05 +000006
|
||||
* a = t.to_a # => [5, 4, 3, 2, 1, 2000, 0, 2, false, nil]
|
||||
* Time.utc(*a) # => 2000-01-02 03:04:05 UTC
|
||||
*
|
||||
* The two forms have their first six arguments in common,
|
||||
* though in different orders;
|
||||
* the ranges of these common arguments are the same for both forms; see above.
|
||||
*
|
||||
* Raises an exception if the number of arguments is eight, nine,
|
||||
* or greater than ten.
|
||||
*
|
||||
* Time.gm is an alias for Time.utc.
|
||||
*
|
||||
|
|
@ -3391,36 +3459,19 @@ time_s_mkutc(int argc, VALUE *argv, VALUE klass)
|
|||
|
||||
/*
|
||||
* call-seq:
|
||||
* Time.local(year, month = 1, day = 1, hour = 0, min = 0, sec_i = 0, usec = 0) -> new_time
|
||||
* Time.local(sec, min, hour, day, month, year, dummy, dummy, dummy, dummy) -> new_time
|
||||
* Time.local(year, month = 1, mday = 1, hour = 0, min = 0, sec = 0, usec = 0) -> new_time
|
||||
* Time.local(sec, min, hour, mday, month, year, dummy, dummy, dummy, dummy) -> new_time
|
||||
*
|
||||
* Returns a new \Time object based the on given arguments;
|
||||
* its timezone is the local timezone.
|
||||
* Like Time.utc, except that the returned \Time object
|
||||
* has the local timezone, not the UTC timezone:
|
||||
*
|
||||
* In the first form (up to seven arguments), argument +year+ is required.
|
||||
* # With seven arguments.
|
||||
* Time.local(0, 1, 2, 3, 4, 5, 6)
|
||||
* # => 0000-01-02 03:04:05.000006 -0600
|
||||
* # With exactly ten arguments.
|
||||
* Time.local(0, 1, 2, 3, 4, 5, 6, 7, 8, 9)
|
||||
* # => 0005-04-03 02:01:00 -0600
|
||||
*
|
||||
* Time.local(2000) # => 2000-01-01 00:00:00 -0600
|
||||
* Time.local(0, 1, 2, 3, 4, 5, 6.5) # => 0000-01-02 03:04:05.0000065 -0600
|
||||
*
|
||||
* In the second form, all ten arguments are required,
|
||||
* though the last four are ignored.
|
||||
* This form is useful for creating a time from a 10-element array
|
||||
* such as those returned by #to_a.
|
||||
*
|
||||
* array = Time.now.to_a
|
||||
* # => [57, 18, 10, 7, 7, 2022, 4, 188, true, "Central Daylight Time"]
|
||||
* array[5] = 2000
|
||||
* Time.local(*array) # => 2000-07-07 10:18:57 -0500
|
||||
*
|
||||
* Parameters:
|
||||
* :include: doc/time/year.rdoc
|
||||
* :include: doc/time/mon-min.rdoc
|
||||
* :include: doc/time/sec_i.rdoc
|
||||
* :include: doc/time/usec.rdoc
|
||||
*
|
||||
* Time.mktime is an alias for Time.local.
|
||||
*
|
||||
* Related: Time.utc.
|
||||
*/
|
||||
|
||||
static VALUE
|
||||
|
|
|
|||
155
timev.rb
155
timev.rb
|
|
@ -223,48 +223,58 @@ class Time
|
|||
Primitive.time_s_now(Primitive.arg!(:in))
|
||||
end
|
||||
|
||||
# _Time_
|
||||
# Returns a new \Time object based on the given arguments.
|
||||
#
|
||||
# This form accepts a \Time object +time+
|
||||
# and optional keyword argument +in+:
|
||||
# Required argument +time+ may be either of:
|
||||
#
|
||||
# Time.at(Time.new) # => 2021-04-26 08:52:31.6023486 -0500
|
||||
# Time.at(Time.new, in: '+09:00') # => 2021-04-26 22:52:31.6023486 +0900
|
||||
# - A \Time object, whose value is the basis for the returned time;
|
||||
# also influenced by optional keyword argument +in:+ (see below).
|
||||
# - A numeric number of seconds (since the epoch) for the returned time.
|
||||
#
|
||||
# _Seconds_
|
||||
# Examples:
|
||||
#
|
||||
# This form accepts a numeric number of seconds +sec+
|
||||
# and optional keyword argument +in+:
|
||||
# t = Time.new(2000, 12, 31, 23, 59, 59) # => 2000-12-31 23:59:59 -0600
|
||||
# secs = t.to_i # => 978328799
|
||||
# Time.at(secs) # => 2000-12-31 23:59:59 -0600
|
||||
# Time.at(secs + 0.5) # => 2000-12-31 23:59:59.5 -0600
|
||||
# Time.at(1000000000) # => 2001-09-08 20:46:40 -0500
|
||||
# Time.at(0) # => 1969-12-31 18:00:00 -0600
|
||||
# Time.at(-1000000000) # => 1938-04-24 17:13:20 -0500
|
||||
#
|
||||
# Time.at(946702800) # => 1999-12-31 23:00:00 -0600
|
||||
# Time.at(946702800, in: '+09:00') # => 2000-01-01 14:00:00 +0900
|
||||
# Optional numeric argument +subsec+ and optional symbol argument +units+
|
||||
# work together to specify subseconds for the returned time;
|
||||
# argument +units+ specifies the units for +subsec+:
|
||||
#
|
||||
# <em>Seconds with Subseconds and Units</em>
|
||||
# - +:millisecond+: +subsec+ in milliseconds:
|
||||
#
|
||||
# This form accepts an integer number of seconds +sec_i+,
|
||||
# a numeric number of milliseconds +msec+,
|
||||
# a symbol argument for the subsecond unit type (defaulting to :usec),
|
||||
# and an optional keyword argument +in+:
|
||||
# Time.at(secs, 0, :millisecond) # => 2000-12-31 23:59:59 -0600
|
||||
# Time.at(secs, 500, :millisecond) # => 2000-12-31 23:59:59.5 -0600
|
||||
# Time.at(secs, 1000, :millisecond) # => 2001-01-01 00:00:00 -0600
|
||||
# Time.at(secs, -1000, :millisecond) # => 2000-12-31 23:59:58 -0600
|
||||
#
|
||||
# Time.at(946702800, 500, :millisecond) # => 1999-12-31 23:00:00.5 -0600
|
||||
# Time.at(946702800, 500, :millisecond, in: '+09:00') # => 2000-01-01 14:00:00.5 +0900
|
||||
# Time.at(946702800, 500000) # => 1999-12-31 23:00:00.5 -0600
|
||||
# Time.at(946702800, 500000, :usec) # => 1999-12-31 23:00:00.5 -0600
|
||||
# Time.at(946702800, 500000, :microsecond) # => 1999-12-31 23:00:00.5 -0600
|
||||
# Time.at(946702800, 500000, in: '+09:00') # => 2000-01-01 14:00:00.5 +0900
|
||||
# Time.at(946702800, 500000, :usec, in: '+09:00') # => 2000-01-01 14:00:00.5 +0900
|
||||
# Time.at(946702800, 500000, :microsecond, in: '+09:00') # => 2000-01-01 14:00:00.5 +0900
|
||||
# Time.at(946702800, 500000000, :nsec) # => 1999-12-31 23:00:00.5 -0600
|
||||
# Time.at(946702800, 500000000, :nanosecond) # => 1999-12-31 23:00:00.5 -0600
|
||||
# Time.at(946702800, 500000000, :nsec, in: '+09:00') # => 2000-01-01 14:00:00.5 +0900
|
||||
# Time.at(946702800, 500000000, :nanosecond, in: '+09:00') # => 2000-01-01 14:00:00.5 +0900
|
||||
# - +:microsecond+ or +:usec+: +subsec+ in microseconds:
|
||||
#
|
||||
# Parameters:
|
||||
# :include: doc/time/sec_i.rdoc
|
||||
# :include: doc/time/msec.rdoc
|
||||
# :include: doc/time/usec.rdoc
|
||||
# :include: doc/time/nsec.rdoc
|
||||
# :include: doc/time/in.rdoc
|
||||
# Time.at(secs, 0, :microsecond) # => 2000-12-31 23:59:59 -0600
|
||||
# Time.at(secs, 500000, :microsecond) # => 2000-12-31 23:59:59.5 -0600
|
||||
# Time.at(secs, 1000000, :microsecond) # => 2001-01-01 00:00:00 -0600
|
||||
# Time.at(secs, -1000000, :microsecond) # => 2000-12-31 23:59:58 -0600
|
||||
#
|
||||
# - +:nsec+ or +:nanosecond+: +subsec+ in nanoseconds:
|
||||
#
|
||||
# Time.at(secs, 0, :nanosecond) # => 2000-12-31 23:59:59 -0600
|
||||
# Time.at(secs, 500000000, :nanosecond) # => 2000-12-31 23:59:59.5 -0600
|
||||
# Time.at(secs, 1000000000, :nanosecond) # => 2001-01-01 00:00:00 -0600
|
||||
# Time.at(secs, -1000000000, :nanosecond) # => 2000-12-31 23:59:58 -0600
|
||||
#
|
||||
#
|
||||
# Optional keyword argument <tt>+in: zone</tt> specifies the timezone
|
||||
# for the returned time:
|
||||
#
|
||||
# Time.at(secs, in: '+12:00') # => 2001-01-01 17:59:59 +1200
|
||||
# Time.at(secs, in: '-12:00') # => 2000-12-31 17:59:59 -1200
|
||||
#
|
||||
# For the forms of argument +zone+, see
|
||||
# {Timezone Specifiers}[rdoc-ref:timezone_specifiers.rdoc].
|
||||
#
|
||||
def self.at(time, subsec = false, unit = :microsecond, in: nil)
|
||||
if Primitive.mandatory_only?
|
||||
|
|
@ -274,24 +284,81 @@ class Time
|
|||
end
|
||||
end
|
||||
|
||||
# Returns a new \Time object based on the given arguments.
|
||||
# Returns a new \Time object based on the given arguments,
|
||||
# by default in the local timezone.
|
||||
#
|
||||
# With no positional arguments, returns the value of Time.now:
|
||||
#
|
||||
# Time.new # => 2021-04-24 17:27:46.0512465 -0500
|
||||
# Time.new # => 2021-04-24 17:27:46.0512465 -0500
|
||||
#
|
||||
# Otherwise, returns a new \Time object based on the given parameters:
|
||||
# With one to six arguments, returns a new \Time object
|
||||
# based on the given arguments, in the local timezone.
|
||||
#
|
||||
# Time.new(2000) # => 2000-01-01 00:00:00 -0600
|
||||
# Time.new(2000, 12, 31, 23, 59, 59.5) # => 2000-12-31 23:59:59.5 -0600
|
||||
# Time.new(2000, 12, 31, 23, 59, 59.5, '+09:00') # => 2000-12-31 23:59:59.5 +0900
|
||||
# Time.new(2000, 1, 2, 3, 4, 5) # => 2000-01-02 03:04:05 -0600
|
||||
#
|
||||
# Parameters:
|
||||
# For the positional arguments (other than +zone+):
|
||||
#
|
||||
# :include: doc/time/year.rdoc
|
||||
# :include: doc/time/mon-min.rdoc
|
||||
# :include: doc/time/sec.rdoc
|
||||
# :include: doc/time/zone_and_in.rdoc
|
||||
# - +year+: Year, with no range limits:
|
||||
#
|
||||
# Time.new(999999999) # => 999999999-01-01 00:00:00 -0600
|
||||
# Time.new(-999999999) # => -999999999-01-01 00:00:00 -0600
|
||||
#
|
||||
# - +month+: Month in range (1..12), or case-insensitive
|
||||
# 3-letter month name:
|
||||
#
|
||||
# Time.new(2000, 1) # => 2000-01-01 00:00:00 -0600
|
||||
# Time.new(2000, 12) # => 2000-12-01 00:00:00 -0600
|
||||
# Time.new(2000, 'jan') # => 2000-01-01 00:00:00 -0600
|
||||
# Time.new(2000, 'JAN') # => 2000-01-01 00:00:00 -0600
|
||||
#
|
||||
# - +mday+: Month day in range(1..31):
|
||||
#
|
||||
# Time.new(2000, 1, 1) # => 2000-01-01 00:00:00 -0600
|
||||
# Time.new(2000, 1, 31) # => 2000-01-31 00:00:00 -0600
|
||||
#
|
||||
# - +hour+: Hour in range (0..23), or 24 if +min+, +sec+, and +usec+
|
||||
# are zero:
|
||||
#
|
||||
# Time.new(2000, 1, 1, 0) # => 2000-01-01 00:00:00 -0600
|
||||
# Time.new(2000, 1, 1, 23) # => 2000-01-01 23:00:00 -0600
|
||||
# Time.new(2000, 1, 1, 24) # => 2000-01-02 00:00:00 -0600
|
||||
#
|
||||
# - +min+: Minute in range (0..59):
|
||||
#
|
||||
# Time.new(2000, 1, 1, 0, 0) # => 2000-01-01 00:00:00 -0600
|
||||
# Time.new(2000, 1, 1, 0, 59) # => 2000-01-01 00:59:00 -0600
|
||||
#
|
||||
# - +sec+: Second in range (0..59), or 60 if +usec+ is zero:
|
||||
#
|
||||
# Time.new(2000, 1, 1, 0, 0, 0) # => 2000-01-01 00:00:00 -0600
|
||||
# Time.new(2000, 1, 1, 0, 0, 59) # => 2000-01-01 00:00:59 -0600
|
||||
# Time.new(2000, 1, 1, 0, 0, 60) # => 2000-01-01 00:01:00 -0600
|
||||
#
|
||||
# These values may be:
|
||||
#
|
||||
# - Integers, as above.
|
||||
# - Numerics convertible to integers:
|
||||
#
|
||||
# Time.new(Float(0.0), Rational(1, 1), 1.0, 0.0, 0.0, 0.0)
|
||||
# # => 0000-01-01 00:00:00 -0600
|
||||
#
|
||||
# - \String integers:
|
||||
#
|
||||
# a = %w[0 1 1 0 0 0]
|
||||
# # => ["0", "1", "1", "0", "0", "0"]
|
||||
# Time.new(*a) # => 0000-01-01 00:00:00 -0600
|
||||
#
|
||||
# When positional argument +zone+ or keyword argument +in:+ is given,
|
||||
# the new \Time object is in the specified timezone.
|
||||
# For the forms of argument +zone+, see
|
||||
# {Timezone Specifiers}[rdoc-ref:timezone_specifiers.rdoc]:
|
||||
#
|
||||
# Time.new(2000, 1, 1, 0, 0, 0, '+12:00')
|
||||
# # => 2000-01-01 00:00:00 +1200
|
||||
# Time.new(2000, 1, 1, 0, 0, 0, in: '-12:00')
|
||||
# # => 2000-01-01 00:00:00 -1200
|
||||
# Time.new(in: '-12:00')
|
||||
# # => 2022-08-23 08:49:26.1941467 -1200
|
||||
#
|
||||
def initialize(year = (now = true), mon = nil, mday = nil, hour = nil, min = nil, sec = nil, zone = nil, in: nil)
|
||||
if zone
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue