# [Time](Time) is an abstraction of dates and times. # [Time](Time) is stored internally as the number of # seconds with fraction since the *Epoch* , January 1, 1970 00:00 UTC. # Also see the library module Date. The [Time](Time) # class treats GMT (Greenwich Mean [Time](Time) ) and # UTC (Coordinated Universal [Time](Time) ) as # equivalent. GMT is the older way of referring to these baseline times # but persists in the names of calls on POSIX systems. # # All times may have fraction. 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 1.9.2, [Time](Time) implementation uses a # signed 63 bit integer, Bignum or # [Rational](https://ruby-doc.org/core-2.6.3/Rational.html). The integer # is a number of nanoseconds since the *Epoch* which can represent # 1823-11-12 to 2116-02-20. When Bignum or # [Rational](https://ruby-doc.org/core-2.6.3/Rational.html) is used # (before 1823, after 2116, under nanosecond), # [Time](Time) works slower as when integer is used. # # # All of these examples were done using the EST timezone which is GMT-5. # # # You can create a new instance of [Time](Time) with # [::new](Time#method-c-new). This will use the # current system time. [::now](Time#method-c-now) is # an alias for this. You can also pass parts of the time to # [::new](Time#method-c-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 nothing else time will default # to January 1 of that year at 00:00:00 with the current system timezone. # Here are some examples: # # ```ruby # Time.new(2002) #=> 2002-01-01 00:00:00 -0500 # Time.new(2002, 10) #=> 2002-10-01 00:00:00 -0500 # Time.new(2002, 10, 31) #=> 2002-10-31 00:00:00 -0500 # ``` # # You can pass a UTC offset: # # ```ruby # Time.new(2002, 10, 31, 2, 2, 2, "+02:00") #=> 2002-10-31 02:02:02 +0200 # ``` # # Or a timezone object: # # ```ruby # tz = timezone("Europe/Athens") # Eastern European Time, UTC+2 # Time.new(2002, 10, 31, 2, 2, 2, tz) #=> 2002-10-31 02:02:02 +0200 # ``` # # You can also use [::gm](Time#method-c-gm), # [::local](Time#method-c-local) and # [::utc](Time#method-c-utc) to infer GMT, local and # UTC timezones instead of using the current system setting. # # You can also create a new time using # [::at](Time#method-c-at) which takes the number of # seconds (or fraction of seconds) since the [Unix # Epoch](http://en.wikipedia.org/wiki/Unix_time). # # ```ruby # Time.at(628232400) #=> 1989-11-28 00:00:00 -0500 # ``` # # # Once you have an instance of [Time](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: # # ```ruby # t = Time.new(1993, 02, 24, 12, 0, 0, "+09:00") # ``` # # Was that a monday? # # ```ruby # t.monday? #=> false # ``` # # What year was that again? # # ```ruby # t.year #=> 1993 # ``` # # Was it daylight savings at the time? # # ```ruby # t.dst? #=> false # ``` # # What’s the day a year later? # # ```ruby # t + (60*60*24*365) #=> 1994-02-24 12:00:00 +0900 # ``` # # How many seconds was that since the Unix Epoch? # # ```ruby # t.to_i #=> 730522800 # ``` # # You can also do standard functions like compare two times. # # ```ruby # t1 = Time.new(2010) # t2 = Time.new(2011) # # t1 == t2 #=> false # t1 == t1 #=> true # t1 < t2 #=> true # t1 > t2 #=> false # # Time.new(2010,10,31).between?(t1, t2) #=> true # ``` # # # A timezone argument must have `local_to_utc` and `utc_to_local` methods, # and may have `name` and `abbr` methods. # # 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](Time) or Time-like object (not # necessary to be the same class). The # [zone](Time#method-i-zone) of the result is just # ignored. Time-like argument to these methods is similar to a # [Time](Time) object in UTC without sub-second; it # has attribute readers for the parts, e.g. # [year](Time#method-i-year), # [month](Time#method-i-month), and so on, and epoch # time readers, [to\_i](Time#method-i-to_i). The # sub-second attributes are fixed as 0, and # [utc\_offset](Time#method-i-utc_offset), # [zone](Time#method-i-zone), # [isdst](Time#method-i-isdst), and their aliases are # same as a [Time](Time) object in UTC. Also to\_time, # \#+, and \#- methods are defined. # # The `name` method is used for marshaling. If this method is not defined # on a timezone object, [Time](Time) objects using # that timezone object can not be dumped by # [Marshal](https://ruby-doc.org/core-2.6.3/Marshal.html). # # The `abbr` method is used by ‘%Z’ in # [strftime](Time#method-i-strftime). # # # At loading marshaled data, a timezone name will be converted to a # timezone object by `find_timezone` class method, if the method is # defined. # # Similary, that class method will be called when a timezone argument does # not have the necessary methods mentioned above. class Time < Object include Comparable def self.at: (Time | Numeric seconds) -> Time | (Numeric seconds, ?Numeric microseconds_with_frac) -> Time def self.gm: (Integer year, ?Integer | String month, ?Integer day, ?Integer hour, ?Integer min, ?Numeric sec, ?Numeric usec_with_frac) -> Time def self.local: (Integer year, ?Integer | String month, ?Integer day, ?Integer hour, ?Integer min, ?Numeric sec, ?Numeric usec_with_frac) -> Time # Creates a new [Time](Time.downloaded.ruby_doc) object for the current # time. This is same as [::new](Time.downloaded.ruby_doc#method-c-new) # without arguments. # # ```ruby # Time.now #=> 2009-06-24 12:39:54 +0900 # ``` def self.now: () -> Time def self.utc: (Integer year, ?Integer | String month, ?Integer day, ?Integer hour, ?Integer min, ?Numeric sec, ?Numeric usec_with_frac) -> Time def +: (Numeric arg0) -> Time def -: (Time arg0) -> Float | (Numeric arg0) -> Time def <: (Time arg0) -> bool def <=: (Time arg0) -> bool def <=>: (Time other) -> Integer? def >: (Time arg0) -> bool def >=: (Time arg0) -> bool # Returns a canonical string representation of *time* . # # ```ruby # Time.now.asctime #=> "Wed Apr 9 08:56:03 2003" # Time.now.ctime #=> "Wed Apr 9 08:56:03 2003" # ``` def asctime: () -> String # Returns a canonical string representation of *time* . # # ```ruby # Time.now.asctime #=> "Wed Apr 9 08:56:03 2003" # Time.now.ctime #=> "Wed Apr 9 08:56:03 2003" # ``` def ctime: () -> String # Returns the day of the month (1..n) for *time* . # # ```ruby # t = Time.now #=> 2007-11-19 08:27:03 -0600 # t.day #=> 19 # t.mday #=> 19 # ``` def day: () -> Integer # Returns `true` if *time* occurs during Daylight Saving # [Time](Time.downloaded.ruby_doc) in its time zone. # # ```ruby # # 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 # ``` def dst?: () -> bool def eql?: (untyped arg0) -> bool # Returns `true` if *time* represents Friday. # # ```ruby # t = Time.local(1987, 12, 18) #=> 1987-12-18 00:00:00 -0600 # t.friday? #=> true # ``` def friday?: () -> bool # Returns a new [Time](Time.downloaded.ruby_doc) object representing # *time* in UTC. # # ```ruby # 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 # ``` def getgm: () -> Time def getlocal: (?Integer utc_offset) -> Time # Returns a new [Time](Time.downloaded.ruby_doc) object representing # *time* in UTC. # # ```ruby # 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 # ``` def getutc: () -> Time # Returns `true` if *time* represents a time in UTC (GMT). # # ```ruby # 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 # # 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 # ``` def gmt?: () -> bool # Returns the offset in seconds between the timezone of *time* and UTC. # # ```ruby # 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 # ``` def gmt_offset: () -> Integer # Converts *time* to UTC (GMT), modifying the receiver. # # ```ruby # 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.now #=> 2007-11-19 08:18:51 -0600 # t.utc? #=> false # t.utc #=> 2007-11-19 14:18:51 UTC # t.utc? #=> true # ``` def gmtime: () -> Time # Returns a hash code for this [Time](Time.downloaded.ruby_doc) object. # # See also Object\#hash. def hash: () -> Integer # Returns the hour of the day (0..23) for *time* . # # ```ruby # t = Time.now #=> 2007-11-19 08:26:20 -0600 # t.hour #=> 8 # ``` def hour: () -> Integer def initialize: (?Integer | String year, ?Integer | String month, ?Integer | String day, ?Integer | String hour, ?Integer | String min, ?Numeric | String sec, ?Numeric | String usec_with_frac) -> void # Returns a string representing *time* . Equivalent to calling # [strftime](Time.downloaded.ruby_doc#method-i-strftime) with the # appropriate format string. # # ```ruby # 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.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" # ``` def inspect: () -> String # Returns `true` if *time* occurs during Daylight Saving # [Time](Time.downloaded.ruby_doc) in its time zone. # # ```ruby # # 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 # ``` def isdst: () -> bool def localtime: (?String utc_offset) -> Time # Returns the day of the month (1..n) for *time* . # # ```ruby # t = Time.now #=> 2007-11-19 08:27:03 -0600 # t.day #=> 19 # t.mday #=> 19 # ``` def mday: () -> Integer # Returns the minute of the hour (0..59) for *time* . # # ```ruby # t = Time.now #=> 2007-11-19 08:25:51 -0600 # t.min #=> 25 # ``` def min: () -> Integer # Returns the month of the year (1..12) for *time* . # # ```ruby # t = Time.now #=> 2007-11-19 08:27:30 -0600 # t.mon #=> 11 # t.month #=> 11 # ``` def mon: () -> Integer # Returns `true` if *time* represents Monday. # # ```ruby # t = Time.local(2003, 8, 4) #=> 2003-08-04 00:00:00 -0500 # t.monday? #=> true # ``` def monday?: () -> bool # Returns the number of nanoseconds for *time* . # # ```ruby # t = Time.now #=> 2007-11-17 15:18:03 +0900 # "%10.9f" % t.to_f #=> "1195280283.536151409" # t.nsec #=> 536151406 # ``` # # The lowest digits of [to\_f](Time.downloaded.ruby_doc#method-i-to_f) and # [nsec](Time.downloaded.ruby_doc#method-i-nsec) are different because # IEEE 754 double is not accurate enough to represent the exact number of # nanoseconds since the Epoch. # # The more accurate value is returned by # [nsec](Time.downloaded.ruby_doc#method-i-nsec). def nsec: () -> Integer def round: (Integer arg0) -> Time # Returns `true` if *time* represents Saturday. # # ```ruby # t = Time.local(2006, 6, 10) #=> 2006-06-10 00:00:00 -0500 # t.saturday? #=> true # ``` def saturday?: () -> bool # Returns the second of the minute (0..60) for *time* . # # **Note:** Seconds range from zero to 60 to allow the system to inject # leap seconds. See # [en.wikipedia.org/wiki/Leap\_second](http://en.wikipedia.org/wiki/Leap_second) # for further details. # # ```ruby # t = Time.now #=> 2007-11-19 08:25:02 -0600 # t.sec #=> 2 # ``` def sec: () -> Integer def strftime: (String arg0) -> String # Returns the fraction for *time* . # # The return value can be a rational number. # # ```ruby # t = Time.now #=> 2009-03-26 22:33:12 +0900 # "%10.9f" % t.to_f #=> "1238074392.940563917" # t.subsec #=> (94056401/100000000) # ``` # # The lowest digits of [to\_f](Time.downloaded.ruby_doc#method-i-to_f) and # [subsec](Time.downloaded.ruby_doc#method-i-subsec) are different because # IEEE 754 double is not accurate enough to represent the rational number. # # The more accurate value is returned by # [subsec](Time.downloaded.ruby_doc#method-i-subsec). def subsec: () -> Numeric # Returns a new [Time](Time.downloaded.ruby_doc) object, one second later # than *time* . [\#succ](Time.downloaded.ruby_doc#method-i-succ) is # obsolete since 1.9.2 for time is not a discrete value. # # ```ruby # t = Time.now #=> 2007-11-19 08:23:57 -0600 # t.succ #=> 2007-11-19 08:23:58 -0600 # ``` # # Use instead `time + 1` # # ```ruby # t + 1 #=> 2007-11-19 08:23:58 -0600 # ``` def succ: () -> Time # Returns `true` if *time* represents Sunday. # # ```ruby # t = Time.local(1990, 4, 1) #=> 1990-04-01 00:00:00 -0600 # t.sunday? #=> true # ``` def sunday?: () -> bool # Returns `true` if *time* represents Thursday. # # ```ruby # t = Time.local(1995, 12, 21) #=> 1995-12-21 00:00:00 -0600 # t.thursday? #=> true # ``` def thursday?: () -> bool # Returns a ten-element *array* of values for *time* : # # ```ruby # [sec, min, hour, day, month, year, wday, yday, isdst, zone] # ``` # # See the individual methods for an explanation of the valid ranges of # each value. The ten elements can be passed directly to # [::utc](Time.downloaded.ruby_doc#method-c-utc) or # [::local](Time.downloaded.ruby_doc#method-c-local) to create a new # [Time](Time.downloaded.ruby_doc) object. # # ```ruby # 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 ] # Returns the value of *time* as a floating point number of seconds since # the Epoch. # # ```ruby # t = Time.now # "%10.5f" % t.to_f #=> "1270968744.77658" # t.to_i #=> 1270968744 # ``` # # Note that IEEE 754 double is not accurate enough to represent the exact # number of nanoseconds since the Epoch. def to_f: () -> Float # Returns the value of *time* as an integer number of seconds since the # Epoch. # # ```ruby # t = Time.now # "%10.5f" % t.to_f #=> "1270968656.89607" # t.to_i #=> 1270968656 # ``` def to_i: () -> Integer # Returns the value of *time* as a rational number of seconds since the # Epoch. # # ```ruby # t = Time.now # t.to_r #=> (1270968792716287611/1000000000) # ``` # # This methods is intended to be used to get an accurate value # representing the nanoseconds since the Epoch. You can use this method to # convert *time* to another Epoch. def to_r: () -> Rational # Returns a string representing *time* . Equivalent to calling # [strftime](Time.downloaded.ruby_doc#method-i-strftime) with the # appropriate format string. # # ```ruby # 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.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" # ``` def to_s: () -> String # Returns `true` if *time* represents Tuesday. # # ```ruby # t = Time.local(1991, 2, 19) #=> 1991-02-19 00:00:00 -0600 # t.tuesday? #=> true # ``` def tuesday?: () -> bool # Returns the number of nanoseconds for *time* . # # ```ruby # t = Time.now #=> 2007-11-17 15:18:03 +0900 # "%10.9f" % t.to_f #=> "1195280283.536151409" # t.nsec #=> 536151406 # ``` # # The lowest digits of [to\_f](Time.downloaded.ruby_doc#method-i-to_f) and # [nsec](Time.downloaded.ruby_doc#method-i-nsec) are different because # IEEE 754 double is not accurate enough to represent the exact number of # nanoseconds since the Epoch. # # The more accurate value is returned by # [nsec](Time.downloaded.ruby_doc#method-i-nsec). def tv_nsec: () -> Numeric # Returns the value of *time* as an integer number of seconds since the # Epoch. # # ```ruby # t = Time.now # "%10.5f" % t.to_f #=> "1270968656.89607" # t.to_i #=> 1270968656 # ``` def tv_sec: () -> Numeric # Returns the number of microseconds for *time* . # # ```ruby # t = Time.now #=> 2007-11-19 08:03:26 -0600 # "%10.6f" % t.to_f #=> "1195481006.775195" # t.usec #=> 775195 # ``` def tv_usec: () -> Numeric # Returns the number of microseconds for *time* . # # ```ruby # t = Time.now #=> 2007-11-19 08:03:26 -0600 # "%10.6f" % t.to_f #=> "1195481006.775195" # t.usec #=> 775195 # ``` def usec: () -> Numeric # Converts *time* to UTC (GMT), modifying the receiver. # # ```ruby # 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.now #=> 2007-11-19 08:18:51 -0600 # t.utc? #=> false # t.utc #=> 2007-11-19 14:18:51 UTC # t.utc? #=> true # ``` def utc: () -> Time # Returns `true` if *time* represents a time in UTC (GMT). # # ```ruby # 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 # # 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 # ``` def utc?: () -> bool # Returns the offset in seconds between the timezone of *time* and UTC. # # ```ruby # 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 # ``` def utc_offset: () -> Integer # Returns an integer representing the day of the week, 0..6, with Sunday # == 0. # # ```ruby # 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 # ``` def wday: () -> Integer # Returns `true` if *time* represents Wednesday. # # ```ruby # t = Time.local(1993, 2, 24) #=> 1993-02-24 00:00:00 -0600 # t.wednesday? #=> true # ``` def wednesday?: () -> bool # Returns an integer representing the day of the year, 1..366. # # ```ruby # t = Time.now #=> 2007-11-19 08:32:31 -0600 # t.yday #=> 323 # ``` def yday: () -> Integer # Returns the year for *time* (including the century). # # ```ruby # t = Time.now #=> 2007-11-19 08:27:51 -0600 # t.year #=> 2007 # ``` def year: () -> Integer # Returns the name of the time zone used for *time* . As of Ruby 1.8, # returns “UTC” rather than “GMT” for UTC times. # # ```ruby # t = Time.gm(2000, "jan", 1, 20, 15, 1) # t.zone #=> "UTC" # t = Time.local(2000, "jan", 1, 20, 15, 1) # t.zone #=> "CST" # ``` def zone: () -> String def self.mktime: (Integer year, ?Integer | String month, ?Integer day, ?Integer hour, ?Integer min, ?Numeric sec, ?Numeric usec_with_frac) -> Time # Returns the offset in seconds between the timezone of *time* and UTC. # # ```ruby # 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 # ``` def gmtoff: () -> Integer # Returns the month of the year (1..12) for *time* . # # ```ruby # t = Time.now #=> 2007-11-19 08:27:30 -0600 # t.mon #=> 11 # t.month #=> 11 # ``` def month: () -> Integer def floor: (?Integer ndigits) -> Time def ceil: (?Integer ndigits) -> Time end Time::RFC2822_DAY_NAME: Array[String] Time::RFC2822_MONTH_NAME: Array[String]