vendor/rails/activesupport/lib/active_support/core_ext/time/conversions.rb

   1 module ActiveSupport #:nodoc:
   2   module CoreExtensions #:nodoc:
   3     module Time #:nodoc:
   4       # Converting times to formatted strings, dates, and datetimes.
   5       module Conversions
   6         DATE_FORMATS = {
   7           :db           => "%Y-%m-%d %H:%M:%S",
   8           :number       => "%Y%m%d%H%M%S",
   9           :time         => "%H:%M",
  10           :short        => "%d %b %H:%M",
  11           :long         => "%B %d, %Y %H:%M",
  12           :long_ordinal => lambda { |time| time.strftime("%B #{time.day.ordinalize}, %Y %H:%M") },
  13           :rfc822       => "%a, %d %b %Y %H:%M:%S %z"
  14         }
  15
  16         def self.included(base) #:nodoc:
  17           base.class_eval do
  18             alias_method :to_default_s, :to_s
  19             alias_method :to_s, :to_formatted_s
  20           end
  21         end
  22
  23         # Converts to a formatted string. See DATE_FORMATS for builtin formats.
  24         #
  25         # This method is aliased to <tt>to_s</tt>.
  26         #
  27         #   time = Time.now                     # => Thu Jan 18 06:10:17 CST 2007
  28         #
  29         #   time.to_formatted_s(:time)          # => "06:10:17"
  30         #   time.to_s(:time)                    # => "06:10:17"
  31         #
  32         #   time.to_formatted_s(:db)            # => "2007-01-18 06:10:17"
  33         #   time.to_formatted_s(:number)        # => "20070118061017"
  34         #   time.to_formatted_s(:short)         # => "18 Jan 06:10"
  35         #   time.to_formatted_s(:long)          # => "January 18, 2007 06:10"
  36         #   time.to_formatted_s(:long_ordinal)  # => "January 18th, 2007 06:10"
  37         #   time.to_formatted_s(:rfc822)        # => "Thu, 18 Jan 2007 06:10:17 -0600"
  38         #
  39         # == Adding your own time formats to +to_formatted_s+
  40         # You can add your own formats to the Time::DATE_FORMATS hash.
  41         # Use the format name as the hash key and either a strftime string
  42         # or Proc instance that takes a time argument as the value.
  43         #
  44         #   # config/initializers/time_formats.rb
  45         #   Time::DATE_FORMATS[:month_and_year] = "%B %Y"
  46         #   Time::DATE_FORMATS[:short_ordinal] = lambda { |time| time.strftime("%B #{time.day.ordinalize}") }
  47         def to_formatted_s(format = :default)
  48           return to_default_s unless formatter = DATE_FORMATS[format]
  49           formatter.respond_to?(:call) ? formatter.call(self).to_s : strftime(formatter)
  50         end
  51
  52         # Returns the UTC offset as an +HH:MM formatted string.
  53         #
  54         #   Time.local(2000).formatted_offset         # => "-06:00"
  55         #   Time.local(2000).formatted_offset(false)  # => "-0600"
  56         def formatted_offset(colon = true, alternate_utc_string = nil)
  57           utc? && alternate_utc_string || utc_offset.to_utc_offset_s(colon)
  58         end
  59
  60         # Converts a Time object to a Date, dropping hour, minute, and second precision.
  61         #
  62         #   my_time = Time.now  # => Mon Nov 12 22:59:51 -0500 2007
  63         #   my_time.to_date     # => Mon, 12 Nov 2007
  64         #
  65         #   your_time = Time.parse("1/13/2009 1:13:03 P.M.")  # => Tue Jan 13 13:13:03 -0500 2009
  66         #   your_time.to_date                                 # => Tue, 13 Jan 2009
  67         def to_date
  68           ::Date.new(year, month, day)
  69         end
  70
  71         # A method to keep Time, Date and DateTime instances interchangeable on conversions.
  72         # In this case, it simply returns +self+.
  73         def to_time
  74           self
  75         end
  76
  77         # Converts a Time instance to a Ruby DateTime instance, preserving UTC offset.
  78         #
  79         #   my_time = Time.now    # => Mon Nov 12 23:04:21 -0500 2007
  80         #   my_time.to_datetime   # => Mon, 12 Nov 2007 23:04:21 -0500
  81         #
  82         #   your_time = Time.parse("1/13/2009 1:13:03 P.M.")  # => Tue Jan 13 13:13:03 -0500 2009
  83         #   your_time.to_datetime                             # => Tue, 13 Jan 2009 13:13:03 -0500
  84         def to_datetime
  85           ::DateTime.civil(year, month, day, hour, min, sec, Rational(utc_offset, 86400))
  86         end
  87       end
  88     end
  89   end
  90 end