From ab12c14494146dcda336f2d56fd2e529389eb793 Mon Sep 17 00:00:00 2001 From: Michael Koziarski Date: Wed, 5 Dec 2007 05:58:20 +0000 Subject: Enhance documentation for Active Support's Time Conversion functions. [rsanheim, jeremymcanally, chuyeow] Closes #7164 git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@8278 5ecf4fe2-1ee6-0310-87b1-e25e094e27de --- .../active_support/core_ext/time/conversions.rb | 49 ++++++++++++++++++++-- 1 file changed, 46 insertions(+), 3 deletions(-) (limited to 'activesupport/lib/active_support/core_ext') diff --git a/activesupport/lib/active_support/core_ext/time/conversions.rb b/activesupport/lib/active_support/core_ext/time/conversions.rb index 4b6ad1eef3..0ce90669d2 100644 --- a/activesupport/lib/active_support/core_ext/time/conversions.rb +++ b/activesupport/lib/active_support/core_ext/time/conversions.rb @@ -19,6 +19,22 @@ module ActiveSupport #:nodoc: end end + # Convert to a formatted string - see DATE_FORMATS for predefined formats. + # You can also add your own formats to the DATE_FORMATS constant and use them with this method. + # + # This method is also aliased as to_s. + # + # ==== Examples: + # time = Time.now # => Thu Jan 18 06:10:17 CST 2007 + # + # time.to_formatted_s(:time) # => "06:10:17" + # time.to_s(:time) # => "06:10:17" + # + # time.to_formatted_s(:db) # => "2007-01-18 06:10:17" + # time.to_formatted_s(:short) # => "18 Jan 06:10" + # time.to_formatted_s(:long) # => "January 18, 2007 06:10" + # time.to_formatted_s(:long_ordinal) # => "January 18th, 2007 06:10" + # time.to_formatted_s(:rfc822) # => "Thu, 18 Jan 2007 06:10:17 -0600" def to_formatted_s(format = :default) if formatter = DATE_FORMATS[format] if formatter.respond_to?(:call) @@ -31,17 +47,44 @@ module ActiveSupport #:nodoc: end end - # Converts self to a Ruby Date object; time portion is discarded + # Convert a Time object to a Date, dropping hour, minute, and second precision. + # + # ==== Examples + # my_time = Time.now + # # => Mon Nov 12 22:59:51 -0500 2007 + # + # my_time.to_date + # #=> Mon, 12 Nov 2007 + # + # your_time = Time.parse("1/13/2009 1:13:03 P.M.") + # # => Tue Jan 13 13:13:03 -0500 2009 + # + # your_time.to_date + # # => Tue, 13 Jan 2009 def to_date ::Date.new(year, month, day) end - # To be able to keep Times, Dates and DateTimes interchangeable on conversions + # A method to keep Time, Date and DateTime instances interchangeable on conversions. + # In this case, it simply returns +self+. def to_time self end - # converts to a Ruby DateTime instance; preserves utc offset + # Converts a Time instance to a Ruby DateTime instance, preserving UTC offset. + # + # ==== Examples + # my_time = Time.now + # # => Mon Nov 12 23:04:21 -0500 2007 + # + # my_time.to_datetime + # # => Mon, 12 Nov 2007 23:04:21 -0500 + # + # your_time = Time.parse("1/13/2009 1:13:03 P.M.") + # # => Tue Jan 13 13:13:03 -0500 2009 + # + # your_time.to_datetime + # # => Tue, 13 Jan 2009 13:13:03 -0500 def to_datetime ::DateTime.civil(year, month, day, hour, min, sec, Rational(utc_offset, 86400)) end -- cgit v1.2.3