# Time is an abstraction of dates and times. 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 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. # # 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 implementation uses a signed 63 bit integer, Bignum or # Rational. The integer is a number of nanoseconds since the *Epoch* which can # represent 1823-11-12 to 2116-02-20. When Bignum or Rational is used (before # 1823, after 2116, under nanosecond), Time works slower as when integer is # used. # # # Examples # # All of these examples were done using the EST timezone which is GMT-5. # # ## 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 nothing else time will default to January 1 of that year at 00:00:00 with # the current system timezone. Here are some examples: # # 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: # # Time.new(2002, 10, 31, 2, 2, 2, "+02:00") #=> 2002-10-31 02:02:02 +0200 # # Or a timezone object: # # 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 Time::gm, Time::local and Time::utc to infer GMT, local and # UTC timezones instead of using the current system setting. # # You can also create a new time using Time::at which takes the number of # seconds (or fraction of seconds) since the [Unix # Epoch](http://en.wikipedia.org/wiki/Unix_time). # # Time.at(628232400) #=> 1989-11-28 00:00:00 -0500 # # ## 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: # # t = Time.new(1993, 02, 24, 12, 0, 0, "+09:00") # # Was that a monday? # # t.monday? #=> false # # What year was that again? # # t.year #=> 1993 # # Was it daylight savings at the time? # # t.dst? #=> false # # What's the day a year later? # # t + (60*60*24*365) #=> 1994-02-24 12:00:00 +0900 # # How many seconds was that since the Unix Epoch? # # t.to_i #=> 730522800 # # You can also do standard functions like compare two times. # # 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 # # ## Timezone argument # # A timezone argument must have `local_to_utc` and `utc_to_local` methods, and # may have `name`, `abbr`, and `dst?` 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 # 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 sub-second; it has attribute readers for the parts, # e.g. #year, #month, and so on, and epoch time readers, #to_i. The sub-second # 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. # # 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. # # The `dst?` method is called with a `Time` value and should return whether the # `Time` value is in daylight savings time in the zone. # # ### Auto conversion to Timezone # # At loading marshaled data, a timezone name will be converted to a timezone # object by `find_timezone` class method, if the method is defined. # # Similarly, that class method will be called when a timezone argument does not # have the necessary methods mentioned above. # class Time < Object include Comparable # Creates a new Time object with the value given by `time`, the given number of # `seconds_with_frac`, or `seconds` and `microseconds_with_frac` since the # Epoch. `seconds_with_frac` and `microseconds_with_frac` can be an Integer, # Float, Rational, or other Numeric. non-portable feature allows the offset to # be negative on some systems. # # If `in` argument is given, the result is in that timezone or UTC offset, or if # a numeric argument is given, the result is in local time. # # Time.at(0) #=> 1969-12-31 18:00:00 -0600 # Time.at(Time.at(0)) #=> 1969-12-31 18:00:00 -0600 # Time.at(946702800) #=> 1999-12-31 23:00:00 -0600 # Time.at(-284061600) #=> 1960-12-31 00:00:00 -0600 # Time.at(946684800.2).usec #=> 200000 # Time.at(946684800, 123456.789).nsec #=> 123456789 # Time.at(946684800, 123456789, :nsec).nsec #=> 123456789 # def self.at: (Time | Numeric seconds) -> Time | (Numeric seconds, ?Numeric microseconds_with_frac) -> Time # 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. # # `sec_with_frac` and `usec_with_frac` can have a fractional part. # # 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 # def self.gm: (Integer year, ?Integer | String month, ?Integer day, ?Integer hour, ?Integer min, ?Numeric sec, ?Numeric usec_with_frac) -> Time # Same as Time::gm, but interprets the values in the local time zone. # # Time.local(2000,"jan",1,20,15,1) #=> 2000-01-01 20:15:01 -0600 # 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 object for the current time. This is same as Time.new # without arguments. # # Time.now #=> 2009-06-24 12:39:54 +0900 # def self.now: () -> Time # 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. # # `sec_with_frac` and `usec_with_frac` can have a fractional part. # # 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 # def self.utc: (Integer year, ?Integer | String month, ?Integer day, ?Integer hour, ?Integer min, ?Numeric sec, ?Numeric usec_with_frac) -> Time # Addition --- Adds some number of seconds (possibly fractional) to *time* and # returns that value as a new Time object. # # t = Time.now #=> 2007-11-19 08:22:21 -0600 # t + (60 * 60 * 24) #=> 2007-11-20 08:22:21 -0600 # def +: (Numeric arg0) -> Time # Difference --- Returns a difference in seconds as a Float between *time* and # `other_time`, or subtracts the given number of seconds in `numeric` from # *time*. # # t = Time.now #=> 2007-11-19 08:23:10 -0600 # t2 = t + 2592000 #=> 2007-12-19 08:23:10 -0600 # t2 - t #=> 2592000.0 # t2 - 2592000 #=> 2007-11-19 08:23:10 -0600 # def -: (Time arg0) -> Float | (Numeric arg0) -> Time def <: (Time arg0) -> bool def <=: (Time arg0) -> bool # Comparison---Compares `time` with `other_time`. # # -1, 0, +1 or nil depending on whether `time` is less than, equal to, or # greater than `other_time`. # # `nil` is returned if the two values are incomparable. # # 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 # def <=>: (Time other) -> Integer | (untyped other) -> Integer? def >: (Time arg0) -> bool def >=: (Time arg0) -> bool # Returns a canonical string representation of *time*. # # 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*. # # 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*. # # 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 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 # def dst?: () -> bool # Returns `true` if *time* and `other_time` are both Time objects with the same # seconds and fractional seconds. # def eql?: (untyped arg0) -> bool # Returns `true` if *time* represents Friday. # # t = Time.local(1987, 12, 18) #=> 1987-12-18 00:00:00 -0600 # t.friday? #=> true # def friday?: () -> bool # Returns a new Time object representing *time* in UTC. # # 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 # Returns a new Time object representing *time* in local time (using the local # time zone in effect for this process). # # 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,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 # def getlocal: (?Integer utc_offset) -> Time # Returns a new Time object representing *time* in UTC. # # 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). # # 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. # # 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. # # 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 object. # # See also Object#hash. # def hash: () -> Integer # Returns the hour of the day (0..23) for *time*. # # t = Time.now #=> 2007-11-19 08:26:20 -0600 # t.hour #=> 8 # def hour: () -> Integer # Returns a Time object. # # It is initialized to the current system time if no argument is given. # # **Note:** The new object will use the resolution available on your system # clock, and may include fractional seconds. # # If one or more arguments are specified, the time is initialized to the # specified time. # # `sec` may have fraction if it is a rational. # # `tz` specifies the timezone. It can be an offset from UTC, given either as a # string such as "+09:00" or a single letter "A".."Z" excluding "J" (so-called # military time zone), or as a number of seconds such as 32400. Or it can be a # timezone object, see [Timezone argument](#class-Time-label-Timezone+argument) # for details. # # a = Time.new #=> 2007-11-19 07:50:02 -0600 # b = Time.new #=> 2007-11-19 07:50:02 -0600 # a == b #=> false # "%.6f" % a.to_f #=> "1195480202.282373" # "%.6f" % b.to_f #=> "1195480202.283415" # # Time.new(2008,6,21, 13,30,0, "+09:00") #=> 2008-06-21 13:30:00 +0900 # # # A trip for RubyConf 2007 # t1 = Time.new(2007,11,1,15,25,0, "+09:00") # JST (Narita) # t2 = Time.new(2007,11,1,12, 5,0, "-05:00") # CDT (Minneapolis) # t3 = Time.new(2007,11,1,13,25,0, "-05:00") # CDT (Minneapolis) # t4 = Time.new(2007,11,1,16,53,0, "-04:00") # EDT (Charlotte) # t5 = Time.new(2007,11,5, 9,24,0, "-05:00") # EST (Charlotte) # t6 = Time.new(2007,11,5,11,21,0, "-05:00") # EST (Detroit) # t7 = Time.new(2007,11,5,13,45,0, "-05:00") # EST (Detroit) # t8 = Time.new(2007,11,6,17,10,0, "+09:00") # JST (Narita) # (t2-t1)/3600.0 #=> 10.666666666666666 # (t4-t3)/3600.0 #=> 2.466666666666667 # (t6-t5)/3600.0 #=> 1.95 # (t8-t7)/3600.0 #=> 13.416666666666666 # 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 detailed string representing *time*. Unlike to_s, preserves # nanoseconds in the representation for easier debugging. # # 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.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" # def inspect: () -> String # 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 # def isdst: () -> bool # Converts *time* to local time (using the local time zone in effect at the # creation time of *time*) modifying the receiver. # # If `utc_offset` is given, it is used instead of the local time. # # t = Time.utc(2000, "jan", 1, 20, 15, 1) #=> 2000-01-01 20:15:01 UTC # t.utc? #=> true # # t.localtime #=> 2000-01-01 14:15:01 -0600 # t.utc? #=> false # # t.localtime("+09:00") #=> 2000-01-02 05:15:01 +0900 # t.utc? #=> false # # If `utc_offset` is not given and *time* is local time, just returns the # receiver. # def localtime: (?String utc_offset) -> Time # Returns the day of the month (1..n) for *time*. # # 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*. # # 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*. # # 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. # # 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*. # # 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 and #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. # def nsec: () -> Integer # Rounds sub seconds 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. # # require 'time' # # t = Time.utc(2010,3,30, 5,43,25.123456789r) # t.iso8601(10) #=> "2010-03-30T05:43:25.1234567890Z" # t.round.iso8601(10) #=> "2010-03-30T05:43:25.0000000000Z" # t.round(0).iso8601(10) #=> "2010-03-30T05:43:25.0000000000Z" # t.round(1).iso8601(10) #=> "2010-03-30T05:43:25.1000000000Z" # t.round(2).iso8601(10) #=> "2010-03-30T05:43:25.1200000000Z" # t.round(3).iso8601(10) #=> "2010-03-30T05:43:25.1230000000Z" # t.round(4).iso8601(10) #=> "2010-03-30T05:43:25.1235000000Z" # # t = Time.utc(1999,12,31, 23,59,59) # (t + 0.4).round.iso8601(3) #=> "1999-12-31T23:59:59.000Z" # (t + 0.49).round.iso8601(3) #=> "1999-12-31T23:59:59.000Z" # (t + 0.5).round.iso8601(3) #=> "2000-01-01T00:00:00.000Z" # (t + 1.4).round.iso8601(3) #=> "2000-01-01T00:00:00.000Z" # (t + 1.49).round.iso8601(3) #=> "2000-01-01T00:00:00.000Z" # (t + 1.5).round.iso8601(3) #=> "2000-01-01T00:00:01.000Z" # # t = Time.utc(1999,12,31, 23,59,59) # (t + 0.123456789).round(4).iso8601(6) #=> "1999-12-31T23:59:59.123500Z" # def round: (?Integer arg0) -> Time # Returns `true` if *time* represents Saturday. # # 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 http://en.wikipedia.org/wiki/Leap_second for further details. # # t = Time.now #=> 2007-11-19 08:25:02 -0600 # t.sec #=> 2 # def sec: () -> Integer # 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: # - 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) # def strftime: (String arg0) -> String # Returns the fraction for *time*. # # The return value can be a rational number. # # 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 and #subsec are different because IEEE 754 double # is not accurate enough to represent the rational number. # # The more accurate value is returned by #subsec. # def subsec: () -> Numeric # Returns `true` if *time* represents Sunday. # # 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. # # 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*: # # [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 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 ] # Returns the value of *time* as a floating point number of seconds since the # Epoch. # # 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. # # 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. # # 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 with the # appropriate format string. # # 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. # # 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*. # # 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 and #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. # def tv_nsec: () -> Numeric # Returns the value of *time* as an integer number of seconds since the Epoch. # # 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*. # # 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*. # # 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. # # 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). # # 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. # # 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. # # 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. # # 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. # # t = Time.now #=> 2007-11-19 08:32:31 -0600 # t.yday #=> 323 # def yday: () -> Integer # Returns the year for *time* (including the century). # # 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. # # 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 # Same as Time::gm, but interprets the values in the local time zone. # # Time.local(2000,"jan",1,20,15,1) #=> 2000-01-01 20:15:01 -0600 # 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. # # 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*. # # t = Time.now #=> 2007-11-19 08:27:30 -0600 # t.mon #=> 11 # t.month #=> 11 # def month: () -> Integer # Floors sub seconds 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. # # require 'time' # # t = Time.utc(2010,3,30, 5,43,25.123456789r) # t.iso8601(10) #=> "2010-03-30T05:43:25.1234567890Z" # t.floor.iso8601(10) #=> "2010-03-30T05:43:25.0000000000Z" # t.floor(0).iso8601(10) #=> "2010-03-30T05:43:25.0000000000Z" # t.floor(1).iso8601(10) #=> "2010-03-30T05:43:25.1000000000Z" # t.floor(2).iso8601(10) #=> "2010-03-30T05:43:25.1200000000Z" # t.floor(3).iso8601(10) #=> "2010-03-30T05:43:25.1230000000Z" # t.floor(4).iso8601(10) #=> "2010-03-30T05:43:25.1234000000Z" # # t = Time.utc(1999,12,31, 23,59,59) # (t + 0.4).floor.iso8601(3) #=> "1999-12-31T23:59:59.000Z" # (t + 0.9).floor.iso8601(3) #=> "1999-12-31T23:59:59.000Z" # (t + 1.4).floor.iso8601(3) #=> "2000-01-01T00:00:00.000Z" # (t + 1.9).floor.iso8601(3) #=> "2000-01-01T00:00:00.000Z" # # t = Time.utc(1999,12,31, 23,59,59) # (t + 0.123456789).floor(4).iso8601(6) #=> "1999-12-31T23:59:59.123400Z" # def floor: (?Integer ndigits) -> Time # Ceils sub seconds 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. # # require 'time' # # t = Time.utc(2010,3,30, 5,43,25.0123456789r) # t.iso8601(10) #=> "2010-03-30T05:43:25.0123456789Z" # t.ceil.iso8601(10) #=> "2010-03-30T05:43:26.0000000000Z" # t.ceil(0).iso8601(10) #=> "2010-03-30T05:43:26.0000000000Z" # t.ceil(1).iso8601(10) #=> "2010-03-30T05:43:25.1000000000Z" # t.ceil(2).iso8601(10) #=> "2010-03-30T05:43:25.0200000000Z" # t.ceil(3).iso8601(10) #=> "2010-03-30T05:43:25.0130000000Z" # t.ceil(4).iso8601(10) #=> "2010-03-30T05:43:25.0124000000Z" # # t = Time.utc(1999,12,31, 23,59,59) # (t + 0.4).ceil.iso8601(3) #=> "2000-01-01T00:00:00.000Z" # (t + 0.9).ceil.iso8601(3) #=> "2000-01-01T00:00:00.000Z" # (t + 1.4).ceil.iso8601(3) #=> "2000-01-01T00:00:01.000Z" # (t + 1.9).ceil.iso8601(3) #=> "2000-01-01T00:00:01.000Z" # # t = Time.utc(1999,12,31, 23,59,59) # (t + 0.123456789).ceil(4).iso8601(6) #=> "1999-12-31T23:59:59.123500Z" # def ceil: (?Integer ndigits) -> Time end Time::RFC2822_DAY_NAME: Array[String] Time::RFC2822_MONTH_NAME: Array[String]