diff --git a/doc/time/in.rdoc b/doc/time/in.rdoc deleted file mode 100644 index 506bd91628..0000000000 --- a/doc/time/in.rdoc +++ /dev/null @@ -1,4 +0,0 @@ -- in: zone: a timezone +zone+. - -For forms of argument +zone+, see -{Timezone Specifiers}[rdoc-ref:timezone_specifiers.rdoc]. diff --git a/doc/time/mon-min.rdoc b/doc/time/mon-min.rdoc deleted file mode 100644 index 5bd430c74a..0000000000 --- a/doc/time/mon-min.rdoc +++ /dev/null @@ -1,8 +0,0 @@ -- +month+: a month value, which may be: - - An integer month in the range 1..12. - - A 3-character string that matches regular expression - /jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec/i. -- +day+: an integer day in the range 1..31 - (less than 31 for some months). -- +hour+: an integer hour in the range 0..23. -- +min+: an integer minute in the range 0..59. diff --git a/doc/time/msec.rdoc b/doc/time/msec.rdoc deleted file mode 100644 index ce5d1e6145..0000000000 --- a/doc/time/msec.rdoc +++ /dev/null @@ -1,2 +0,0 @@ -- +msec+ is the number of milliseconds (Integer, Float, or Rational) - in the range 0..1000. diff --git a/doc/time/nsec.rdoc b/doc/time/nsec.rdoc deleted file mode 100644 index a2dfe2d608..0000000000 --- a/doc/time/nsec.rdoc +++ /dev/null @@ -1,2 +0,0 @@ -- +nsec+ is the number of nanoseconds (Integer, Float, or Rational) - in the range 0..1000000000. diff --git a/doc/time/sec.rdoc b/doc/time/sec.rdoc deleted file mode 100644 index 049c712110..0000000000 --- a/doc/time/sec.rdoc +++ /dev/null @@ -1,2 +0,0 @@ -- +sec+ is the number of seconds (Integer, Float, or Rational) - in the range 0..60. diff --git a/doc/time/sec_i.rdoc b/doc/time/sec_i.rdoc deleted file mode 100644 index fd5519082c..0000000000 --- a/doc/time/sec_i.rdoc +++ /dev/null @@ -1 +0,0 @@ -- +sec_i+ is the integer number of seconds in the range 0..60. diff --git a/doc/time/usec.rdoc b/doc/time/usec.rdoc deleted file mode 100644 index bb5a46419a..0000000000 --- a/doc/time/usec.rdoc +++ /dev/null @@ -1,2 +0,0 @@ -- +usec+ is the number of microseconds (Integer, Float, or Rational) - in the range 0..1000000. diff --git a/doc/time/year.rdoc b/doc/time/year.rdoc deleted file mode 100644 index 2222b830d7..0000000000 --- a/doc/time/year.rdoc +++ /dev/null @@ -1 +0,0 @@ -- +year+: an integer year. diff --git a/doc/time/zone_and_in.rdoc b/doc/time/zone_and_in.rdoc deleted file mode 100644 index f36940ee13..0000000000 --- a/doc/time/zone_and_in.rdoc +++ /dev/null @@ -1,5 +0,0 @@ -- +zone+: a timezone +zone+. -- in: zone: a timezone +zone+. - -For forms of +zone+, see -{Timezone Specifiers}[rdoc-ref:timezone_specifiers.rdoc]. diff --git a/time.c b/time.c index d2d0de91e5..505ab4835c 100644 --- a/time.c +++ b/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 diff --git a/timev.rb b/timev.rb index f477735875..ad97d63b55 100644 --- a/timev.rb +++ b/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+: # - # Seconds with Subseconds and Units + # - +: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 +in: zone 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