rbs 3.7.0 → 3.8.0

data/core/time.rbs

@@ -45,6 +45,42 @@
 # 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.
@@ -127,16 +163,14 @@
 # *   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}](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).
-#
+# *   [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
 #
@@ -150,7 +184,6 @@
 # *   #+ (plus): Returns a new time increased by the given number of seconds.
 # *   #- (minus): Returns a new time decreased by the given number of seconds.
 #
-#
 # ### Methods for Fetching
 #
 # *   #year: Returns the year of the time.
@@ -175,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.
@@ -189,13 +221,11 @@
 # *   #friday?: Returns whether time is a Friday.
 # *   #saturday?: Returns whether the time is a Saturday.
 #
-#
 # ### Methods for Comparing
 #
 # *   #<=>: 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.
@@ -210,14 +240,12 @@
 # *   #deconstruct_keys: Returns a hash of time components used in
 #     pattern-matching.
 #
-#
 # ### Methods for Rounding
 #
 # *   #round:Returns a new time with subseconds rounded.
 # *   #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).
 #
@@ -231,7 +259,6 @@
 # *   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):
 #
@@ -241,7 +268,6 @@
 # *   [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
@@ -250,7 +276,6 @@
 # *   `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
@@ -289,22 +314,33 @@
 #
 # *   `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.
+#     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`.
-#     *   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.
+#     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
@@ -312,26 +348,37 @@
 #
 # *   `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.
+#     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.
+#     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`:
 #
-#     *   Called when `Marshal.dump(t)` is invoked
-#     *   Argument: none.
-#     *   Returns: the string name of the timezone.
+#     Called when `Marshal.dump(t)` is invoked
+#
+#     Argument
+# :       none.
 #
+#     Returns
+# :       the string name of the timezone.
 #
 #
 # #### `Time`-Like Objects
@@ -358,7 +405,6 @@
 # *   `isdst`
 # *   `to_i`
 #
-#
 # For a returned `Integer`, its components, decomposed in UTC, are interpreted
 # as times in the specified timezone.
 #
@@ -424,7 +470,6 @@ class Time < Object
   # *   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
@@ -460,7 +505,6 @@ class Time < Object
   #         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:
   #
@@ -527,7 +571,6 @@ class Time < Object
   #         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.
@@ -542,7 +585,6 @@ class Time < Object
   #         # => ["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:
   #
@@ -659,7 +701,6 @@ class Time < Object
   #         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.
@@ -674,7 +715,6 @@ class Time < Object
   #         # => ["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:
   #
@@ -756,7 +796,6 @@ class Time < Object
   # *   `1`, if `self` is greater then `other_time`.
   # *   `nil`, if `self` and `other_time` are incomparable.
   #
-  #
   # Examples:
   #
   #     t = Time.now     # => 2007-11-19 08:12:12 -0600
@@ -1066,7 +1105,6 @@ class Time < Object
   #         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
   #
-  #
   # These values may be:
   #
   # *   Integers, as above.
@@ -1081,7 +1119,6 @@ class Time < Object
   #         # => ["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):
@@ -1138,6 +1175,25 @@ class Time < Object
   #
   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
   #   - localtime -> self or new_time
@@ -1151,7 +1207,6 @@ class Time < Object
   #         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
   #
-  #
   # With argument `zone` given, returns the new `Time` object created by
   # converting `self` to the given time zone:
   #
@@ -1550,6 +1605,32 @@ class Time < Object
   #
   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: () -> String
+
   # <!--
   #   rdoc-file=time.c
   #   - yday -> integer