Permalink
Browse files

Merge [8606] to stable: document date and time to_formatted_s. Refere…

…nces #10747.

git-svn-id: http://svn-commit.rubyonrails.org/rails/branches/2-0-stable@8607 5ecf4fe2-1ee6-0310-87b1-e25e094e27de
  • Loading branch information...
1 parent 09b1021 commit 3328171a40e8dd08feabde43eba58672a310cedd @jeremy jeremy committed Jan 9, 2008
@@ -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",
@@ -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
@@ -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",
@@ -12,7 +32,7 @@ module Conversions
: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

0 comments on commit 3328171

Please sign in to comment.