From c9fc4d2ca38ae917658d3abf0c9858d6ebc4d366 Mon Sep 17 00:00:00 2001 From: Jeremy Kemper Date: Wed, 9 Jan 2008 08:46:08 +0000 Subject: [PATCH] Document date and time to_formatted_s. Closes #10747 [leethal] git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@8606 5ecf4fe2-1ee6-0310-87b1-e25e094e27de --- .../core_ext/date/conversions.rb | 22 +++++++++++++++- .../core_ext/date_time/conversions.rb | 25 +++++++++++++++++-- .../core_ext/time/conversions.rb | 24 ++++++++++++++++-- 3 files changed, 66 insertions(+), 5 deletions(-) diff --git a/activesupport/lib/active_support/core_ext/date/conversions.rb b/activesupport/lib/active_support/core_ext/date/conversions.rb index 684775c5e3..e06ca3ada5 100644 --- a/activesupport/lib/active_support/core_ext/date/conversions.rb +++ b/activesupport/lib/active_support/core_ext/date/conversions.rb @@ -1,7 +1,27 @@ module ActiveSupport #:nodoc: module CoreExtensions #:nodoc: module Date #:nodoc: - # Getting dates in different convenient string representations and other objects + # Getting datetimes in different convenient string representations and other objects. + # + # == Adding your own time formats in to_formatted_s + # You can add your own time formats by merging them into the DATE_FORMATS constant. Use a string with + # Ruby's strftime formatting (http://ruby-doc.org/core/classes/Time.html#M000297), or + # pass a lambda. The lambda yields the instance to_formatted_s is called on, so that calculations + # can be performed on that instance. This is handy when Ruby's strftime formatting is insufficient. See + # the +short_ordinal+ example below. + # + # See DATE_FORMATS for the list of built-in formats, and to_formatted_s for implementation details. + # + # === Examples: + # # config/initializers/time_formats.rb + # ActiveSupport::CoreExtensions::Date::Conversions::DATE_FORMATS.merge!( + # :month_and_year => "%B %Y", + # :short_ordinal => lambda { |time| time.strftime("%B #{time.day.ordinalize}") } + # ) + # + # Calling it on a Time instance: + # + # Time.now.to_s(:short_ordinal) module Conversions DATE_FORMATS = { :short => "%e %b", diff --git a/activesupport/lib/active_support/core_ext/date_time/conversions.rb b/activesupport/lib/active_support/core_ext/date_time/conversions.rb index 8ea8679b42..2ee663ac93 100644 --- a/activesupport/lib/active_support/core_ext/date_time/conversions.rb +++ b/activesupport/lib/active_support/core_ext/date_time/conversions.rb @@ -1,9 +1,30 @@ module ActiveSupport #:nodoc: module CoreExtensions #:nodoc: module DateTime #:nodoc: - # Getting datetimes in different convenient string representations and other objects + # Getting datetimes in different convenient string representations and other objects. + # + # == Adding your own time formats in to_formatted_s + # You can add your own time formats by merging them into the ::Time::Conversions::DATE_FORMATS constant. Use a string with + # Ruby's strftime formatting (http://ruby-doc.org/core/classes/Time.html#M000297), or + # pass a lambda. The lambda yields the instance to_formatted_s is called on, so that calculations + # can be performed on that instance. This is handy when Ruby's strftime formatting is insufficient. See + # the +short_ordinal+ example below. + # + # See ActiveSupport::CoreExtensions::Time::Conversions::DATE_FORMATS for the list of built-in formats, and + # to_formatted_s for implementation details. + # + # === Examples: + # # config/initializers/time_formats.rb + # ActiveSupport::CoreExtensions::Time::Conversions::DATE_FORMATS.merge!( + # :month_and_year => "%B %Y", + # :short_ordinal => lambda { |time| time.strftime("%B #{time.day.ordinalize}") } + # ) + # + # Calling it on a Time instance: + # + # Time.now.to_s(:short_ordinal) module Conversions - def self.included(base) + def self.included(base) #:nodoc: base.class_eval do alias_method :to_datetime_default_s, :to_s alias_method :to_s, :to_formatted_s diff --git a/activesupport/lib/active_support/core_ext/time/conversions.rb b/activesupport/lib/active_support/core_ext/time/conversions.rb index ab076a5930..13f41fffbd 100644 --- a/activesupport/lib/active_support/core_ext/time/conversions.rb +++ b/activesupport/lib/active_support/core_ext/time/conversions.rb @@ -1,7 +1,27 @@ module ActiveSupport #:nodoc: module CoreExtensions #:nodoc: module Time #:nodoc: - # Getting times in different convenient string representations and other objects + # Getting times in different convenient string representations and other objects. + # + # == Adding your own time formats in to_formatted_s + # You can add your own time formats by merging them into the DATE_FORMATS constant. Use a string with + # Ruby's strftime formatting (http://ruby-doc.org/core/classes/Time.html#M000297), or + # pass a lambda. The lambda yields the instance to_formatted_s is called on, so that calculations + # can be performed on that instance. This is handy when Ruby's strftime formatting is insufficient. See + # the +short_ordinal+ example below. + # + # See ::Time::DATE_FORMATS for the list of built-in formats, and to_formatted_s for implementation details. + # + # === Examples: + # # config/initializers/time_formats.rb + # ActiveSupport::CoreExtensions::Time::Conversions::DATE_FORMATS.merge!( + # :month_and_year => "%B %Y", + # :short_ordinal => lambda { |time| time.strftime("%B #{time.day.ordinalize}") } + # ) + # + # Calling it on a Time instance: + # + # Time.now.to_s(:short_ordinal) module Conversions DATE_FORMATS = { :db => "%Y-%m-%d %H:%M:%S", @@ -13,7 +33,7 @@ module ActiveSupport #:nodoc: :rfc822 => "%a, %d %b %Y %H:%M:%S %z" } - def self.included(base) + def self.included(base) #:nodoc: base.class_eval do alias_method :to_default_s, :to_s alias_method :to_s, :to_formatted_s