diff options
Diffstat (limited to 'lib')
| -rw-r--r-- | lib/time.rb | 174 |
1 files changed, 101 insertions, 73 deletions
diff --git a/lib/time.rb b/lib/time.rb index a2ada7728b..49ef68a5e2 100644 --- a/lib/time.rb +++ b/lib/time.rb @@ -2,6 +2,8 @@ require 'date' +# :stopdoc: + # = time.rb # # When 'time' is required, Time is extended with additional methods for parsing @@ -18,73 +20,8 @@ require 'date' # 8601}[http://www.iso.org/iso/date_and_time_format]) # * various formats handled by Date._parse # * custom formats handled by Date._strptime -# -# == Examples -# -# All examples assume you have loaded Time with: -# -# require 'time' -# -# All of these examples were done using the EST timezone which is GMT-5. -# -# === Converting to a String -# -# t = Time.now -# t.iso8601 # => "2011-10-05T22:26:12-04:00" -# t.rfc2822 # => "Wed, 05 Oct 2011 22:26:12 -0400" -# t.httpdate # => "Thu, 06 Oct 2011 02:26:12 GMT" -# -# === Time.parse -# -# #parse takes a string representation of a Time and attempts to parse it -# using a heuristic. -# -# Time.parse("2010-10-31") #=> 2010-10-31 00:00:00 -0500 -# -# Any missing pieces of the date are inferred based on the current date. -# -# # assuming the current date is "2011-10-31" -# Time.parse("12:00") #=> 2011-10-31 12:00:00 -0500 -# -# We can change the date used to infer our missing elements by passing a second -# object that responds to #mon, #day and #year, such as Date, Time or DateTime. -# We can also use our own object. -# -# class MyDate -# attr_reader :mon, :day, :year -# -# def initialize(mon, day, year) -# @mon, @day, @year = mon, day, year -# end -# end -# -# d = Date.parse("2010-10-28") -# t = Time.parse("2010-10-29") -# dt = DateTime.parse("2010-10-30") -# md = MyDate.new(10,31,2010) -# -# Time.parse("12:00", d) #=> 2010-10-28 12:00:00 -0500 -# Time.parse("12:00", t) #=> 2010-10-29 12:00:00 -0500 -# Time.parse("12:00", dt) #=> 2010-10-30 12:00:00 -0500 -# Time.parse("12:00", md) #=> 2010-10-31 12:00:00 -0500 -# -# #parse also accepts an optional block. You can use this block to specify how -# to handle the year component of the date. This is specifically designed for -# handling two digit years. For example, if you wanted to treat all two digit -# years prior to 70 as the year 2000+ you could write this: -# -# Time.parse("01-10-31") {|year| year + (year < 70 ? 2000 : 1900)} -# #=> 2001-10-31 00:00:00 -0500 -# Time.parse("70-10-31") {|year| year + (year < 70 ? 2000 : 1900)} -# #=> 1970-10-31 00:00:00 -0500 -# -# === Time.strptime -# -# #strptime works similar to +parse+ except that instead of using a heuristic -# to detect the format of the input string, you provide a second argument that -# describes the format of the string. For example: -# -# Time.strptime("2000-10-31", "%Y-%m-%d") #=> 2000-10-31 00:00:00 -0500 + +# :startdoc: class Time class << Time @@ -131,6 +68,13 @@ class Time # # If +zone_offset+ is unable to determine the offset, nil will be # returned. + # + # require 'time' + # + # Time.zone_offset("EST") #=> -18000 + # + # You must require 'time' to use this method. + # def zone_offset(zone, year=self.now.year) off = nil zone = zone.upcase @@ -316,17 +260,62 @@ class Time private :make_time # - # Parses +date+ using Date._parse and converts it to a Time object. + # Takes a string representation of a Time and attempts to parse it + # using a heuristic. # - # If a block is given, the year described in +date+ is converted by the - # block. For example: + # require 'time' + # + # Time.parse("2010-10-31") #=> 2010-10-31 00:00:00 -0500 # - # Time.parse(...) {|y| 0 <= y && y < 100 ? (y >= 69 ? y + 1900 : y + 2000) : y} + # Any missing pieces of the date are inferred based on the current date. + # + # require 'time' + # + # # assuming the current date is "2011-10-31" + # Time.parse("12:00") #=> 2011-10-31 12:00:00 -0500 + # + # We can change the date used to infer our missing elements by passing a second + # object that responds to #mon, #day and #year, such as Date, Time or DateTime. + # We can also use our own object. + # + # require 'time' + # + # class MyDate + # attr_reader :mon, :day, :year + # + # def initialize(mon, day, year) + # @mon, @day, @year = mon, day, year + # end + # end + # + # d = Date.parse("2010-10-28") + # t = Time.parse("2010-10-29") + # dt = DateTime.parse("2010-10-30") + # md = MyDate.new(10,31,2010) + # + # Time.parse("12:00", d) #=> 2010-10-28 12:00:00 -0500 + # Time.parse("12:00", t) #=> 2010-10-29 12:00:00 -0500 + # Time.parse("12:00", dt) #=> 2010-10-30 12:00:00 -0500 + # Time.parse("12:00", md) #=> 2010-10-31 12:00:00 -0500 + # + # If a block is given, the year described in +date+ is converted + # by the block. This is specifically designed for handling two + # digit years. For example, if you wanted to treat all two digit + # years prior to 70 as the year 2000+ you could write this: + # + # require 'time' + # + # Time.parse("01-10-31") {|year| year + (year < 70 ? 2000 : 1900)} + # #=> 2001-10-31 00:00:00 -0500 + # Time.parse("70-10-31") {|year| year + (year < 70 ? 2000 : 1900)} + # #=> 1970-10-31 00:00:00 -0500 # # If the upper components of the given time are broken or missing, they are # supplied with those of +now+. For the lower components, the minimum # values (1 or 0) are assumed if broken or missing. For example: # + # require 'time' + # # # Suppose it is "Thu Nov 29 14:33:20 2001" now and # # your time zone is EST which is GMT-5. # now = Time.parse("Thu Nov 29 14:33:20 2001") @@ -378,7 +367,9 @@ class Time end # - # Parses +date+ using Date._strptime and converts it to a Time object. + # Works similar to +parse+ except that instead of using a + # heuristic to detect the format of the input string, you provide + # a second argument that describes the format of the string. # # If a block is given, the year described in +date+ is converted by the # block. For example: @@ -436,7 +427,13 @@ class Time # %Z :: Time zone name # %% :: Literal "%" character # %+ :: date(1) (%a %b %e %H:%M:%S %Z %Y) - + # + # require 'time' + # + # Time.strptime("2000-10-31", "%Y-%m-%d") #=> 2000-10-31 00:00:00 -0500 + # + # You must require 'time' to use this method. + # def strptime(date, format, now=self.now) d = Date._strptime(date, format) raise ArgumentError, "invalid strptime format - `#{format}'" unless d @@ -474,6 +471,11 @@ class Time # # See #rfc2822 for more information on this format. # + # require 'time' + # + # Time.rfc2822("Wed, 05 Oct 2011 22:26:12 -0400") + # #=> 2010-10-05 22:26:12 -0400 + # # You must require 'time' to use this method. # def rfc2822(date) @@ -527,6 +529,11 @@ class Time # # See #httpdate for more information on this format. # + # require 'time' + # + # Time.httpdate("Thu, 06 Oct 2011 02:26:12 GMT") + # #=> 2011-10-06 02:26:12 UTC + # # You must require 'time' to use this method. # def httpdate(date) @@ -576,6 +583,12 @@ class Time # # See #xmlschema for more information on this format. # + # require 'time' + # + # t = Time.now + # Time.xmlschema("2011-10-05T22:26:12-04:00") + # #=> 2011-10-05 22:26:12-04:00 + # # You must require 'time' to use this method. # def xmlschema(date) @@ -623,6 +636,11 @@ class Time # # If +self+ is a UTC time, -0000 is used as zone. # + # require 'time' + # + # t = Time.now + # t.rfc2822 # => "Wed, 05 Oct 2011 22:26:12 -0400" + # # You must require 'time' to use this method. # def rfc2822 @@ -658,6 +676,11 @@ class Time # # Note that the result is always UTC (GMT). # + # require 'time' + # + # t = Time.now + # t.httpdate # => "Thu, 06 Oct 2011 02:26:12 GMT" + # # You must require 'time' to use this method. # def httpdate @@ -682,6 +705,11 @@ class Time # +fractional_digits+ specifies a number of digits to use for fractional # seconds. Its default value is 0. # + # require 'time' + # + # t = Time.now + # t.iso8601 # => "2011-10-05T22:26:12-04:00" + # # You must require 'time' to use this method. # def xmlschema(fraction_digits=0) |