# Programming Ruby ### The Pragmatic Programmer's Guide
Previous < | Contents ^ | Next >

class Time |
Parent: | Object
Version: | 1.6

### Index:

at gm local mktime new now times utc + -- <=> asctime ctime day gmt? gmtime hour isdst localtime mday min mon month sec strftime to_a to_f to_i to_s tv_sec tv_usec usec utc utc? wday yday year zone

`Time` is an abstraction of dates and times. Time is stored internally as the number of seconds and microseconds since the epoch, January 1, 1970 00:00 UTC. Also see the library modules `Date` and `ParseDate`, documented beginning on pages 439 and 453, respectively. The `Time` class treats GMT (Greenwich Mean Time) and UTC (Coordinated Universal Time)[Yes, UTC really does stand for Coordinated Universal Time. There was a committee involved.] 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 are stored with some number of microseconds. Be aware of this fact when comparing times with each other---times that are apparently equal when displayed may be different when compared.

mixins
Comparable: | <, <=, ==, >=, >, between?

class methods
at | Time.at( aTime ) -> aTime Time.at( seconds [, microseconds ] ) -> aTime
|  | Creates a new time object with the value given by aTime, or the given number of seconds (and optional microseconds) from epoch.
`Time.at(0)` | » | `Wed Dec 31 18:00:00 CST 1969`
`Time.at(946702800)` | » | `Fri Dec 31 23:00:00 CST 1999`
gm | Time.gm( year [, month, day, hour, min, sec, usec] ) -> aTime Time.gm( sec, min, hour, day, month, year, wday, yday, isdst, tz ) -> aTime
|  | Creates a time 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` .
`Time.gm(2000,"jan",1,20,15,1)` | » | `Sat Jan 01 20:15:01 UTC 2000`
local | Time.local( year [, month, day, hour, min, sec, usec] ) -> aTime Time.local( sec, min, hour, day, month, year, wday, yday, isdst, tz ) -> aTime
|  | Same as `Time.gm` , but interprets the values in the local time zone.
`Time.local(2000,"jan",1,20,15,1)` | » | `Sat Jan 01 20:15:01 CST 2000`
mktime | Time.mktime( year, month, day, hour, min, sec, usec ) -> aTime
|  | Synonym for `Time.local` .
new | Time.new -> aTime
|  | Returns a `Time` object initialized to the current system time. Note: The object created will be created using the resolution available on your system clock, and so may include fractional seconds.
`a = Time.new` | » | `Sun Jun 09 00:19:20 CDT 2002`
`b = Time.new` | » | `Sun Jun 09 00:19:20 CDT 2002`
`a == b` | » | `false`
`"%.6f" % a.to_f` | » | `"1023599960.526217"`
`"%.6f" % b.to_f` | » | `"1023599960.526838"`
now | Time.now -> aTime
|  | Synonym for `Time.new` .
times | Time.times -> aStructTms
|  | Returns a `Tms` structure (see `Struct::Tms` on page 383) that contains user and system CPU times for this process.
`t = Time.times`
`[ t.utime, t.stime ]` | » | `[0.04, 0.0]`
utc | Time.utc( year [, month, day, hour, min, sec, usec] ) -> aTime Time.utc( sec, min, hour, day, month, year, wday, yday, isdst, tz ) -> aTime
|  | Synonym for `Time.gm` .
`Time.utc(2000,"jan",1,20,15,1)` | » | `Sat Jan 01 20:15:01 UTC 2000`

instance methods
+ | time + aNumeric -> aTime
|  | Addition---Adds some number of seconds (possibly fractional) to time and returns that value as a new time.
`t = Time.now` | » | `Sun Jun 09 00:19:20 CDT 2002`
`t + (60 * 60 * 24)` | » | `Mon Jun 10 00:19:20 CDT 2002`
-- | time `-` aTime -> aFloat time `-` aNumeric -> aTime
|  | Difference---Returns a new time that represents the difference between two times, or subtracts the given number of seconds in aNumeric from time.
`t = Time.now` | » | `Sun Jun 09 00:19:20 CDT 2002`
`t2 = t + 2592000` | » | `Tue Jul 09 00:19:20 CDT 2002`
`t2 - t` | » | `2592000.0`
`t2 - 2592000` | » | `Sun Jun 09 00:19:20 CDT 2002`
<=> | time <=> anOtherTime -> -1, 0, +1 time <=> aNumeric -> -1, 0, +1
|  | Comparison---Compares time with anOtherTime or with aNumeric, which is the number of seconds (possibly fractional) since epoch.
`t = Time.now` | » | `Sun Jun 09 00:19:20 CDT 2002`
`t2 = t + 2592000` | » | `Tue Jul 09 00:19:20 CDT 2002`
`t <=> t2` | » | `-1`
`t2 <=> t` | » | `1`
`t <=> t` | » | `0`
asctime | time.asctime -> aString
|  | Returns a canonical string representation of time.
`Time.now.asctime` | » | `"Sun Jun 9 00:19:21 2002"`
ctime | time.ctime -> aString
|  | Synonym for `Time#asctime` .
day | time.day -> aFixnum
|  | Returns the day of the month (1..n) for time.
`t = Time.now` | » | `Sun Jun 09 00:19:21 CDT 2002`
`t.day` | » | `9`
gmt? | time.gmt? -> `true` or `false`
|  | Returns `true` if time represents a time in UTC (GMT).
`t = Time.now` | » | `Sun Jun 09 00:19:21 CDT 2002`
`t.gmt?` | » | `false`
`t = Time.gm(2000,"jan",1,20,15,1)` | » | `Sat Jan 01 20:15:01 UTC 2000`
`t.gmt?` | » | `true`
gmtime | time.gmtime -> time
|  | Converts time to UTC (GMT), modifying the receiver.
`t = Time.now` | » | `Sun Jun 09 00:19:21 CDT 2002`
`t.gmt?` | » | `false`
`t.gmtime` | » | `Sun Jun 09 05:19:21 UTC 2002`
`t.gmt?` | » | `true`
hour | time.hour -> aFixnum
|  | Returns the hour of the day (0..23) for time.
`t = Time.now` | » | `Sun Jun 09 00:19:21 CDT 2002`
`t.hour` | » | `0`
isdst | time.isdst -> `true` or `false`
|  | Returns `true` if time occurs during Daylight Saving Time in its time zone.
`t = Time.local(2000, 7, 1)` | » | `Sat Jul 01 00:00:00 CDT 2000`
`t.isdst` | » | `true`
`t2 = Time.local(2000, 1, 1)` | » | `Sat Jan 01 00:00:00 CST 2000`
`t2.isdst` | » | `false`
localtime | time.localtime -> time
|  | Converts time to local time (using the local time zone in effect for this process) modifying the receiver.
`t = Time.gm(2000, "jan", 1, 20, 15, 1)`
`t.gmt?` | » | `true`
`t.localtime` | » | `Sat Jan 01 14:15:01 CST 2000`
`t.gmt?` | » | `false`
mday | time.mday -> aFixnum
|  | Synonym for `Time#day` .
min | time.min -> aFixnum
|  | Returns the minute of the hour (0..59) for time.
`t = Time.now` | » | `Sun Jun 09 00:19:21 CDT 2002`
`t.min` | » | `19`
mon | time.mon -> aFixnum
|  | Returns the month of the year (1..12) for time.
`t = Time.now` | » | `Sun Jun 09 00:19:21 CDT 2002`
`t.mon` | » | `6`
month | time.month -> aFixnum
|  | Synonym for `Time#mon` .
sec | time.sec -> aFixnum
|  | Returns the second of the minute (0..60)[Yes, seconds really can range from zero to 60. This allows the system to inject leap seconds every now and then to correct for the fact that years are not really a convenient number of hours long.] for time.
`t = Time.now` | » | `Sun Jun 09 00:19:21 CDT 2002`
`t.sec` | » | `21`
strftime | time.strftime( aString ) -> aString
|  | Formats time according to the directives in the given format string. See Table 22.9 on page 397 for the available values. Any text not listed as a directive will be passed through to the output string.
`t = Time.now`
`t.strftime("Printed on %m/%d/%Y")` | » | `"Printed on 06/09/2002"`
`t.strftime("at %I:%M%p")` | » | `"at 12:19AM"`
`Time#strftime` directives
Format | Meaning
%a | The abbreviated weekday name (``Sun'')
%A | The full weekday name (``Sunday'')
%b | The abbreviated month name (``Jan'')
%B | The full month name (``January'')
%c | The preferred local date and time representation
%d | Day of the month (01..31)
%H | Hour of the day, 24-hour clock (00..23)
%I | Hour of the day, 12-hour clock (01..12)
%j | Day of the year (001..366)
%m | Month of the year (01..12)
%M | Minute of the hour (00..59)
%p | Meridian indicator (``AM'' or ``PM'')
%S | Second of the minute (00..60)
%U | Week number of the current year, starting with the first Sunday as the first day of the first week (00..53)
%W | Week number of the current year, starting with the first Monday as the first day of the first week (00..53)
%w | Day of the week (Sunday is 0, 0..6)
%x | Preferred representation for the date alone, no time
%X | Preferred representation for the time alone, no date
%y | Year without a century (00..99)
%Y | Year with century
%Z | Time zone name
%% | Literal ``%'' character
to_a | time.to_a -> anArray
|  | Returns a ten-element anArray 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`.
`now = Time.now` | » | `Sun Jun 09 00:19:21 CDT 2002`
`t = now.to_a` | » | `[21, 19, 0, 9, 6, 2002, 0, 160, true, "CDT"]`
to_f | time.to_f -> aFloat
|  | Returns the value of time as a floating point number of seconds since epoch.
`t = Time.now`
`"%10.5f" % t.to_f` | » | `"1023599961.93824"`
`t.to_i` | » | `1023599961`
to_i | time.to_i -> anInteger
|  | Returns the value of time as an integer number of seconds since epoch.
`t = Time.now`
`"%10.5f" % t.to_f` | » | `"1023599962.01627"`
`t.to_i` | » | `1023599962`
to_s | time.to_s -> aString
|  | Returns a string representing time. Equivalent to calling `Time#strftime` with a format string of ```%a` `%b` `%d` `%H:%M:%S` `%Z` `%Y`''.
`Time.now.to_s` | » | `"Sun Jun 09 00:19:22 CDT 2002"`
tv_sec | time.tv_sec -> anInteger
|  | Synonym for `Time#to_i` .
tv_usec | time.tv_usec -> anInteger
|  | Synonym for `Time#usec` .
usec | time.usec -> anInteger
|  | Returns just the number of microseconds for time.
`t = Time.now` | » | `Sun Jun 09 00:19:22 CDT 2002`
`"%10.6f" % t.to_f` | » | `"1023599962.174522"`
`t.usec` | » | `174522`
utc | time.utc -> time
|  | Synonym for `Time#gmtime` .
`t = Time.now` | » | `Sun Jun 09 00:19:22 CDT 2002`
`t.utc?` | » | `false`
`t.utc` | » | `Sun Jun 09 05:19:22 UTC 2002`
`t.utc?` | » | `true`
utc? | time.utc? -> `true` or `false`
|  | Returns `true` if time represents a time in UTC (GMT).
`t = Time.now` | » | `Sun Jun 09 00:19:22 CDT 2002`
`t.utc?` | » | `false`
`t = Time.gm(2000,"jan",1,20,15,1)` | » | `Sat Jan 01 20:15:01 UTC 2000`
`t.utc?` | » | `true`
wday | time.wday -> aFixnum
|  | Returns an integer representing the day of the week, 0..6, with Sunday == 0.
`t = Time.now` | » | `Sun Jun 09 00:19:22 CDT 2002`
`t.wday` | » | `0`
yday | time.yday -> aFixnum
|  | Returns an integer representing the day of the year, 1..366.
`t = Time.now` | » | `Sun Jun 09 00:19:22 CDT 2002`
`t.yday` | » | `160`
year | time.year -> aFixnum
|  | Returns the year for time (including the century).
`t = Time.now` | » | `Sun Jun 09 00:19:22 CDT 2002`
`t.year` | » | `2002`
zone | time.zone -> aString
|  | Returns the name of the time zone used for time.
`t = Time.gm(2000, "jan", 1, 20, 15, 1)`
`t.zone` | » | `"GMT"`
`t = Time.local(2000, "jan", 1, 20, 15, 1)`
`t.zone` | » | `"CST"`

Previous < | Contents ^ | Next >

Extracted from the book "Programming Ruby - The Pragmatic Programmer's Guide"
Copyright © 2001 by Addison Wesley Longman, Inc. This material may be distributed only subject to the terms and conditions set forth in the Open Publication License, v1.0 or later (the latest version is presently available at http://www.opencontent.org/openpub/)).

Distribution of substantively modified versions of this document is prohibited without the explicit permission of the copyright holder.

Distribution of the work or derivative of the work in any standard (paper) book form is prohibited unless prior permission is obtained from the copyright holder.