rbs 2.8.4 → 3.8.1

data/core/time.rbs

@@ -1,23 +1,91 @@
 # <!-- rdoc-file=timev.rb -->
-# Time is an abstraction of dates and times. Time is stored internally as the
-# number of seconds with subsecond since the *Epoch*, 1970-01-01 00:00:00 UTC.
+# A `Time` object represents a date and time:
 #
-# 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.
+#     Time.new(2000, 1, 1, 0, 0, 0) # => 2000-01-01 00:00:00 -0600
 #
-# Note: A Time object uses the resolution available on your system clock.
+# Although its value can be expressed as a single numeric (see [Epoch
+# Seconds](rdoc-ref:Time@Epoch+Seconds) below), it can be convenient to deal
+# with the value by parts:
 #
-# All times may have subsecond. Be aware of this fact when comparing times with
-# each other -- times that are apparently equal when displayed may be different
-# when compared. (Since Ruby 2.7.0, Time#inspect shows subsecond but Time#to_s
-# still doesn't show subsecond.)
+#     t = Time.new(-2000, 1, 1, 0, 0, 0.0)
+#     # => -2000-01-01 00:00:00 -0600
+#     t.year # => -2000
+#     t.month # => 1
+#     t.mday # => 1
+#     t.hour # => 0
+#     t.min # => 0
+#     t.sec # => 0
+#     t.subsec # => 0
+#
+#     t = Time.new(2000, 12, 31, 23, 59, 59.5)
+#     # => 2000-12-31 23:59:59.5 -0600
+#     t.year # => 2000
+#     t.month # => 12
+#     t.mday # => 31
+#     t.hour # => 23
+#     t.min # => 59
+#     t.sec # => 59
+#     t.subsec # => (1/2)
+#
+# ## Epoch Seconds
+#
+# *Epoch seconds* is the exact number of seconds (including fractional
+# subseconds) since the Unix Epoch, January 1, 1970.
+#
+# You can retrieve that value exactly using method Time.to_r:
+#
+#     Time.at(0).to_r        # => (0/1)
+#     Time.at(0.999999).to_r # => (9007190247541737/9007199254740992)
+#
+# Other retrieval methods such as Time#to_i and Time#to_f may return a value
+# that rounds or truncates subseconds.
+#
+# ## Time Resolution
+#
+# A `Time` object derived from the system clock (for example, by method
+# Time.now) has the resolution supported by the system.
+#
+# ## Time Internal Representation
+#
+# Time implementation uses a signed 63 bit integer, Integer, or Rational. It is
+# a number of nanoseconds since the *Epoch*. The signed 63 bit integer can
+# represent 1823-11-12 to 2116-02-20. When Integer or Rational is used (before
+# 1823, after 2116, under nanosecond), Time works slower than when the signed 63
+# bit integer is used.
+#
+# Ruby uses the C function `localtime` and `gmtime` to map between the number
+# and 6-tuple (year,month,day,hour,minute,second). `localtime` is used for local
+# time and "gmtime" is used for UTC.
+#
+# Integer and Rational has no range limit, but the localtime and gmtime has
+# range limits due to the C types `time_t` and `struct tm`. If that limit is
+# exceeded, Ruby extrapolates the localtime function.
+#
+# The Time class always uses the Gregorian calendar. I.e. the proleptic
+# Gregorian calendar is used. Other calendars, such as Julian calendar, are not
+# supported.
+#
+# `time_t` can represent 1901-12-14 to 2038-01-19 if it is 32 bit signed
+# integer, -292277022657-01-27 to 292277026596-12-05 if it is 64 bit signed
+# integer. However `localtime` on some platforms doesn't supports negative
+# `time_t` (before 1970).
+#
+# `struct tm` has *tm_year* member to represent years. (`tm_year = 0` means the
+# year 1900.) It is defined as `int` in the C standard. *tm_year* can represent
+# between -2147481748 to 2147485547 if `int` is 32 bit.
+#
+# Ruby supports leap seconds as far as if the C function `localtime` and
+# `gmtime` supports it. They use the tz database in most Unix systems. The tz
+# database has timezones which supports leap seconds. For example, "Asia/Tokyo"
+# doesn't support leap seconds but "right/Asia/Tokyo" supports leap seconds. So,
+# Ruby supports leap seconds if the TZ environment variable is set to
+# "right/Asia/Tokyo" in most Unix systems.
 #
 # ## Examples
 #
 # All of these examples were done using the EST timezone which is GMT-5.
 #
-# ### Creating a New Time Instance
+# ### 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 an alias for this. You can also pass parts of the
@@ -34,7 +102,7 @@
 #
 #     Time.new(2002, 10, 31, 2, 2, 2, "+02:00") #=> 2002-10-31 02:02:02 +0200
 #
-# Or a timezone object:
+# Or [a timezone object](rdoc-ref:Time@Timezone+Objects):
 #
 #     zone = timezone("Europe/Athens")      # Eastern European Time, UTC+2
 #     Time.new(2002, 10, 31, 2, 2, 2, zone) #=> 2002-10-31 02:02:02 +0200
@@ -48,7 +116,7 @@
 #
 #     Time.at(628232400) #=> 1989-11-28 00:00:00 -0500
 #
-# ### Working with an Instance of Time
+# ### 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 will
@@ -90,23 +158,19 @@
 #
 # ## What's Here
 #
-# First, what's elsewhere. Class Time:
-#
-# *   Inherits from [class
-#     Object](Object.html#class-Object-label-What-27s+Here).
-# *   Includes [module
-#     Comparable](Comparable.html#module-Comparable-label-What-27s+Here).
+# First, what's elsewhere. Class `Time`:
 #
+# *   Inherits from [class Object](rdoc-ref:Object@What-27s+Here).
+# *   Includes [module Comparable](rdoc-ref:Comparable@What-27s+Here).
 #
-# Here, class Time provides methods that are useful for:
-#
-# *   [Creating \Time objects](#class-Time-label-Methods+for+Creating).
-# *   [Fetching \Time values](#class-Time-label-Methods+for+Fetching).
-# *   [Querying a \Time object](#class-Time-label-Methods+for+Querying).
-# *   [Comparing \Time objects](#class-Time-label-Methods+for+Comparing).
-# *   [Converting a \Time object](#class-Time-label-Methods+for+Converting).
-# *   [Rounding a \Time](#class-Time-label-Methods+for+Rounding).
+# Here, class `Time` provides methods that are useful for:
 #
+# *   [Creating Time objects](rdoc-ref:Time@Methods+for+Creating).
+# *   [Fetching Time values](rdoc-ref:Time@Methods+for+Fetching).
+# *   [Querying a Time object](rdoc-ref:Time@Methods+for+Querying).
+# *   [Comparing Time objects](rdoc-ref:Time@Methods+for+Comparing).
+# *   [Converting a Time object](rdoc-ref:Time@Methods+for+Converting).
+# *   [Rounding a Time](rdoc-ref:Time@Methods+for+Rounding).
 #
 # ### Methods for Creating
 #
@@ -118,9 +182,7 @@
 # *   ::at: Returns a new time based on seconds since epoch.
 # *   ::now: Returns a new time based on the current system time.
 # *   #+ (plus): Returns a new time increased by the given number of seconds.
-# *   [-](#method-i-2D) (minus): Returns a new time
-#         decreased by the given number of seconds.
-#
+# *   #- (minus): Returns a new time decreased by the given number of seconds.
 #
 # ### Methods for Fetching
 #
@@ -146,7 +208,6 @@
 # *   #to_r: Returns the Rational number of seconds since epoch for the time.
 # *   #zone: Returns a string representation of the timezone of the time.
 #
-#
 # ### Methods for Querying
 #
 # *   #utc? (aliased as #gmt?): Returns whether the time is UTC.
@@ -160,13 +221,11 @@
 # *   #friday?: Returns whether time is a Friday.
 # *   #saturday?: Returns whether the time is a Saturday.
 #
-#
 # ### Methods for Comparing
 #
-# *   [#<=>](#method-i-3C-3D-3E): Compares `self` to another time.
+# *   #<=>: Compares `self` to another time.
 # *   #eql?: Returns whether the time is equal to another time.
 #
-#
 # ### Methods for Converting
 #
 # *   #asctime (aliased as #ctime): Returns the time as a string.
@@ -178,7 +237,8 @@
 # *   #getlocal: Returns a new time converted to local time.
 # *   #utc (aliased as #gmtime): Converts time to UTC in place.
 # *   #localtime: Converts time to local time in place.
-#
+# *   #deconstruct_keys: Returns a hash of time components used in
+#     pattern-matching.
 #
 # ### Methods for Rounding
 #
@@ -186,95 +246,273 @@
 # *   #ceil: Returns a new time with subseconds raised to a ceiling.
 # *   #floor: Returns a new time with subseconds lowered to a floor.
 #
+# For the forms of argument `zone`, see [Timezone
+# Specifiers](rdoc-ref:Time@Timezone+Specifiers).
+#
+# ## Timezone Specifiers
+#
+# Certain `Time` methods accept arguments that specify timezones:
+#
+# *   Time.at: keyword argument `in:`.
+# *   Time.new: positional argument `zone` or keyword argument `in:`.
+# *   Time.now: keyword argument `in:`.
+# *   Time#getlocal: positional argument `zone`.
+# *   Time#localtime: positional argument `zone`.
+#
+# The value given with any of these must be one of the following (each detailed
+# below):
+#
+# *   [Hours/minutes offset](rdoc-ref:Time@Hours-2FMinutes+Offsets).
+# *   [Single-letter offset](rdoc-ref:Time@Single-Letter+Offsets).
+# *   [Integer offset](rdoc-ref:Time@Integer+Offsets).
+# *   [Timezone object](rdoc-ref:Time@Timezone+Objects).
+# *   [Timezone name](rdoc-ref:Time@Timezone+Names).
+#
+# ### Hours/Minutes Offsets
+#
+# The zone value may be a string offset from UTC in the form `'+HH:MM'` or
+# `'-HH:MM'`, where:
+#
+# *   `HH` is the 2-digit hour in the range `0..23`.
+# *   `MM` is the 2-digit minute in the range `0..59`.
+#
+# Examples:
+#
+#     t = Time.utc(2000, 1, 1, 20, 15, 1) # => 2000-01-01 20:15:01 UTC
+#     Time.at(t, in: '-23:59')            # => 1999-12-31 20:16:01 -2359
+#     Time.at(t, in: '+23:59')            # => 2000-01-02 20:14:01 +2359
+#
+# ### Single-Letter Offsets
+#
+# The zone value may be a  letter in the range `'A'..'I'` or `'K'..'Z'`; see
+# [List of military time
+# zones](https://en.wikipedia.org/wiki/List_of_military_time_zones):
+#
+#     t = Time.utc(2000, 1, 1, 20, 15, 1) # => 2000-01-01 20:15:01 UTC
+#     Time.at(t, in: 'A')                 # => 2000-01-01 21:15:01 +0100
+#     Time.at(t, in: 'I')                 # => 2000-01-02 05:15:01 +0900
+#     Time.at(t, in: 'K')                 # => 2000-01-02 06:15:01 +1000
+#     Time.at(t, in: 'Y')                 # => 2000-01-01 08:15:01 -1200
+#     Time.at(t, in: 'Z')                 # => 2000-01-01 20:15:01 UTC
+#
+# ### Integer Offsets
+#
+# The zone value may be an integer number of seconds in the range
+# `-86399..86399`:
+#
+#     t = Time.utc(2000, 1, 1, 20, 15, 1) # => 2000-01-01 20:15:01 UTC
+#     Time.at(t, in: -86399)              # => 1999-12-31 20:15:02 -235959
+#     Time.at(t, in: 86399)               # => 2000-01-02 20:15:00 +235959
+#
+# ### Timezone Objects
+#
+# The zone value may be an object responding to certain timezone methods, an
+# instance of [Timezone](https://github.com/panthomakos/timezone) and
+# [TZInfo](https://tzinfo.github.io) for example.
+#
+# The timezone methods are:
+#
+# *   `local_to_utc`:
+#
+#     Called when Time.new is invoked with `tz` as the value of positional
+#     argument `zone` or keyword argument `in:`.
+#
+#     Argument
+# :       a [Time-like object](rdoc-ref:Time@Time-Like+Objects).
+#
+#     Returns
+# :       a [Time-like object](rdoc-ref:Time@Time-Like+Objects) in the UTC
+#         timezone.
+#
+#
+# *   `utc_to_local`:
+#
+#     Called when Time.at or Time.now is invoked with `tz` as the value for
+#     keyword argument `in:`, and when Time#getlocal or Time#localtime is called
+#     with `tz` as the value for positional argument `zone`.
+#
+#     The UTC offset will be calculated as the difference between the original
+#     time and the returned object as an `Integer`. If the object is in fixed
+#     offset, its `utc_offset` is also counted.
+#
+#     Argument
+# :       a [Time-like object](rdoc-ref:Time@Time-Like+Objects).
+#
+#     Returns
+# :       a [Time-like object](rdoc-ref:Time@Time-Like+Objects) in the local
+#         timezone.
+#
+#
+# A custom timezone class may have these instance methods, which will be called
+# if defined:
+#
+# *   `abbr`:
+#
+#     Called when Time#strftime is invoked with a format involving `%Z`.
+#
+#     Argument
+# :       a [Time-like object](rdoc-ref:Time@Time-Like+Objects).
+#
+#     Returns
+# :       a string abbreviation for the timezone name.
+#
+#
+# *   `dst?`:
+#
+#     Called when Time.at or Time.now is invoked with `tz` as the value for
+#     keyword argument `in:`, and when Time#getlocal or Time#localtime is called
+#     with `tz` as the value for positional argument `zone`.
+#
+#     Argument
+# :       a [Time-like object](rdoc-ref:Time@Time-Like+Objects).
+#
+#     Returns
+# :       whether the time is daylight saving time.
+#
+#
+# *   `name`:
 #
-# ## Timezone Argument
+#     Called when `Marshal.dump(t)` is invoked
 #
-# A timezone argument must have `local_to_utc` and `utc_to_local` methods, and
-# may have `name`, `abbr`, and `dst?` methods.
+#     Argument
+# :       none.
 #
-# The `local_to_utc` method should convert a Time-like object from the timezone
-# to UTC, and `utc_to_local` is the opposite.  The result also should be a Time
-# or Time-like object (not necessary to be the same class).  The #zone of the
-# result is just ignored. Time-like argument to these methods is similar to a
-# Time object in UTC without subsecond; it has attribute readers for the parts,
-# e.g. #year, #month, and so on, and epoch time readers, #to_i.  The subsecond
-# attributes are fixed as 0, and #utc_offset, #zone, #isdst, and their aliases
-# are same as a Time object in UTC. Also #to_time, #+, and #- methods are
-# defined.
+#     Returns
+# :       the string name of the timezone.
 #
-# The `name` method is used for marshaling. If this method is not defined on a
-# timezone object, Time objects using that timezone object can not be dumped by
-# Marshal.
 #
-# The `abbr` method is used by '%Z' in #strftime.
+# #### `Time`-Like Objects
 #
-# The `dst?` method is called with a `Time` value and should return whether the
-# `Time` value is in daylight savings time in the zone.
+# A `Time`-like object is a container object capable of interfacing with
+# timezone libraries for timezone conversion.
 #
-# ### Auto Conversion to Timezone
+# The argument to the timezone conversion methods above will have attributes
+# similar to Time, except that timezone related attributes are meaningless.
 #
-# At loading marshaled data, a timezone name will be converted to a timezone
-# object by `find_timezone` class method, if the method is defined.
+# The objects returned by `local_to_utc` and `utc_to_local` methods of the
+# timezone object may be of the same class as their arguments, of arbitrary
+# object classes, or of class Integer.
 #
-# Similarly, that class method will be called when a timezone argument does not
-# have the necessary methods mentioned above.
+# For a returned class other than `Integer`, the class must have the following
+# methods:
+#
+# *   `year`
+# *   `mon`
+# *   `mday`
+# *   `hour`
+# *   `min`
+# *   `sec`
+# *   `isdst`
+# *   `to_i`
+#
+# For a returned `Integer`, its components, decomposed in UTC, are interpreted
+# as times in the specified timezone.
+#
+# ### Timezone Names
+#
+# If the class (the receiver of class methods, or the class of the receiver of
+# instance methods) has `find_timezone` singleton method, this method is called
+# to achieve the corresponding timezone object from a timezone name.
+#
+# For example, using [Timezone](https://github.com/panthomakos/timezone):
+#     class TimeWithTimezone < Time
+#       require 'timezone'
+#       def self.find_timezone(z) = Timezone[z]
+#     end
+#
+#     TimeWithTimezone.now(in: "America/New_York")        #=> 2023-12-25 00:00:00 -0500
+#     TimeWithTimezone.new("2023-12-25 America/New_York") #=> 2023-12-25 00:00:00 -0500
+#
+# Or, using [TZInfo](https://tzinfo.github.io):
+#     class TimeWithTZInfo < Time
+#       require 'tzinfo'
+#       def self.find_timezone(z) = TZInfo::Timezone.get(z)
+#     end
+#
+#     TimeWithTZInfo.now(in: "America/New_York")          #=> 2023-12-25 00:00:00 -0500
+#     TimeWithTZInfo.new("2023-12-25 America/New_York")   #=> 2023-12-25 00:00:00 -0500
+#
+# You can define this method per subclasses, or on the toplevel Time class.
 #
 class Time < Object
+  # A type that's used for timeouts.
+  #
+  # All numeric types implement this, but custom classes can also implement it if desired.
+  #
+  # Usage of `Time::_Timeout` is fairly common throughout the stdlib, such as in `Kernel#sleep`,
+  # `IO#timeout=`, and `TCPSocket#new`'s `connet_timeout` field.
+  interface _Timeout
+    # Returns `[seconds, nanoseconds]`.
+    #
+    # The `seconds` should be a whole number of seconds, whereas the `nanoseconds` should be smaller
+    # than one. For example, `3.125.divmod(1)` would yield `[3, 0.125]`
+    def divmod: (1) -> [int, _TimeoutNSecs]
+  end
+
+  # The nanoseconds part of `Time::_Timeout`'s return value. See it for details
+  interface _TimeoutNSecs
+    # Convert `self` into a whole number of seconds.
+    def *: (1_000_000_000) -> int
+  end
+
   include Comparable
 
   # <!--
   #   rdoc-file=timev.rb
   #   - at(time, subsec = false, unit = :microsecond, in: nil)
   # -->
-  # *Time*
-  #
-  # This form accepts a Time object `time` and optional keyword argument `in`:
-  #
-  #     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
-  #
-  # *Seconds*
-  #
-  # This form accepts a numeric number of seconds `sec` and optional keyword
-  # argument `in`:
-  #
-  #     Time.at(946702800)               # => 1999-12-31 23:00:00 -0600
-  #     Time.at(946702800, in: '+09:00') # => 2000-01-01 14:00:00 +0900
-  #
-  # *Seconds with Subseconds and Units*
-  #
-  # 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(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
-  #
-  # Parameters:
-  # *   `isec_i` is the integer number of seconds in the range `0..60`.
-  # *   `msec` is the number of milliseconds (Integer, Float, or Rational) in the
-  #     range `0..1000`.
-  # *   `usec` is the number of microseconds (Integer, Float, or Rational) in the
-  #     range `0..1000000`.
-  # *   `nsec` is the number of nanoseconds (Integer, Float, or Rational) in the
-  #     range `0..1000000000`.
-  # *   `in: zone`: a timezone *zone*, which may be:
-  #     *   A string offset from UTC.
-  #     *   A single letter offset from UTC, in the range `'A'..'Z'`, `'J'` (the
-  #         so-called military timezone) excluded.
-  #     *   An integer number of seconds.
-  #     *   A timezone object; see [Timezone
-  #         Argument](#class-Time-label-Timezone+Argument) for details.
+  # Returns a new `Time` object based on the given arguments.
+  #
+  # Required argument `time` may be either of:
+  #
+  # *   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 [Epoch seconds](rdoc-ref:Time@Epoch+Seconds) for the
+  #     returned time.
+  #
+  # Examples:
+  #
+  #     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
+  #
+  # 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`:
+  #
+  # *   `:millisecond`: `subsec` in milliseconds:
+  #
+  #         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
+  #
+  # *   `:microsecond` or `:usec`: `subsec` in microseconds:
+  #
+  #         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
+  #
+  # *   `:nanosecond` or `:nsec`: `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:Time@Timezone+Specifiers).
   #
   def self.at: (Time, ?in: String | Integer | nil) -> Time
              | (Numeric, ?in: String | Integer | nil) -> Time
@@ -282,60 +520,114 @@ class Time < Object
 
   type subsec_unit = :msec | :millisecond | :usec | :microsecond | :nsec | :nanosecond
 
-  # 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 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.
+  # <!-- rdoc-file=time.c -->
+  # Returns a new `Time` object based the on given arguments, in the UTC timezone.
   #
-  # `sec_with_frac` and `usec_with_frac` can have a fractional part.
+  # With one to seven arguments given, the arguments are interpreted as in the
+  # first calling sequence above:
   #
-  #     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
+  #     Time.utc(year, month = 1, mday = 1, hour = 0, min = 0, sec = 0, usec = 0)
   #
-  def self.gm: (Integer year, ?Integer | String month, ?Integer day, ?Integer hour, ?Integer min, ?Numeric sec, ?Numeric usec_with_frac) -> Time
-
-  # <!--
-  #   rdoc-file=time.c
-  #   - 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
-  # -->
-  # Returns a new Time object based the on given arguments; its timezone is the
-  # local timezone.
+  # Examples:
   #
-  # In the first form (up to seven arguments), argument `year` is required.
+  #     Time.utc(2000)  # => 2000-01-01 00:00:00 UTC
+  #     Time.utc(-2000) # => -2000-01-01 00:00:00 UTC
   #
-  #     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
+  # There are no minimum and maximum values for the required argument `year`.
   #
-  # 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.
+  # For the optional arguments:
   #
-  #     array = Time.now.to_a
-  #     p array # => [57, 26, 13, 24, 4, 2021, 6, 114, true, "Central Daylight Time"]
-  #     array[5] = 2000
-  #     Time.local(*array)  # => 2000-04-24 13:26:57 -0500
+  # *   `month`: Month in range (1..12), or case-insensitive 3-letter month name:
   #
-  # Parameters:
-  # *   `year`: an integer year.
-  # *   `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`.
+  #         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
   #
-  # *   `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`.
-  # *   `isec_i` is the integer number of seconds in the range `0..60`.
-  # *   `usec` is the number of microseconds (Integer, Float, or Rational) in the
-  #     range `0..1000000`.
+  # *   `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
   #
-  # Alias: Time.mktime.
+  # *   `hour`: Hour in range (0..23), or 24 if `min`, `sec`, and `usec` are zero:
   #
-  # Related: Time.utc.
+  #         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.
+  #
+  # Related: Time.local.
+  #
+  def self.gm: (Integer year, ?Integer | String month, ?Integer day, ?Integer hour, ?Integer min, ?Numeric sec, ?Numeric usec_with_frac) -> Time
+
+  # <!--
+  #   rdoc-file=time.c
+  #   - 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
+  # -->
+  # Like Time.utc, except that the returned `Time` object has the local timezone,
+  # not the UTC timezone:
+  #
+  #     # 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
   #
   def self.local: (Integer year, ?Integer | String month, ?Integer day, ?Integer hour, ?Integer min, ?Numeric sec, ?Numeric usec_with_frac) -> Time
 
@@ -343,60 +635,110 @@ class Time < Object
   #   rdoc-file=timev.rb
   #   - now(in: nil)
   # -->
-  # Creates a new Time object from the current system time. This is the same as
+  # Creates a new `Time` object from the current system time. This is the same as
   # Time.new without arguments.
   #
   #     Time.now               # => 2009-06-24 12:39:54 +0900
   #     Time.now(in: '+04:00') # => 2009-06-24 07:39:54 +0400
   #
-  # Parameter:
-  # *   `in: zone`: a timezone *zone*, which may be:
-  #     *   A string offset from UTC.
-  #     *   A single letter offset from UTC, in the range `'A'..'Z'`, `'J'` (the
-  #         so-called military timezone) excluded.
-  #     *   An integer number of seconds.
-  #     *   A timezone object; see [Timezone
-  #         Argument](#class-Time-label-Timezone+Argument) for details.
+  # For forms of argument `zone`, see [Timezone
+  # Specifiers](rdoc-ref:Time@Timezone+Specifiers).
   #
   def self.now: (?in: String | Integer | nil) -> Time
 
   # <!--
   #   rdoc-file=time.c
-  #   - 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.
+  #
+  # With one to seven arguments given, the arguments are interpreted as in the
+  # first calling sequence above:
+  #
+  #     Time.utc(year, month = 1, mday = 1, hour = 0, min = 0, sec = 0, usec = 0)
   #
-  # In the first form (up to seven arguments), argument `year` is required.
+  # Examples:
+  #
+  #     Time.utc(2000)  # => 2000-01-01 00:00:00 UTC
+  #     Time.utc(-2000) # => -2000-01-01 00:00:00 UTC
+  #
+  # 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:
   #
-  #     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
+  # *   Integers, as above.
+  # *   Numerics convertible to integers:
   #
-  # 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.
+  #         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
   #
-  #     array = Time.now.to_a
-  #     p array # => [57, 26, 13, 24, 4, 2021, 6, 114, true, "Central Daylight Time"]
-  #     array[5] = 2000
-  #     Time.utc(*array) # => 2000-04-24 13:26:57 UTC
+  # *   String integers:
   #
-  # Parameters:
-  # *   `year`: an integer year.
-  # *   `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`.
+  #         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
   #
-  # *   `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`.
-  # *   `isec_i` is the integer number of seconds in the range `0..60`.
-  # *   `usec` is the number of microseconds (Integer, Float, or Rational) in the
-  #     range `0..1000000`.
+  # 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)
   #
-  # Alias: Time.gm.
+  # 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.
   #
   # Related: Time.local.
   #
@@ -404,28 +746,37 @@ class Time < Object
 
   # <!--
   #   rdoc-file=time.c
-  #   - time + numeric -> time
+  #   - self + numeric -> new_time
   # -->
-  # Adds some number of seconds (possibly including subsecond) to *time* and
-  # returns that value as a new Time object.
+  # Returns a new `Time` object whose value is the sum of the numeric value of
+  # `self` and the given `numeric`:
+  #
+  #     t = Time.new(2000) # => 2000-01-01 00:00:00 -0600
+  #     t + (60 * 60 * 24) # => 2000-01-02 00:00:00 -0600
+  #     t + 0.5            # => 2000-01-01 00:00:00.5 -0600
   #
-  #     t = Time.now         #=> 2020-07-20 22:14:43.170490982 +0900
-  #     t + (60 * 60 * 24)   #=> 2020-07-21 22:14:43.170490982 +0900
+  # Related: Time#-.
   #
   def +: (Numeric arg0) -> Time
 
   # <!--
   #   rdoc-file=time.c
-  #   - time - other_time -> float
-  #   - time - numeric    -> time
+  #   - self - numeric -> new_time
+  #   - self - other_time -> float
   # -->
-  # Returns a difference in seconds as a Float between *time* and `other_time`, or
-  # subtracts the given number of seconds in `numeric` from *time*.
+  # When `numeric` is given, returns a new `Time` object whose value is the
+  # difference of the numeric value of `self` and `numeric`:
+  #
+  #     t = Time.new(2000) # => 2000-01-01 00:00:00 -0600
+  #     t - (60 * 60 * 24) # => 1999-12-31 00:00:00 -0600
+  #     t - 0.5            # => 1999-12-31 23:59:59.5 -0600
+  #
+  # When `other_time` is given, returns a Float whose value is the difference of
+  # the numeric values of `self` and `other_time` in seconds:
   #
-  #     t = Time.now       #=> 2020-07-20 22:15:49.302766336 +0900
-  #     t2 = t + 2592000   #=> 2020-08-19 22:15:49.302766336 +0900
-  #     t2 - t             #=> 2592000.0
-  #     t2 - 2592000       #=> 2020-07-20 22:15:49.302766336 +0900
+  #     t - t # => 0.0
+  #
+  # Related: Time#+.
   #
   def -: (Time arg0) -> Float
        | (Numeric arg0) -> Time
@@ -436,27 +787,29 @@ class Time < Object
 
   # <!--
   #   rdoc-file=time.c
-  #   - time <=> other_time -> -1, 0, +1, or nil
+  #   - self <=> other_time -> -1, 0, +1, or nil
   # -->
-  # Compares `time` with `other_time`.
+  # Compares `self` with `other_time`; returns:
   #
-  # -1, 0, +1 or nil depending on whether `time` is less than, equal to, or
-  # greater than `other_time`.
+  # *   `-1`, if `self` is less than `other_time`.
+  # *   `0`, if `self` is equal to `other_time`.
+  # *   `1`, if `self` is greater then `other_time`.
+  # *   `nil`, if `self` and `other_time` are incomparable.
   #
-  # `nil` is returned if the two values are incomparable.
+  # Examples:
   #
-  #     t = Time.now       #=> 2007-11-19 08:12:12 -0600
-  #     t2 = t + 2592000   #=> 2007-12-19 08:12:12 -0600
-  #     t <=> t2           #=> -1
-  #     t2 <=> t           #=> 1
+  #     t = Time.now     # => 2007-11-19 08:12:12 -0600
+  #     t2 = t + 2592000 # => 2007-12-19 08:12:12 -0600
+  #     t <=> t2         # => -1
+  #     t2 <=> t         # => 1
   #
-  #     t = Time.now       #=> 2007-11-19 08:13:38 -0600
-  #     t2 = t + 0.1       #=> 2007-11-19 08:13:38 -0600
-  #     t.nsec             #=> 98222999
-  #     t2.nsec            #=> 198222999
-  #     t <=> t2           #=> -1
-  #     t2 <=> t           #=> 1
-  #     t <=> t            #=> 0
+  #     t = Time.now     # => 2007-11-19 08:13:38 -0600
+  #     t2 = t + 0.1     # => 2007-11-19 08:13:38 -0600
+  #     t.nsec           # => 98222999
+  #     t2.nsec          # => 198222999
+  #     t <=> t2         # => -1
+  #     t2 <=> t         # => 1
+  #     t <=> t          # => 0
   #
   def <=>: (Time other) -> Integer
          | (untyped other) -> Integer?
@@ -466,895 +819,840 @@ class Time < Object
   def >=: (Time arg0) -> bool
 
   # <!-- rdoc-file=time.c -->
-  # Returns a canonical string representation of *time*.
+  # Returns a string representation of `self`, formatted by `strftime('%a %b %e %T
+  # %Y')` or its shorthand version `strftime('%c')`; see [Formats for Dates and
+  # Times](rdoc-ref:strftime_formatting.rdoc):
+  #
+  #     t = Time.new(2000, 12, 31, 23, 59, 59, 0.5)
+  #     t.ctime                      # => "Sun Dec 31 23:59:59 2000"
+  #     t.strftime('%a %b %e %T %Y') # => "Sun Dec 31 23:59:59 2000"
+  #     t.strftime('%c')             # => "Sun Dec 31 23:59:59 2000"
+  #
+  # Related: Time#to_s, Time#inspect:
   #
-  #     Time.now.asctime   #=> "Wed Apr  9 08:56:03 2003"
-  #     Time.now.ctime     #=> "Wed Apr  9 08:56:03 2003"
+  #     t.inspect                    # => "2000-12-31 23:59:59.5 +000001"
+  #     t.to_s                       # => "2000-12-31 23:59:59 +0000"
   #
   def asctime: () -> String
 
   # <!--
   #   rdoc-file=time.c
-  #   - time.asctime -> string
-  #   - time.ctime   -> string
+  #   - ctime -> string
   # -->
-  # Returns a canonical string representation of *time*.
+  # Returns a string representation of `self`, formatted by `strftime('%a %b %e %T
+  # %Y')` or its shorthand version `strftime('%c')`; see [Formats for Dates and
+  # Times](rdoc-ref:strftime_formatting.rdoc):
   #
-  #     Time.now.asctime   #=> "Wed Apr  9 08:56:03 2003"
-  #     Time.now.ctime     #=> "Wed Apr  9 08:56:03 2003"
+  #     t = Time.new(2000, 12, 31, 23, 59, 59, 0.5)
+  #     t.ctime                      # => "Sun Dec 31 23:59:59 2000"
+  #     t.strftime('%a %b %e %T %Y') # => "Sun Dec 31 23:59:59 2000"
+  #     t.strftime('%c')             # => "Sun Dec 31 23:59:59 2000"
+  #
+  # Related: Time#to_s, Time#inspect:
+  #
+  #     t.inspect                    # => "2000-12-31 23:59:59.5 +000001"
+  #     t.to_s                       # => "2000-12-31 23:59:59 +0000"
   #
   def ctime: () -> String
 
   # <!-- rdoc-file=time.c -->
-  # Returns the day of the month (1..31) for *time*.
+  # Returns the integer day of the month for `self`, in range (1..31):
   #
-  #     t = Time.now   #=> 2007-11-19 08:27:03 -0600
-  #     t.day          #=> 19
-  #     t.mday         #=> 19
+  #     t = Time.new(2000, 1, 2, 3, 4, 5, 6)
+  #     # => 2000-01-02 03:04:05 +000006
+  #     t.mday # => 2
+  #
+  # Related: Time#year, Time#hour, Time#min.
   #
   def day: () -> Integer
 
+  # <!--
+  #   rdoc-file=time.c
+  #   - deconstruct_keys(array_of_names_or_nil) -> hash
+  # -->
+  # Returns a hash of the name/value pairs, to use in pattern matching. Possible
+  # keys are: `:year`, `:month`, `:day`, `:yday`, `:wday`, `:hour`, `:min`,
+  # `:sec`, `:subsec`, `:dst`, `:zone`.
+  #
+  # Possible usages:
+  #
+  #     t = Time.utc(2022, 10, 5, 21, 25, 30)
+  #
+  #     if t in wday: 3, day: ..7  # uses deconstruct_keys underneath
+  #       puts "first Wednesday of the month"
+  #     end
+  #     #=> prints "first Wednesday of the month"
+  #
+  #     case t
+  #     in year: ...2022
+  #       puts "too old"
+  #     in month: ..9
+  #       puts "quarter 1-3"
+  #     in wday: 1..5, month:
+  #       puts "working day in month #{month}"
+  #     end
+  #     #=> prints "working day in month 10"
+  #
+  # Note that deconstruction by pattern can also be combined with class check:
+  #
+  #     if t in Time(wday: 3, day: ..7)
+  #       puts "first Wednesday of the month"
+  #     end
+  #
+  def deconstruct_keys: (Array[Symbol]?) -> Hash[Symbol, Integer]
+
   # <!-- rdoc-file=time.c -->
-  # 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
+  # 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
   #
   def dst?: () -> bool
 
   # <!--
   #   rdoc-file=time.c
-  #   - time.eql?(other_time)
+  #   - eql?(other_time)
   # -->
-  # Returns `true` if *time* and `other_time` are both Time objects with the same
-  # seconds (including subsecond) from the Epoch.
+  # Returns `true` if `self` and `other_time` are both `Time` objects with the
+  # exact same time value.
   #
   def eql?: (untyped arg0) -> bool
 
   # <!--
   #   rdoc-file=time.c
-  #   - time.friday? -> true or false
+  #   - friday? -> true or false
   # -->
-  # Returns `true` if *time* represents Friday.
+  # Returns `true` if `self` represents a Friday, `false` otherwise:
+  #
+  #     t = Time.utc(2000, 1, 7) # => 2000-01-07 00:00:00 UTC
+  #     t.friday?                # => true
   #
-  #     t = Time.local(1987, 12, 18)     #=> 1987-12-18 00:00:00 -0600
-  #     t.friday?                        #=> true
+  # Related: Time#saturday?, Time#sunday?, Time#monday?.
   #
   def friday?: () -> bool
 
   # <!--
   #   rdoc-file=time.c
-  #   - time.getgm  -> new_time
-  #   - time.getutc -> new_time
+  #   - getutc -> new_time
   # -->
-  # Returns a new Time object representing *time* in UTC.
+  # Returns a new `Time` object representing the value of `self` converted to the
+  # UTC timezone:
   #
-  #     t = Time.local(2000,1,1,20,15,1)   #=> 2000-01-01 20:15:01 -0600
-  #     t.gmt?                             #=> false
-  #     y = t.getgm                        #=> 2000-01-02 02:15:01 UTC
-  #     y.gmt?                             #=> true
-  #     t == y                             #=> true
+  #     local = Time.local(2000) # => 2000-01-01 00:00:00 -0600
+  #     local.utc?               # => false
+  #     utc = local.getutc       # => 2000-01-01 06:00:00 UTC
+  #     utc.utc?                 # => true
+  #     utc == local             # => true
   #
   def getgm: () -> Time
 
   # <!--
   #   rdoc-file=time.c
-  #   - time.getlocal -> new_time
-  #   - time.getlocal(utc_offset) -> new_time
-  #   - time.getlocal(timezone) -> new_time
+  #   - getlocal(zone = nil) -> new_time
   # -->
-  # Returns a new Time object representing *time* in local time (using the local
-  # time zone in effect for this process).
+  # Returns a new `Time` object representing the value of `self` converted to a
+  # given timezone; if `zone` is `nil`, the local timezone is used:
   #
-  # If `utc_offset` is given, it is used instead of the local time. `utc_offset`
-  # can be given as a human-readable string (eg. `"+09:00"`) or as a number of
-  # seconds (eg. `32400`).
+  #     t = Time.utc(2000)                    # => 2000-01-01 00:00:00 UTC
+  #     t.getlocal                            # => 1999-12-31 18:00:00 -0600
+  #     t.getlocal('+12:00')                  # => 2000-01-01 12:00:00 +1200
   #
-  #     t = Time.utc(2000,1,1,20,15,1)  #=> 2000-01-01 20:15:01 UTC
-  #     t.utc?                          #=> true
-  #
-  #     l = t.getlocal                  #=> 2000-01-01 14:15:01 -0600
-  #     l.utc?                          #=> false
-  #     t == l                          #=> true
-  #
-  #     j = t.getlocal("+09:00")        #=> 2000-01-02 05:15:01 +0900
-  #     j.utc?                          #=> false
-  #     t == j                          #=> true
-  #
-  #     k = t.getlocal(9*60*60)         #=> 2000-01-02 05:15:01 +0900
-  #     k.utc?                          #=> false
-  #     t == k                          #=> true
+  # For forms of argument `zone`, see [Timezone
+  # Specifiers](rdoc-ref:Time@Timezone+Specifiers).
   #
   def getlocal: (?Integer utc_offset) -> Time
 
   # <!-- rdoc-file=time.c -->
-  # Returns a new Time object representing *time* in UTC.
+  # Returns a new `Time` object representing the value of `self` converted to the
+  # UTC timezone:
   #
-  #     t = Time.local(2000,1,1,20,15,1)   #=> 2000-01-01 20:15:01 -0600
-  #     t.gmt?                             #=> false
-  #     y = t.getgm                        #=> 2000-01-02 02:15:01 UTC
-  #     y.gmt?                             #=> true
-  #     t == y                             #=> true
+  #     local = Time.local(2000) # => 2000-01-01 00:00:00 -0600
+  #     local.utc?               # => false
+  #     utc = local.getutc       # => 2000-01-01 06:00:00 UTC
+  #     utc.utc?                 # => true
+  #     utc == local             # => true
   #
   def getutc: () -> Time
 
   # <!-- rdoc-file=time.c -->
-  # Returns `true` if *time* represents a time in UTC (GMT).
+  # Returns `true` if `self` represents a time in UTC (GMT):
   #
-  #     t = Time.now                        #=> 2007-11-19 08:15:23 -0600
-  #     t.utc?                              #=> false
-  #     t = Time.gm(2000,"jan",1,20,15,1)   #=> 2000-01-01 20:15:01 UTC
-  #     t.utc?                              #=> true
+  #     now = Time.now
+  #     # => 2022-08-18 10:24:13.5398485 -0500
+  #     now.utc? # => false
+  #     utc = Time.utc(2000, 1, 1, 20, 15, 1)
+  #     # => 2000-01-01 20:15:01 UTC
+  #     utc.utc? # => true
   #
-  #     t = Time.now                        #=> 2007-11-19 08:16:03 -0600
-  #     t.gmt?                              #=> false
-  #     t = Time.gm(2000,1,1,20,15,1)       #=> 2000-01-01 20:15:01 UTC
-  #     t.gmt?                              #=> true
+  # Related: Time.utc.
   #
   def gmt?: () -> bool
 
   # <!-- rdoc-file=time.c -->
-  # 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.
   #
   def gmt_offset: () -> Integer
 
   # <!--
   #   rdoc-file=time.c
-  #   - time.gmtime    -> time
-  #   - time.utc       -> time
+  #   - utc -> self
   # -->
-  # Converts *time* to UTC (GMT), modifying the receiver.
+  # Returns `self`, converted to the UTC timezone:
   #
-  #     t = Time.now   #=> 2007-11-19 08:18:31 -0600
-  #     t.gmt?         #=> false
-  #     t.gmtime       #=> 2007-11-19 14:18:31 UTC
-  #     t.gmt?         #=> true
+  #     t = Time.new(2000) # => 2000-01-01 00:00:00 -0600
+  #     t.utc?             # => false
+  #     t.utc              # => 2000-01-01 06:00:00 UTC
+  #     t.utc?             # => true
   #
-  #     t = Time.now   #=> 2007-11-19 08:18:51 -0600
-  #     t.utc?         #=> false
-  #     t.utc          #=> 2007-11-19 14:18:51 UTC
-  #     t.utc?         #=> true
+  # Related: Time#getutc (returns a new converted `Time` object).
   #
   def gmtime: () -> Time
 
   # <!--
   #   rdoc-file=time.c
-  #   - time.hash   -> integer
+  #   - hash -> integer
   # -->
-  # Returns a hash code for this Time object.
+  # Returns the integer hash code for `self`.
   #
-  # See also Object#hash.
+  # Related: Object#hash.
   #
   def hash: () -> Integer
 
   # <!--
   #   rdoc-file=time.c
-  #   - time.hour -> integer
+  #   - hour -> integer
   # -->
-  # Returns the hour of the day (0..23) for *time*.
+  # Returns the integer hour of the day for `self`, in range (0..23):
   #
-  #     t = Time.now   #=> 2007-11-19 08:26:20 -0600
-  #     t.hour         #=> 8
+  #     t = Time.new(2000, 1, 2, 3, 4, 5, 6)
+  #     # => 2000-01-02 03:04:05 +000006
+  #     t.hour # => 3
+  #
+  # Related: Time#year, Time#mon, Time#min.
   #
   def hour: () -> Integer
 
   # <!--
   #   rdoc-file=timev.rb
-  #   - new(year = (now = true), mon = nil, mday = nil, hour = nil, min = nil, sec = nil, zone = nil, in: nil)
+  #   - Time.new(year = nil, mon = nil, mday = nil, hour = nil, min = nil, sec = nil, zone = nil, in: nil, precision: 9)
   # -->
-  # 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
+  #
+  # With one string argument that represents a time, returns a new `Time` object
+  # based on the given argument, in the local timezone.
+  #
+  #     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 +0900')        # => 2000-12-31 23:59:59.5 +0900
+  #     Time.new('2000-12-31 23:59:59.5', in: '+0900') # => 2000-12-31 23:59:59.5 +0900
+  #     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.56789', precision: 3) # => 2000-12-31 23:59:59.567 -0600
+  #
+  # With one to six arguments, returns a new `Time` object based on the given
+  # arguments, in the local timezone.
+  #
+  #     Time.new(2000, 1, 2, 3, 4, 5) # => 2000-01-02 03:04:05 -0600
+  #
+  # For the positional arguments (other than `zone`):
+  #
+  # *   `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):
   #
-  # Otherwise, returns a new Time object based on the given parameters:
+  #         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
   #
-  #     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
+  # *   `sec`: Second in range (0...61):
   #
-  # Parameters:
+  #         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
   #
-  # *   `year`: an integer year.
-  # *   `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`.
+  #     `sec` may be Float or Rational.
   #
-  # *   `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`.
-  # *   `sec` is the number of seconds (Integer, Float, or Rational) in the range
-  #     `0..60`.
-  # *   `zone`: a timezone, which may be:
-  #     *   A string offset from UTC.
-  #     *   A single letter offset from UTC, in the range `'A'..'Z'`, `'J'` (the
-  #         so-called military timezone) excluded.
-  #     *   An integer number of seconds.
-  #     *   A timezone object; see [Timezone
-  #         Argument](#class-Time-label-Timezone+Argument) for details.
+  #         Time.new(2000, 1, 1, 0, 0, 59.5)  # => 2000-12-31 23:59:59.5 +0900
+  #         Time.new(2000, 1, 1, 0, 0, 59.7r) # => 2000-12-31 23:59:59.7 +0900
   #
-  # *   `in: zone`: a timezone *zone*, which may be as above.
+  # These values may be:
   #
-  def initialize: (?Integer? year, ?Integer? month, ?Integer? day, ?Integer? hour, ?Integer? min, ?Numeric? sec, ?String | Integer | nil) -> void
-                | (?Integer? year, ?Integer? month, ?Integer? day, ?Integer? hour, ?Integer? min, ?Numeric? sec, in: String | Integer | nil) -> void
+  # *   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:Time@Timezone+Specifiers):
+  #
+  #     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
+  #
+  # Since `in:` keyword argument just provides the default, so if the first
+  # argument in single string form contains time zone information, this keyword
+  # argument will be silently ignored.
+  #
+  #     Time.new('2000-01-01 00:00:00 +0100', in: '-0500').utc_offset  # => 3600
+  #
+  # *   `precision`: maximum effective digits in sub-second part, default is 9.
+  #     More digits will be truncated, as other operations of `Time`. Ignored
+  #     unless the first argument is a string.
+  #
+  def initialize: (?Integer year, ?Integer? month, ?Integer? day, ?Integer? hour, ?Integer? min, ?Numeric? sec, ?String | Integer | nil) -> void
+                | (?Integer year, ?Integer? month, ?Integer? day, ?Integer? hour, ?Integer? min, ?Numeric? sec, in: String | Integer | nil) -> void
+                | (String, ?in: string | int | nil, ?precision: int) -> void
 
   # <!--
   #   rdoc-file=time.c
-  #   - time.inspect -> string
+  #   - inspect -> string
   # -->
-  # Returns a detailed string representing *time*. Unlike to_s, preserves
-  # subsecond in the representation for easier debugging.
+  # Returns a string representation of `self` with subseconds:
   #
-  #     t = Time.now
-  #     t.inspect                             #=> "2012-11-10 18:16:12.261257655 +0100"
-  #     t.strftime "%Y-%m-%d %H:%M:%S.%N %z"  #=> "2012-11-10 18:16:12.261257655 +0100"
+  #     t = Time.new(2000, 12, 31, 23, 59, 59, 0.5)
+  #     t.inspect # => "2000-12-31 23:59:59.5 +000001"
   #
-  #     t.utc.inspect                          #=> "2012-11-10 17:16:12.261257655 UTC"
-  #     t.strftime "%Y-%m-%d %H:%M:%S.%N UTC"  #=> "2012-11-10 17:16:12.261257655 UTC"
+  # Related: Time#ctime, Time#to_s:
+  #
+  #     t.ctime   # => "Sun Dec 31 23:59:59 2000"
+  #     t.to_s    # => "2000-12-31 23:59:59 +0000"
   #
   def inspect: () -> String
 
   # <!--
   #   rdoc-file=time.c
-  #   - 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.
-  #
-  #     # 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
+  # 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
   #
   def isdst: () -> bool
 
+  # <!-- rdoc-file=lib/time.rb -->
+  # Parses `time` as a dateTime defined by the XML Schema and converts it to a
+  # Time object.  The format is a restricted version of the format defined by ISO
+  # 8601.
+  #
+  # ArgumentError is raised if `time` is not compliant with the format or if the
+  # Time class cannot represent the specified time.
+  #
+  # See #xmlschema for more information on this format.
+  #
+  #     require 'time'
+  #
+  #     Time.xmlschema("2011-10-05T22:26:12-04:00")
+  #     #=> 2011-10-05 22:26:12-04:00
+  #
+  # You must require 'time' to use this method.
+  #
+  alias iso8601 xmlschema
+
   # <!--
   #   rdoc-file=time.c
-  #   - time.localtime -> time
-  #   - time.localtime(utc_offset) -> time
+  #   - localtime -> self or new_time
+  #   - localtime(zone) -> new_time
   # -->
-  # Converts *time* to local time (using the local time zone in effect at the
-  # creation time of *time*) modifying the receiver.
+  # With no argument given:
   #
-  # If `utc_offset` is given, it is used instead of the local time.
+  # *   Returns `self` if `self` is a local time.
+  # *   Otherwise returns a new `Time` in the user's local timezone:
   #
-  #     t = Time.utc(2000, "jan", 1, 20, 15, 1) #=> 2000-01-01 20:15:01 UTC
-  #     t.utc?                                  #=> true
+  #         t = Time.utc(2000, 1, 1, 20, 15, 1) # => 2000-01-01 20:15:01 UTC
+  #         t.localtime                         # => 2000-01-01 14:15:01 -0600
   #
-  #     t.localtime                             #=> 2000-01-01 14:15:01 -0600
-  #     t.utc?                                  #=> false
+  # With argument `zone` given, returns the new `Time` object created by
+  # converting `self` to the given time zone:
   #
-  #     t.localtime("+09:00")                   #=> 2000-01-02 05:15:01 +0900
-  #     t.utc?                                  #=> false
+  #     t = Time.utc(2000, 1, 1, 20, 15, 1) # => 2000-01-01 20:15:01 UTC
+  #     t.localtime("-09:00")               # => 2000-01-01 11:15:01 -0900
   #
-  # If `utc_offset` is not given and *time* is local time, just returns the
-  # receiver.
+  # For forms of argument `zone`, see [Timezone
+  # Specifiers](rdoc-ref:Time@Timezone+Specifiers).
   #
   def localtime: (?String utc_offset) -> Time
 
   # <!--
   #   rdoc-file=time.c
-  #   - time.day  -> integer
-  #   - time.mday -> integer
+  #   - mday -> integer
   # -->
-  # Returns the day of the month (1..31) for *time*.
+  # Returns the integer day of the month for `self`, in range (1..31):
+  #
+  #     t = Time.new(2000, 1, 2, 3, 4, 5, 6)
+  #     # => 2000-01-02 03:04:05 +000006
+  #     t.mday # => 2
   #
-  #     t = Time.now   #=> 2007-11-19 08:27:03 -0600
-  #     t.day          #=> 19
-  #     t.mday         #=> 19
+  # Related: Time#year, Time#hour, Time#min.
   #
   def mday: () -> Integer
 
   # <!--
   #   rdoc-file=time.c
-  #   - time.min -> integer
+  #   - min -> integer
   # -->
-  # Returns the minute of the hour (0..59) for *time*.
+  # Returns the integer minute of the hour for `self`, in range (0..59):
   #
-  #     t = Time.now   #=> 2007-11-19 08:25:51 -0600
-  #     t.min          #=> 25
+  #     t = Time.new(2000, 1, 2, 3, 4, 5, 6)
+  #     # => 2000-01-02 03:04:05 +000006
+  #     t.min # => 4
+  #
+  # Related: Time#year, Time#mon, Time#sec.
   #
   def min: () -> Integer
 
   # <!--
   #   rdoc-file=time.c
-  #   - time.mon   -> integer
-  #   - time.month -> integer
+  #   - mon -> integer
   # -->
-  # Returns the month of the year (1..12) for *time*.
+  # Returns the integer month of the year for `self`, in range (1..12):
+  #
+  #     t = Time.new(2000, 1, 2, 3, 4, 5, 6)
+  #     # => 2000-01-02 03:04:05 +000006
+  #     t.mon # => 1
   #
-  #     t = Time.now   #=> 2007-11-19 08:27:30 -0600
-  #     t.mon          #=> 11
-  #     t.month        #=> 11
+  # Related: Time#year, Time#hour, Time#min.
   #
   def mon: () -> Integer
 
   # <!--
   #   rdoc-file=time.c
-  #   - time.monday? -> true or false
+  #   - monday? -> true or false
   # -->
-  # Returns `true` if *time* represents Monday.
+  # Returns `true` if `self` represents a Monday, `false` otherwise:
   #
-  #     t = Time.local(2003, 8, 4)       #=> 2003-08-04 00:00:00 -0500
-  #     t.monday?                        #=> true
+  #     t = Time.utc(2000, 1, 3) # => 2000-01-03 00:00:00 UTC
+  #     t.monday?                # => true
+  #
+  # Related: Time#tuesday?, Time#wednesday?, Time#thursday?.
   #
   def monday?: () -> bool
 
   # <!-- rdoc-file=time.c -->
-  # Returns the number of nanoseconds for the subsecond part of *time*. The result
-  # is a non-negative integer less than 10**9.
-  #
-  #     t = Time.now        #=> 2020-07-20 22:07:10.963933942 +0900
-  #     t.nsec              #=> 963933942
+  # Returns the number of nanoseconds in the subseconds part of `self` in the
+  # range (0..999_999_999); lower-order digits are truncated, not rounded:
   #
-  # If *time* has fraction of nanosecond (such as picoseconds), it is truncated.
+  #     t = Time.now # => 2022-07-11 15:04:53.3219637 -0500
+  #     t.nsec       # => 321963700
   #
-  #     t = Time.new(2000,1,1,0,0,0.666_777_888_999r)
-  #     t.nsec              #=> 666777888
-  #
-  # Time#subsec can be used to obtain the subsecond part exactly.
+  # Related: Time#subsec (returns exact subseconds).
   #
   def nsec: () -> Integer
 
   # <!--
   #   rdoc-file=time.c
-  #   - time.round([ndigits])   -> new_time
+  #   - round(ndigits = 0) -> new_time
   # -->
-  # Rounds subsecond to a given precision in decimal digits (0 digits by default).
-  # It returns a new Time object. `ndigits` should be zero or a positive integer.
-  #
-  #     t = Time.utc(2010,3,30, 5,43,25.123456789r)
-  #     t                       #=> 2010-03-30 05:43:25.123456789 UTC
-  #     t.round                 #=> 2010-03-30 05:43:25 UTC
-  #     t.round(0)              #=> 2010-03-30 05:43:25 UTC
-  #     t.round(1)              #=> 2010-03-30 05:43:25.1 UTC
-  #     t.round(2)              #=> 2010-03-30 05:43:25.12 UTC
-  #     t.round(3)              #=> 2010-03-30 05:43:25.123 UTC
-  #     t.round(4)              #=> 2010-03-30 05:43:25.1235 UTC
-  #
-  #     t = Time.utc(1999,12,31, 23,59,59)
-  #     (t + 0.4).round         #=> 1999-12-31 23:59:59 UTC
-  #     (t + 0.49).round        #=> 1999-12-31 23:59:59 UTC
-  #     (t + 0.5).round         #=> 2000-01-01 00:00:00 UTC
-  #     (t + 1.4).round         #=> 2000-01-01 00:00:00 UTC
-  #     (t + 1.49).round        #=> 2000-01-01 00:00:00 UTC
-  #     (t + 1.5).round         #=> 2000-01-01 00:00:01 UTC
-  #
-  #     t = Time.utc(1999,12,31, 23,59,59)     #=> 1999-12-31 23:59:59 UTC
-  #     (t + 0.123456789).round(4).iso8601(6)  #=> 1999-12-31 23:59:59.1235 UTC
-  #
-  def round: (?Integer arg0) -> Time
+  # Returns a new `Time` object whose numeric value is that of `self`, with its
+  # seconds value rounded to precision `ndigits`:
+  #
+  #     t = Time.utc(2010, 3, 30, 5, 43, 25.123456789r)
+  #     t          # => 2010-03-30 05:43:25.123456789 UTC
+  #     t.round    # => 2010-03-30 05:43:25 UTC
+  #     t.round(0) # => 2010-03-30 05:43:25 UTC
+  #     t.round(1) # => 2010-03-30 05:43:25.1 UTC
+  #     t.round(2) # => 2010-03-30 05:43:25.12 UTC
+  #     t.round(3) # => 2010-03-30 05:43:25.123 UTC
+  #     t.round(4) # => 2010-03-30 05:43:25.1235 UTC
+  #
+  #     t = Time.utc(1999, 12,31, 23, 59, 59)
+  #     t                # => 1999-12-31 23:59:59 UTC
+  #     (t + 0.4).round  # => 1999-12-31 23:59:59 UTC
+  #     (t + 0.49).round # => 1999-12-31 23:59:59 UTC
+  #     (t + 0.5).round  # => 2000-01-01 00:00:00 UTC
+  #     (t + 1.4).round  # => 2000-01-01 00:00:00 UTC
+  #     (t + 1.49).round # => 2000-01-01 00:00:00 UTC
+  #     (t + 1.5).round  # => 2000-01-01 00:00:01 UTC
+  #
+  # Related: Time#ceil, Time#floor.
+  #
+  def round: (?int ndigits) -> Time
 
   # <!--
   #   rdoc-file=time.c
-  #   - time.saturday? -> true or false
+  #   - saturday? -> true or false
   # -->
-  # Returns `true` if *time* represents Saturday.
+  # Returns `true` if `self` represents a Saturday, `false` otherwise:
+  #
+  #     t = Time.utc(2000, 1, 1) # => 2000-01-01 00:00:00 UTC
+  #     t.saturday?              # => true
   #
-  #     t = Time.local(2006, 6, 10)      #=> 2006-06-10 00:00:00 -0500
-  #     t.saturday?                      #=> true
+  # Related: Time#sunday?, Time#monday?, Time#tuesday?.
   #
   def saturday?: () -> bool
 
   # <!--
   #   rdoc-file=time.c
-  #   - time.sec -> integer
+  #   - sec -> integer
   # -->
-  # Returns the second of the minute (0..60) for *time*.
+  # Returns the integer second of the minute for `self`, in range (0..60):
   #
-  # **Note:** Seconds range from zero to 60 to allow the system to inject leap
-  # seconds. See https://en.wikipedia.org/wiki/Leap_second for further details.
+  #     t = Time.new(2000, 1, 2, 3, 4, 5, 6)
+  #     # => 2000-01-02 03:04:05 +000006
+  #     t.sec # => 5
   #
-  #     t = Time.now   #=> 2007-11-19 08:25:02 -0600
-  #     t.sec          #=> 2
+  # Note: the second value may be 60 when there is a [leap
+  # second](https://en.wikipedia.org/wiki/Leap_second).
+  #
+  # Related: Time#year, Time#mon, Time#min.
   #
   def sec: () -> Integer
 
   # <!--
   #   rdoc-file=time.c
-  #   - time.strftime( string ) -> string
+  #   - strftime(format_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)
+  # Returns a string representation of `self`, formatted according to the given
+  # string `format`. See [Formats for Dates and
+  # Times](rdoc-ref:strftime_formatting.rdoc).
   #
   def strftime: (String arg0) -> String
 
   # <!--
   #   rdoc-file=time.c
-  #   - time.subsec    -> number
+  #   - subsec -> numeric
   # -->
-  # Returns the subsecond for *time*.
-  #
-  # The return value can be a rational number.
-  #
-  #     t = Time.now        #=> 2020-07-20 15:40:26.867462289 +0900
-  #     t.subsec            #=> (867462289/1000000000)
+  # Returns the exact subseconds for `self` as a Numeric (Integer or Rational):
   #
-  #     t = Time.now        #=> 2020-07-20 15:40:50.313828595 +0900
-  #     t.subsec            #=> (62765719/200000000)
+  #     t = Time.now # => 2022-07-11 15:11:36.8490302 -0500
+  #     t.subsec     # => (4245151/5000000)
   #
-  #     t = Time.new(2000,1,1,2,3,4) #=> 2000-01-01 02:03:04 +0900
-  #     t.subsec                     #=> 0
+  # If the subseconds is zero, returns integer zero:
   #
-  #     Time.new(2000,1,1,0,0,1/3r,"UTC").subsec #=> (1/3)
+  #     t = Time.new(2000, 1, 1, 2, 3, 4) # => 2000-01-01 02:03:04 -0600
+  #     t.subsec                          # => 0
   #
   def subsec: () -> (0 | Rational)
 
   # <!--
   #   rdoc-file=time.c
-  #   - time.sunday? -> true or false
+  #   - sunday? -> true or false
   # -->
-  # Returns `true` if *time* represents Sunday.
+  # Returns `true` if `self` represents a Sunday, `false` otherwise:
   #
-  #     t = Time.local(1990, 4, 1)       #=> 1990-04-01 00:00:00 -0600
-  #     t.sunday?                        #=> true
+  #     t = Time.utc(2000, 1, 2) # => 2000-01-02 00:00:00 UTC
+  #     t.sunday?                # => true
+  #
+  # Related: Time#monday?, Time#tuesday?, Time#wednesday?.
   #
   def sunday?: () -> bool
 
   # <!--
   #   rdoc-file=time.c
-  #   - time.thursday? -> true or false
+  #   - thursday? -> true or false
   # -->
-  # Returns `true` if *time* represents Thursday.
+  # Returns `true` if `self` represents a Thursday, `false` otherwise:
+  #
+  #     t = Time.utc(2000, 1, 6) # => 2000-01-06 00:00:00 UTC
+  #     t.thursday?              # => true
   #
-  #     t = Time.local(1995, 12, 21)     #=> 1995-12-21 00:00:00 -0600
-  #     t.thursday?                      #=> true
+  # Related: Time#friday?, Time#saturday?, Time#sunday?.
   #
   def thursday?: () -> bool
 
   # <!--
   #   rdoc-file=time.c
-  #   - 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"]
-  #
-  def to_a: () -> [ Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, bool, String ]
+  def to_a: () -> [ Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, bool, String? ]
 
   # <!--
   #   rdoc-file=time.c
-  #   - time.to_f -> float
+  #   - to_f -> float
   # -->
-  # Returns the value of *time* as a floating point number of seconds since the
-  # Epoch. The return value approximate the exact value in the Time object because
-  # floating point numbers cannot represent all rational numbers exactly.
+  # Returns the value of `self` as a Float number [Epoch
+  # seconds](rdoc-ref:Time@Epoch+Seconds); subseconds are included.
+  #
+  # The stored value of `self` is a [Rational](rdoc-ref:Rational@#method-i-to_f),
+  # which means that the returned value may be approximate:
   #
-  #     t = Time.now        #=> 2020-07-20 22:00:29.38740268 +0900
-  #     t.to_f              #=> 1595250029.3874028
-  #     t.to_i              #=> 1595250029
+  #     Time.utc(1970, 1, 1, 0, 0, 0).to_f         # => 0.0
+  #     Time.utc(1970, 1, 1, 0, 0, 0, 999999).to_f # => 0.999999
+  #     Time.utc(1950, 1, 1, 0, 0, 0).to_f         # => -631152000.0
+  #     Time.utc(1990, 1, 1, 0, 0, 0).to_f         # => 631152000.0
   #
-  # Note that IEEE 754 double is not accurate enough to represent the exact number
-  # of nanoseconds since the Epoch. (IEEE 754 double has 53bit mantissa. So it can
-  # represent exact number of nanoseconds only in `2 ** 53 / 1_000_000_000 / 60 /
-  # 60 / 24 = 104.2` days.) When Ruby uses a nanosecond-resolution clock function,
-  # such as `clock_gettime` of POSIX, to obtain the current time, Time#to_f can
-  # lose information of a Time object created with `Time.now`.
+  # Related: Time#to_i, Time#to_r.
   #
   def to_f: () -> Float
 
   # <!--
   #   rdoc-file=time.c
-  #   - time.to_i   -> int
-  #   - time.tv_sec -> int
+  #   - to_i -> integer
   # -->
-  # Returns the value of *time* as an integer number of seconds since the Epoch.
+  # Returns the value of `self` as integer [Epoch
+  # seconds](rdoc-ref:Time@Epoch+Seconds); subseconds are truncated (not rounded):
   #
-  # If *time* contains subsecond, they are truncated.
+  #     Time.utc(1970, 1, 1, 0, 0, 0).to_i         # => 0
+  #     Time.utc(1970, 1, 1, 0, 0, 0, 999999).to_i # => 0
+  #     Time.utc(1950, 1, 1, 0, 0, 0).to_i         # => -631152000
+  #     Time.utc(1990, 1, 1, 0, 0, 0).to_i         # => 631152000
   #
-  #     t = Time.now        #=> 2020-07-21 01:41:29.746012609 +0900
-  #     t.to_i              #=> 1595263289
+  # Related: Time#to_f Time#to_r.
   #
   def to_i: () -> Integer
 
   # <!--
   #   rdoc-file=time.c
-  #   - time.to_r -> a_rational
+  #   - to_r -> rational
   # -->
-  # Returns the value of *time* as a rational number of seconds since the Epoch.
+  # Returns the value of `self` as a Rational exact number of [Epoch
+  # seconds](rdoc-ref:Time@Epoch+Seconds);
   #
-  #     t = Time.now      #=> 2020-07-20 22:03:45.212167333 +0900
-  #     t.to_r            #=> (1595250225212167333/1000000000)
+  #     Time.now.to_r # => (16571402750320203/10000000)
   #
-  # This method is intended to be used to get an accurate value representing the
-  # seconds (including subsecond) since the Epoch.
+  # Related: Time#to_f, Time#to_i.
   #
   def to_r: () -> Rational
 
   # <!--
   #   rdoc-file=time.c
-  #   - time.to_s    -> string
+  #   - to_s    -> string
   # -->
-  # Returns a string representing *time*. Equivalent to calling #strftime with the
-  # appropriate format string.
+  # Returns a string representation of `self`, without subseconds:
   #
-  #     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"
+  #     t = Time.new(2000, 12, 31, 23, 59, 59, 0.5)
+  #     t.to_s    # => "2000-12-31 23:59:59 +0000"
+  #
+  # Related: Time#ctime, Time#inspect:
   #
-  #     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"
+  #     t.ctime   # => "Sun Dec 31 23:59:59 2000"
+  #     t.inspect # => "2000-12-31 23:59:59.5 +000001"
   #
   def to_s: () -> String
 
   # <!--
   #   rdoc-file=time.c
-  #   - time.tuesday? -> true or false
+  #   - tuesday? -> true or false
   # -->
-  # Returns `true` if *time* represents Tuesday.
+  # Returns `true` if `self` represents a Tuesday, `false` otherwise:
   #
-  #     t = Time.local(1991, 2, 19)      #=> 1991-02-19 00:00:00 -0600
-  #     t.tuesday?                       #=> true
+  #     t = Time.utc(2000, 1, 4) # => 2000-01-04 00:00:00 UTC
+  #     t.tuesday?               # => true
+  #
+  # Related: Time#wednesday?, Time#thursday?, Time#friday?.
   #
   def tuesday?: () -> bool
 
   # <!--
   #   rdoc-file=time.c
-  #   - time.nsec    -> int
-  #   - time.tv_nsec -> int
+  #   - nsec -> integer
   # -->
-  # Returns the number of nanoseconds for the subsecond part of *time*. The result
-  # is a non-negative integer less than 10**9.
-  #
-  #     t = Time.now        #=> 2020-07-20 22:07:10.963933942 +0900
-  #     t.nsec              #=> 963933942
+  # Returns the number of nanoseconds in the subseconds part of `self` in the
+  # range (0..999_999_999); lower-order digits are truncated, not rounded:
   #
-  # If *time* has fraction of nanosecond (such as picoseconds), it is truncated.
+  #     t = Time.now # => 2022-07-11 15:04:53.3219637 -0500
+  #     t.nsec       # => 321963700
   #
-  #     t = Time.new(2000,1,1,0,0,0.666_777_888_999r)
-  #     t.nsec              #=> 666777888
-  #
-  # Time#subsec can be used to obtain the subsecond part exactly.
+  # Related: Time#subsec (returns exact subseconds).
   #
   def tv_nsec: () -> Integer
 
   # <!-- rdoc-file=time.c -->
-  # Returns the value of *time* as an integer number of seconds since the Epoch.
+  # Returns the value of `self` as integer [Epoch
+  # seconds](rdoc-ref:Time@Epoch+Seconds); subseconds are truncated (not rounded):
   #
-  # If *time* contains subsecond, they are truncated.
+  #     Time.utc(1970, 1, 1, 0, 0, 0).to_i         # => 0
+  #     Time.utc(1970, 1, 1, 0, 0, 0, 999999).to_i # => 0
+  #     Time.utc(1950, 1, 1, 0, 0, 0).to_i         # => -631152000
+  #     Time.utc(1990, 1, 1, 0, 0, 0).to_i         # => 631152000
   #
-  #     t = Time.now        #=> 2020-07-21 01:41:29.746012609 +0900
-  #     t.to_i              #=> 1595263289
+  # Related: Time#to_f Time#to_r.
   #
   def tv_sec: () -> Integer
 
   # <!--
   #   rdoc-file=time.c
-  #   - time.usec    -> int
-  #   - time.tv_usec -> int
+  #   - usec -> integer
   # -->
-  # Returns the number of microseconds for the subsecond part of *time*. The
-  # result is a non-negative integer less than 10**6.
-  #
-  #     t = Time.now        #=> 2020-07-20 22:05:58.459785953 +0900
-  #     t.usec              #=> 459785
+  # Returns the number of microseconds in the subseconds part of `self` in the
+  # range (0..999_999); lower-order digits are truncated, not rounded:
   #
-  # If *time* has fraction of microsecond (such as nanoseconds), it is truncated.
+  #     t = Time.now # => 2022-07-11 14:59:47.5484697 -0500
+  #     t.usec       # => 548469
   #
-  #     t = Time.new(2000,1,1,0,0,0.666_777_888_999r)
-  #     t.usec              #=> 666777
-  #
-  # Time#subsec can be used to obtain the subsecond part exactly.
+  # Related: Time#subsec (returns exact subseconds).
   #
   def tv_usec: () -> Integer
 
   # <!-- rdoc-file=time.c -->
-  # Returns the number of microseconds for the subsecond part of *time*. The
-  # result is a non-negative integer less than 10**6.
-  #
-  #     t = Time.now        #=> 2020-07-20 22:05:58.459785953 +0900
-  #     t.usec              #=> 459785
+  # Returns the number of microseconds in the subseconds part of `self` in the
+  # range (0..999_999); lower-order digits are truncated, not rounded:
   #
-  # If *time* has fraction of microsecond (such as nanoseconds), it is truncated.
+  #     t = Time.now # => 2022-07-11 14:59:47.5484697 -0500
+  #     t.usec       # => 548469
   #
-  #     t = Time.new(2000,1,1,0,0,0.666_777_888_999r)
-  #     t.usec              #=> 666777
-  #
-  # Time#subsec can be used to obtain the subsecond part exactly.
+  # Related: Time#subsec (returns exact subseconds).
   #
   def usec: () -> Integer
 
   # <!-- rdoc-file=time.c -->
-  # Converts *time* to UTC (GMT), modifying the receiver.
+  # Returns `self`, converted to the UTC timezone:
   #
-  #     t = Time.now   #=> 2007-11-19 08:18:31 -0600
-  #     t.gmt?         #=> false
-  #     t.gmtime       #=> 2007-11-19 14:18:31 UTC
-  #     t.gmt?         #=> true
+  #     t = Time.new(2000) # => 2000-01-01 00:00:00 -0600
+  #     t.utc?             # => false
+  #     t.utc              # => 2000-01-01 06:00:00 UTC
+  #     t.utc?             # => true
   #
-  #     t = Time.now   #=> 2007-11-19 08:18:51 -0600
-  #     t.utc?         #=> false
-  #     t.utc          #=> 2007-11-19 14:18:51 UTC
-  #     t.utc?         #=> true
+  # Related: Time#getutc (returns a new converted `Time` object).
   #
   def utc: () -> Time
 
   # <!--
   #   rdoc-file=time.c
-  #   - time.utc? -> true or false
-  #   - time.gmt? -> true or false
+  #   - utc? -> true or false
   # -->
-  # Returns `true` if *time* represents a time in UTC (GMT).
+  # Returns `true` if `self` represents a time in UTC (GMT):
   #
-  #     t = Time.now                        #=> 2007-11-19 08:15:23 -0600
-  #     t.utc?                              #=> false
-  #     t = Time.gm(2000,"jan",1,20,15,1)   #=> 2000-01-01 20:15:01 UTC
-  #     t.utc?                              #=> true
+  #     now = Time.now
+  #     # => 2022-08-18 10:24:13.5398485 -0500
+  #     now.utc? # => false
+  #     utc = Time.utc(2000, 1, 1, 20, 15, 1)
+  #     # => 2000-01-01 20:15:01 UTC
+  #     utc.utc? # => true
   #
-  #     t = Time.now                        #=> 2007-11-19 08:16:03 -0600
-  #     t.gmt?                              #=> false
-  #     t = Time.gm(2000,1,1,20,15,1)       #=> 2000-01-01 20:15:01 UTC
-  #     t.gmt?                              #=> true
+  # Related: Time.utc.
   #
   def utc?: () -> bool
 
   # <!-- rdoc-file=time.c -->
-  # 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.
   #
   def utc_offset: () -> Integer
 
   # <!--
   #   rdoc-file=time.c
-  #   - time.wday -> integer
+  #   - wday -> integer
   # -->
-  # Returns an integer representing the day of the week, 0..6, with Sunday == 0.
-  #
-  #     t = Time.now   #=> 2007-11-20 02:35:35 -0600
-  #     t.wday         #=> 2
-  #     t.sunday?      #=> false
-  #     t.monday?      #=> false
-  #     t.tuesday?     #=> true
-  #     t.wednesday?   #=> false
-  #     t.thursday?    #=> false
-  #     t.friday?      #=> false
-  #     t.saturday?    #=> false
+  # Returns the integer day of the week for `self`, in range (0..6), with Sunday
+  # as zero.
+  #
+  #     t = Time.new(2000, 1, 2, 3, 4, 5, 6)
+  #     # => 2000-01-02 03:04:05 +000006
+  #     t.wday    # => 0
+  #     t.sunday? # => true
+  #
+  # Related: Time#year, Time#hour, Time#min.
   #
   def wday: () -> Integer
 
   # <!--
   #   rdoc-file=time.c
-  #   - time.wednesday? -> true or false
+  #   - wednesday? -> true or false
   # -->
-  # Returns `true` if *time* represents Wednesday.
+  # Returns `true` if `self` represents a Wednesday, `false` otherwise:
   #
-  #     t = Time.local(1993, 2, 24)      #=> 1993-02-24 00:00:00 -0600
-  #     t.wednesday?                     #=> true
+  #     t = Time.utc(2000, 1, 5) # => 2000-01-05 00:00:00 UTC
+  #     t.wednesday?             # => true
+  #
+  # Related: Time#thursday?, Time#friday?, Time#saturday?.
   #
   def wednesday?: () -> bool
 
+  # <!--
+  #   rdoc-file=lib/time.rb
+  #   - xmlschema(fraction_digits=0)
+  # -->
+  # Returns a string which represents the time as a dateTime defined by XML
+  # Schema:
+  #
+  #     CCYY-MM-DDThh:mm:ssTZD
+  #     CCYY-MM-DDThh:mm:ss.sssTZD
+  #
+  # where TZD is Z or [+-]hh:mm.
+  #
+  # If self is a UTC time, Z is used as TZD.  [+-]hh:mm is used otherwise.
+  #
+  # `fraction_digits` specifies a number of digits to use for fractional seconds.
+  # Its default value is 0.
+  #
+  #     require 'time'
+  #
+  #     t = Time.now
+  #     t.iso8601  # => "2011-10-05T22:26:12-04:00"
+  #
+  # You must require 'time' to use this method.
+  #
+  def xmlschema: (?Integer fraction_digits) -> String
+
   # <!--
   #   rdoc-file=time.c
-  #   - 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
   #
   def yday: () -> Integer
 
   # <!--
   #   rdoc-file=time.c
-  #   - time.year -> integer
+  #   - year -> integer
   # -->
-  # Returns the year for *time* (including the century).
+  # Returns the integer year for `self`:
+  #
+  #     t = Time.new(2000, 1, 2, 3, 4, 5, 6)
+  #     # => 2000-01-02 03:04:05 +000006
+  #     t.year # => 2000
   #
-  #     t = Time.now   #=> 2007-11-19 08:27:51 -0600
-  #     t.year         #=> 2007
+  # Related: Time#mon, Time#hour, Time#min.
   #
   def year: () -> Integer
 
@@ -1362,99 +1660,101 @@ class Time < Object
   #   rdoc-file=time.c
   #   - 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"
   #
-  def zone: () -> String
+  def zone: () -> String?
 
-  # Same as Time::gm, but interprets the values in the local time zone.
+  # <!-- rdoc-file=time.c -->
+  # Like Time.utc, except that the returned `Time` object has the local timezone,
+  # not the UTC timezone:
   #
-  #     Time.local(2000,"jan",1,20,15,1)   #=> 2000-01-01 20:15:01 -0600
+  #     # 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
   #
   def self.mktime: (Integer year, ?Integer | String month, ?Integer day, ?Integer hour, ?Integer min, ?Numeric sec, ?Numeric usec_with_frac) -> Time
 
   # <!--
   #   rdoc-file=time.c
-  #   - 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.
   #
   def gmtoff: () -> Integer
 
   # <!-- rdoc-file=time.c -->
-  # Returns the month of the year (1..12) for *time*.
+  # Returns the integer month of the year for `self`, in range (1..12):
+  #
+  #     t = Time.new(2000, 1, 2, 3, 4, 5, 6)
+  #     # => 2000-01-02 03:04:05 +000006
+  #     t.mon # => 1
   #
-  #     t = Time.now   #=> 2007-11-19 08:27:30 -0600
-  #     t.mon          #=> 11
-  #     t.month        #=> 11
+  # Related: Time#year, Time#hour, Time#min.
   #
   def month: () -> Integer
 
   # <!--
   #   rdoc-file=time.c
-  #   - time.floor([ndigits])   -> new_time
+  #   - floor(ndigits = 0) -> new_time
   # -->
-  # Floors subsecond to a given precision in decimal digits (0 digits by default).
-  # It returns a new Time object. `ndigits` should be zero or a positive integer.
+  # Returns a new `Time` object whose numerical value is less than or equal to
+  # `self` with its seconds truncated to precision `ndigits`:
   #
-  #     t = Time.utc(2010,3,30, 5,43,25.123456789r)
-  #     t                       #=> 2010-03-30 05:43:25.123456789 UTC
-  #     t.floor                 #=> 2010-03-30 05:43:25 UTC
-  #     t.floor(0)              #=> 2010-03-30 05:43:25 UTC
-  #     t.floor(1)              #=> 2010-03-30 05:43:25.1 UTC
-  #     t.floor(2)              #=> 2010-03-30 05:43:25.12 UTC
-  #     t.floor(3)              #=> 2010-03-30 05:43:25.123 UTC
-  #     t.floor(4)              #=> 2010-03-30 05:43:25.1234 UTC
+  #     t = Time.utc(2010, 3, 30, 5, 43, 25.123456789r)
+  #     t           # => 2010-03-30 05:43:25.123456789 UTC
+  #     t.floor     # => 2010-03-30 05:43:25 UTC
+  #     t.floor(2)  # => 2010-03-30 05:43:25.12 UTC
+  #     t.floor(4)  # => 2010-03-30 05:43:25.1234 UTC
+  #     t.floor(6)  # => 2010-03-30 05:43:25.123456 UTC
+  #     t.floor(8)  # => 2010-03-30 05:43:25.12345678 UTC
+  #     t.floor(10) # => 2010-03-30 05:43:25.123456789 UTC
   #
-  #     t = Time.utc(1999,12,31, 23,59,59)
-  #     (t + 0.4).floor    #=> 1999-12-31 23:59:59 UTC
-  #     (t + 0.9).floor    #=> 1999-12-31 23:59:59 UTC
-  #     (t + 1.4).floor    #=> 2000-01-01 00:00:00 UTC
-  #     (t + 1.9).floor    #=> 2000-01-01 00:00:00 UTC
+  #     t = Time.utc(1999, 12, 31, 23, 59, 59)
+  #     t               # => 1999-12-31 23:59:59 UTC
+  #     (t + 0.4).floor # => 1999-12-31 23:59:59 UTC
+  #     (t + 0.9).floor # => 1999-12-31 23:59:59 UTC
+  #     (t + 1.4).floor # => 2000-01-01 00:00:00 UTC
+  #     (t + 1.9).floor # => 2000-01-01 00:00:00 UTC
   #
-  #     t = Time.utc(1999,12,31, 23,59,59)
-  #     (t + 0.123456789).floor(4)  #=> 1999-12-31 23:59:59.1234 UTC
+  # Related: Time#ceil, Time#round.
   #
-  def floor: (?Integer ndigits) -> Time
+  def floor: (?int ndigits) -> Time
 
   # <!--
   #   rdoc-file=time.c
-  #   - time.ceil([ndigits])   -> new_time
+  #   - ceil(ndigits = 0)   -> new_time
   # -->
-  # Ceils subsecond to a given precision in decimal digits (0 digits by default).
-  # It returns a new Time object. `ndigits` should be zero or a positive integer.
-  #
-  #     t = Time.utc(2010,3,30, 5,43,25.0123456789r)
-  #     t                      #=> 2010-03-30 05:43:25 123456789/10000000000 UTC
-  #     t.ceil                 #=> 2010-03-30 05:43:26 UTC
-  #     t.ceil(0)              #=> 2010-03-30 05:43:26 UTC
-  #     t.ceil(1)              #=> 2010-03-30 05:43:25.1 UTC
-  #     t.ceil(2)              #=> 2010-03-30 05:43:25.02 UTC
-  #     t.ceil(3)              #=> 2010-03-30 05:43:25.013 UTC
-  #     t.ceil(4)              #=> 2010-03-30 05:43:25.0124 UTC
-  #
-  #     t = Time.utc(1999,12,31, 23,59,59)
-  #     (t + 0.4).ceil         #=> 2000-01-01 00:00:00 UTC
-  #     (t + 0.9).ceil         #=> 2000-01-01 00:00:00 UTC
-  #     (t + 1.4).ceil         #=> 2000-01-01 00:00:01 UTC
-  #     (t + 1.9).ceil         #=> 2000-01-01 00:00:01 UTC
-  #
-  #     t = Time.utc(1999,12,31, 23,59,59)
-  #     (t + 0.123456789).ceil(4)  #=> 1999-12-31 23:59:59.1235 UTC
-  #
-  def ceil: (?Integer ndigits) -> Time
+  # Returns a new `Time` object whose numerical value is greater than or equal to
+  # `self` with its seconds truncated to precision `ndigits`:
+  #
+  #     t = Time.utc(2010, 3, 30, 5, 43, 25.123456789r)
+  #     t          # => 2010-03-30 05:43:25.123456789 UTC
+  #     t.ceil     # => 2010-03-30 05:43:26 UTC
+  #     t.ceil(2)  # => 2010-03-30 05:43:25.13 UTC
+  #     t.ceil(4)  # => 2010-03-30 05:43:25.1235 UTC
+  #     t.ceil(6)  # => 2010-03-30 05:43:25.123457 UTC
+  #     t.ceil(8)  # => 2010-03-30 05:43:25.12345679 UTC
+  #     t.ceil(10) # => 2010-03-30 05:43:25.123456789 UTC
+  #
+  #     t = Time.utc(1999, 12, 31, 23, 59, 59)
+  #     t              # => 1999-12-31 23:59:59 UTC
+  #     (t + 0.4).ceil # => 2000-01-01 00:00:00 UTC
+  #     (t + 0.9).ceil # => 2000-01-01 00:00:00 UTC
+  #     (t + 1.4).ceil # => 2000-01-01 00:00:01 UTC
+  #     (t + 1.9).ceil # => 2000-01-01 00:00:01 UTC
+  #
+  # Related: Time#floor, Time#round.
+  #
+  def ceil: (?int ndigits) -> Time
 end
 
 Time::RFC2822_DAY_NAME: Array[String]