Google

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 443 and 457, respectively. The Time class treats GMT (Greenwich Mean Time) and UTC (Coordinated Universal Time)1 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 -> Wed Feb 07 12:36:51 CST 2001
b = Time.new -> Wed Feb 07 12:36:51 CST 2001
a == b -> false
"%.6f" % a.to_f -> "981571011.541298"
"%.6f" % b.to_f -> "981571011.541821"

now Time.now -> aTime
Synonym for Time::new.
times Time.times -> aStructTms
Returns a Tms structure (see Struct::Tms on page 388) that contains user and system CPU times for this process.

t = Time.times
[ t.utime, t.stime ] -> [0.0, 0.01]

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 -> Wed Feb 07 12:36:51 CST 2001
t + (60 * 60 * 24) -> Thu Feb 08 12:36:51 CST 2001

- 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 -> Wed Feb 07 12:36:51 CST 2001
t2 = t + 2592000 -> Fri Mar 09 12:36:51 CST 2001
t2 - t -> 2592000.0
t2 - 2592000 -> Wed Feb 07 12:36:51 CST 2001

<=> 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 -> Wed Feb 07 12:36:51 CST 2001
t2 = t + 2592000 -> Fri Mar 09 12:36:51 CST 2001
t <=> t2 -> -1
t2 <=> t -> 1
t <=> t -> 0

asctime time.asctime -> aString
Returns a canonical string representation of time.

Time.now.asctime -> "Wed Feb  7 12:36:51 2001"

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 -> Wed Feb 07 12:36:51 CST 2001
t.day -> 7

gmt? time.gmt? -> true or false
Returns true if time represents a time in UTC (GMT).

t = Time.now -> Wed Feb 07 12:36:51 CST 2001
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 -> Wed Feb 07 12:36:51 CST 2001
t.gmt? -> false
t.gmtime -> Wed Feb 07 18:36:51 UTC 2001
t.gmt? -> true

hour time.hour -> aFixnum
Returns the hour of the day (0..23) for time.

t = Time.now -> Wed Feb 07 12:36:51 CST 2001
t.hour -> 12

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 -> Wed Feb 07 12:36:51 CST 2001
t.min -> 36

mon time.mon -> aFixnum
Returns the month of the year (1..12) for time.

t = Time.now -> Wed Feb 07 12:36:51 CST 2001
t.mon -> 2

month time.month -> aFixnum
Synonym for Time#mon.
sec time.sec -> aFixnum
Returns the second of the minute (0..60)2 for time.

t = Time.now -> Wed Feb 07 12:36:52 CST 2001
t.sec -> 52

strftime time.strftime( aString ) -> aString
Formats time according to the directives in the given format string. See Table 22.9 on page 402 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 02/07/2001"
t.strftime("at %I:%M%p") -> "at 12:36PM"

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: {:0909:[ sec, min, hour, day, month, year, wday, yday, isdst, zone ]}:0909:. 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 -> Wed Feb 07 12:36:52 CST 2001
t = now.to_a -> [52, 36, 12, 7, 2, 2001, 3, 38, false, "CST"]

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 -> "981571012.11235"
t.to_i -> 981571012

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 -> "981571012.15911"
t.to_i -> 981571012

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 -> "Wed Feb 07 12:36:52 CST 2001"

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 -> Wed Feb 07 12:36:52 CST 2001
"%10.6f" % t.to_f -> "981571012.213906"
t.usec -> 213906

utc time.utc -> time
Synonym for Time#gmtime.

t = Time.now -> Wed Feb 07 12:36:52 CST 2001
t.utc? -> false
t.utc -> Wed Feb 07 18:36:52 UTC 2001
t.utc? -> true

utc? time.utc? -> true or false
Returns true if time represents a time in UTC (GMT).

t = Time.now -> Wed Feb 07 12:36:52 CST 2001
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 -> Wed Feb 07 12:36:52 CST 2001
t.wday -> 3

yday time.yday -> aFixnum
Returns an integer representing the day of the year, 1..366.

t = Time.now -> Wed Feb 07 12:36:52 CST 2001
t.yday -> 38

year time.year -> aFixnum
Returns the year for time (including the century).

t = Time.now -> Wed Feb 07 12:36:52 CST 2001
t.year -> 2001

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"

Yes, UTC really does stand for Coordinated Universal Time. There was a committee involved. 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.


Extracted from the book "Programming Ruby - The Pragmatic Programmer's Guide"
Copyright © 2000 Addison Wesley Longman, Inc. Released under the terms of the Open Publication License V1.0.
This reference is available for download.