core/time.rbs in rbs-3.3.2 vs core/time.rbs in rbs-3.4.0.pre.1

- old
+ new

@@ -1,7 +1,7 @@ # <!-- rdoc-file=timev.rb --> -# A Time object represents a date and time: +# A `Time` object represents a date and time: # # Time.new(2000, 1, 1, 0, 0, 0) # => 2000-01-01 00:00:00 -0600 # # 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 @@ -40,18 +40,18 @@ # 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. +# A `Time` object derived from the system clock (for example, by method +# Time.now) has the resolution supported by the system. # # ## 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 # time to Time.new such as year, month, minute, etc. When you want to construct # a time this way you must pass at least a year. If you pass the year with @@ -64,11 +64,11 @@ # # You can pass a UTC offset: # # 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 # # You can also use Time.local and Time.utc to infer local and UTC timezones @@ -78,11 +78,11 @@ # (with subsecond) since the [Unix # Epoch](https://en.wikipedia.org/wiki/Unix_time). # # 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 # work on the assumption that you have done the following: # @@ -120,24 +120,24 @@ # # Time.new(2010,10,31).between?(t1, t2) #=> true # # ## What's Here # -# First, what's elsewhere. Class Time: +# 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: +# 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 # # * ::new: Returns a new time from specified arguments (year, month, etc.), @@ -217,24 +217,191 @@ # * #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:timezones.rdoc). +# 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`. +# * 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`: +# +# * Called when `Marshal.dump(t)` is invoked +# * Argument: none. +# * Returns: the string name of the timezone. +# +# +# +# #### `Time`-Like Objects +# +# A `Time`-like object is a container object capable of interfacing with +# timezone libraries for timezone conversion. +# +# The argument to the timezone conversion methods above will have attributes +# similar to Time, except that timezone related attributes are meaningless. +# +# 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. +# +# 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 include Comparable # <!-- # rdoc-file=timev.rb # - at(time, subsec = false, unit = :microsecond, in: nil) # --> - # Returns a new Time object based on the given arguments. + # 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 + # * 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. # # @@ -272,27 +439,27 @@ # 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 + # 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:timezones.rdoc). + # Specifiers](rdoc-ref:Time@Timezone+Specifiers). # def self.at: (Time, ?in: String | Integer | nil) -> Time | (Numeric, ?in: String | Integer | nil) -> Time | (Integer sec_i, Numeric msec, subsec_unit msec, ?in: String | Integer | nil) -> Time type subsec_unit = :msec | :millisecond | :usec | :microsecond | :nsec | :nanosecond # <!-- rdoc-file=time.c --> - # Returns a new Time object based the on given arguments, in the UTC timezone. + # 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) @@ -365,11 +532,11 @@ # # 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 + # 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 @@ -379,22 +546,20 @@ # above. # # Raises an exception if the number of arguments is eight, nine, or greater than # ten. # - # Time.gm is an alias for Time.utc. - # # 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, + # 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 @@ -406,27 +571,27 @@ # <!-- # 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 # # For forms of argument `zone`, see [Timezone - # Specifiers](rdoc-ref:timezones.rdoc). + # Specifiers](rdoc-ref:Time@Timezone+Specifiers). # def self.now: (?in: String | Integer | nil) -> Time # <!-- # rdoc-file=time.c # - 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, in the UTC timezone. + # 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) @@ -499,11 +664,11 @@ # # 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 + # 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 @@ -513,21 +678,19 @@ # above. # # Raises an exception if the number of arguments is eight, nine, or greater than # ten. # - # Time.gm is an alias for Time.utc. - # # Related: Time.local. # def self.utc: (Integer year, ?Integer | String month, ?Integer day, ?Integer hour, ?Integer min, ?Numeric sec, ?Numeric usec_with_frac) -> Time # <!-- # rdoc-file=time.c # - self + numeric -> new_time # --> - # Returns a new Time object whose value is the sum of the numeric value of + # 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 @@ -539,19 +702,19 @@ # <!-- # rdoc-file=time.c # - self - numeric -> new_time # - self - other_time -> float # --> - # When `numeric` is given, returns a new Time object whose value is the + # 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`: + # the numeric values of `self` and `other_time` in seconds: # # t - t # => 0.0 # # Related: Time#+. # @@ -604,12 +767,10 @@ # 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" # - # Time#asctime is an alias for Time#ctime. - # # 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" # @@ -626,12 +787,10 @@ # 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" # - # Time#asctime is an alias for Time#ctime. - # # 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" # @@ -642,12 +801,10 @@ # # t = Time.new(2000, 1, 2, 3, 4, 5, 6) # # => 2000-01-02 03:04:05 +000006 # t.mday # => 2 # - # Time#day is an alias for Time#mday. - # # Related: Time#year, Time#hour, Time#min. # def day: () -> Integer # <!-- @@ -693,20 +850,18 @@ # t.dst? # => false # t = Time.local(2000, 7, 1) # => 2000-07-01 00:00:00 -0500 # t.zone # => "Central Daylight Time" # t.dst? # => true # - # Time#isdst is an alias for Time#dst?. - # def dst?: () -> bool # <!-- # rdoc-file=time.c # - eql?(other_time) # --> - # Returns `true` if `self` and `other_time` are both Time objects with the exact - # same time value. + # 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 @@ -723,51 +878,47 @@ # <!-- # rdoc-file=time.c # - getutc -> new_time # --> - # Returns a new Time object representing the value of `self` converted to the + # Returns a new `Time` object representing the value of `self` converted to the # UTC timezone: # # 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 # - # Time#getgm is an alias for Time#getutc. - # def getgm: () -> Time # <!-- # rdoc-file=time.c # - getlocal(zone = nil) -> new_time # --> - # Returns a new Time object representing the value of `self` converted to a + # Returns a new `Time` object representing the value of `self` converted to a # given timezone; if `zone` is `nil`, the local timezone is used: # # 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 # # For forms of argument `zone`, see [Timezone - # Specifiers](rdoc-ref:timezones.rdoc). + # Specifiers](rdoc-ref:Time@Timezone+Specifiers). # def getlocal: (?Integer utc_offset) -> Time # <!-- rdoc-file=time.c --> - # Returns a new Time object representing the value of `self` converted to the + # Returns a new `Time` object representing the value of `self` converted to the # UTC timezone: # # 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 # - # Time#getgm is an alias for Time#getutc. - # def getutc: () -> Time # <!-- rdoc-file=time.c --> # Returns `true` if `self` represents a time in UTC (GMT): # @@ -776,24 +927,20 @@ # now.utc? # => false # utc = Time.utc(2000, 1, 1, 20, 15, 1) # # => 2000-01-01 20:15:01 UTC # utc.utc? # => true # - # Time#gmt? is an alias for Time#utc?. - # # Related: Time.utc. # def gmt?: () -> bool # <!-- rdoc-file=time.c --> # Returns the offset in seconds between the timezones of UTC and `self`: # # Time.utc(2000, 1, 1).utc_offset # => 0 # Time.local(2000, 1, 1).utc_offset # => -21600 # -6*3600, or minus six hours. # - # Time#gmt_offset and Time#gmtoff are aliases for Time#utc_offset. - # def gmt_offset: () -> Integer # <!-- # rdoc-file=time.c # - utc -> self @@ -803,14 +950,12 @@ # 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 # - # Time#gmtime is an alias for Time#utc. + # Related: Time#getutc (returns a new converted `Time` object). # - # Related: Time#getutc (returns a new converted Time object). - # def gmtime: () -> Time # <!-- # rdoc-file=time.c # - hash -> integer @@ -835,29 +980,29 @@ # def hour: () -> Integer # <!-- # rdoc-file=timev.rb - # - new(year = (now = true), mon = (str = year; nil), mday = nil, hour = nil, min = nil, sec = nil, zone = nil, in: nil, precision: 9) + # - 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, by default in the + # 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 # - # With one string argument that represents a time, returns a new Time object + # 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 + # 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`): @@ -916,23 +1061,29 @@ # # => ["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:timezones.rdoc): + # `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. + # 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 @@ -963,36 +1114,34 @@ # t.dst? # => false # t = Time.local(2000, 7, 1) # => 2000-07-01 00:00:00 -0500 # t.zone # => "Central Daylight Time" # t.dst? # => true # - # Time#isdst is an alias for Time#dst?. - # def isdst: () -> bool # <!-- # rdoc-file=time.c # - localtime -> self or new_time # - localtime(zone) -> new_time # --> # With no argument given: # # * Returns `self` if `self` is a local time. - # * Otherwise returns a new Time in the user's local timezone: + # * Otherwise returns a new `Time` in the user's local timezone: # # 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: + # With argument `zone` given, returns the new `Time` object created by + # converting `self` to the given time zone: # # 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 # # For forms of argument `zone`, see [Timezone - # Specifiers](rdoc-ref:timezones.rdoc). + # Specifiers](rdoc-ref:Time@Timezone+Specifiers). # def localtime: (?String utc_offset) -> Time # <!-- # rdoc-file=time.c @@ -1002,12 +1151,10 @@ # # t = Time.new(2000, 1, 2, 3, 4, 5, 6) # # => 2000-01-02 03:04:05 +000006 # t.mday # => 2 # - # Time#day is an alias for Time#mday. - # # Related: Time#year, Time#hour, Time#min. # def mday: () -> Integer # <!-- @@ -1032,12 +1179,10 @@ # # t = Time.new(2000, 1, 2, 3, 4, 5, 6) # # => 2000-01-02 03:04:05 +000006 # t.mon # => 1 # - # Time#month is an alias for Time#mday. - # # Related: Time#year, Time#hour, Time#min. # def mon: () -> Integer # <!-- @@ -1060,19 +1205,17 @@ # t = Time.now # => 2022-07-11 15:04:53.3219637 -0500 # t.nsec # => 321963700 # # Related: Time#subsec (returns exact subseconds). # - # Time#tv_nsec is an alias for Time#usec. - # def nsec: () -> Integer # <!-- # rdoc-file=time.c # - round(ndigits = 0) -> new_time # --> - # Returns a new Time object whose numeric value is that of `self`, with its + # 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 @@ -1186,11 +1329,11 @@ # 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] # # The returned array is suitable for use as an argument to Time.utc or - # Time.local to create a new Time object. + # Time.local to create a new `Time` object. # def to_a: () -> [ Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, bool, String ] # <!-- # rdoc-file=time.c @@ -1221,12 +1364,10 @@ # 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 # - # Time#tv_sec is an alias for Time#to_i. - # # Related: Time#to_f Time#to_r. # def to_i: () -> Integer # <!-- @@ -1281,12 +1422,10 @@ # t = Time.now # => 2022-07-11 15:04:53.3219637 -0500 # t.nsec # => 321963700 # # Related: Time#subsec (returns exact subseconds). # - # Time#tv_nsec is an alias for Time#usec. - # def tv_nsec: () -> Integer # <!-- rdoc-file=time.c --> # Returns the value of `self` as integer [Epoch # seconds](rdoc-ref:Time@Epoch+Seconds); subseconds are truncated (not rounded): @@ -1294,12 +1433,10 @@ # 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 # - # Time#tv_sec is an alias for Time#to_i. - # # Related: Time#to_f Time#to_r. # def tv_sec: () -> Integer # <!-- @@ -1312,12 +1449,10 @@ # t = Time.now # => 2022-07-11 14:59:47.5484697 -0500 # t.usec # => 548469 # # Related: Time#subsec (returns exact subseconds). # - # Time#tv_usec is an alias for Time#usec. - # def tv_usec: () -> Integer # <!-- rdoc-file=time.c --> # Returns the number of microseconds in the subseconds part of `self` in the # range (0..999_999); lower-order digits are truncated, not rounded: @@ -1325,26 +1460,22 @@ # t = Time.now # => 2022-07-11 14:59:47.5484697 -0500 # t.usec # => 548469 # # Related: Time#subsec (returns exact subseconds). # - # Time#tv_usec is an alias for Time#usec. - # def usec: () -> Integer # <!-- rdoc-file=time.c --> # Returns `self`, converted to the UTC timezone: # # 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 # - # Time#gmtime is an alias for Time#utc. + # Related: Time#getutc (returns a new converted `Time` object). # - # Related: Time#getutc (returns a new converted Time object). - # def utc: () -> Time # <!-- # rdoc-file=time.c # - utc? -> true or false @@ -1356,24 +1487,20 @@ # now.utc? # => false # utc = Time.utc(2000, 1, 1, 20, 15, 1) # # => 2000-01-01 20:15:01 UTC # utc.utc? # => true # - # Time#gmt? is an alias for Time#utc?. - # # Related: Time.utc. # def utc?: () -> bool # <!-- rdoc-file=time.c --> # Returns the offset in seconds between the timezones of UTC and `self`: # # Time.utc(2000, 1, 1).utc_offset # => 0 # Time.local(2000, 1, 1).utc_offset # => -21600 # -6*3600, or minus six hours. # - # Time#gmt_offset and Time#gmtoff are aliases for Time#utc_offset. - # def utc_offset: () -> Integer # <!-- # rdoc-file=time.c # - wday -> integer @@ -1438,11 +1565,11 @@ # Time.new(2000, 1, 1).zone # => "Central Standard Time" # def zone: () -> String # <!-- rdoc-file=time.c --> - # Like Time.utc, except that the returned Time object has the local timezone, + # 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 @@ -1459,32 +1586,28 @@ # Returns the offset in seconds between the timezones of UTC and `self`: # # Time.utc(2000, 1, 1).utc_offset # => 0 # Time.local(2000, 1, 1).utc_offset # => -21600 # -6*3600, or minus six hours. # - # Time#gmt_offset and Time#gmtoff are aliases for Time#utc_offset. - # def gmtoff: () -> Integer # <!-- rdoc-file=time.c --> # 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 # - # Time#month is an alias for Time#mday. - # # Related: Time#year, Time#hour, Time#min. # def month: () -> Integer # <!-- # rdoc-file=time.c # - floor(ndigits = 0) -> new_time # --> - # Returns a new Time object whose numerical value is less than or equal to + # 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 @@ -1507,10 +1630,10 @@ # <!-- # rdoc-file=time.c # - ceil(ndigits = 0) -> new_time # --> - # Returns a new Time object whose numerical value is greater than or equal to + # 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