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

   1 module ActiveSupport #:nodoc:
   2   module CoreExtensions #:nodoc:
   3     module DateTime #:nodoc:
   4       # Converting datetimes to formatted strings, dates, and times.
   5       module Conversions
   6         def self.append_features(base) #:nodoc:
   7           base.class_eval do
   8             alias_method :default_inspect, :inspect
   9             alias_method :to_default_s, :to_s unless (instance_methods(false) & [:to_s, 'to_s']).empty?
  10
  11             # Ruby 1.9 has DateTime#to_time which internally relies on Time. We define our own #to_time which allows
  12             # DateTimes outside the range of what can be created with Time.
  13             remove_method :to_time if instance_methods.include?(:to_time)
  14           end
  15
  16           super
  17
  18           base.class_eval do
  19             alias_method :to_s, :to_formatted_s
  20             alias_method :inspect, :readable_inspect
  21           end
  22         end
  23
  24         # Convert to a formatted string. See Time::DATE_FORMATS for predefined formats.
  25         #
  26         # This method is aliased to <tt>to_s</tt>.
  27         #
  28         # === Examples:
  29         #   datetime = DateTime.civil(2007, 12, 4, 0, 0, 0, 0)   # => Tue, 04 Dec 2007 00:00:00 +0000
  30         #
  31         #   datetime.to_formatted_s(:db)            # => "2007-12-04 00:00:00"
  32         #   datetime.to_s(:db)                      # => "2007-12-04 00:00:00"
  33         #   datetime.to_s(:number)                  # => "20071204000000"
  34         #   datetime.to_formatted_s(:short)         # => "04 Dec 00:00"
  35         #   datetime.to_formatted_s(:long)          # => "December 04, 2007 00:00"
  36         #   datetime.to_formatted_s(:long_ordinal)  # => "December 4th, 2007 00:00"
  37         #   datetime.to_formatted_s(:rfc822)        # => "Tue, 04 Dec 2007 00:00:00 +0000"
  38         #
  39         # == Adding your own datetime formats to to_formatted_s
  40         # DateTime formats are shared with Time. You can add your own to the
  41         # Time::DATE_FORMATS hash. Use the format name as the hash key and
  42         # either a strftime string or Proc instance that takes a time or
  43         # datetime argument as the value.
  44         #
  45         #   # config/initializers/time_formats.rb
  46         #   Time::DATE_FORMATS[:month_and_year] = "%B %Y"
  47         #   Time::DATE_FORMATS[:short_ordinal] = lambda { |time| time.strftime("%B #{time.day.ordinalize}") }
  48         def to_formatted_s(format = :default)
  49           return to_default_s unless formatter = ::Time::DATE_FORMATS[format]
  50           formatter.respond_to?(:call) ? formatter.call(self).to_s : strftime(formatter)
  51         end
  52
  53         # Returns the +utc_offset+ as an +HH:MM formatted string. Examples:
  54         #
  55         #   datetime = DateTime.civil(2000, 1, 1, 0, 0, 0, Rational(-6, 24))
  56         #   datetime.formatted_offset         # => "-06:00"
  57         #   datetime.formatted_offset(false)  # => "-0600"
  58         def formatted_offset(colon = true, alternate_utc_string = nil)
  59           utc? && alternate_utc_string || utc_offset.to_utc_offset_s(colon)
  60         end
  61
  62         # Overrides the default inspect method with a human readable one, e.g., "Mon, 21 Feb 2005 14:30:00 +0000"
  63         def readable_inspect
  64           to_s(:rfc822)
  65         end
  66
  67         # Converts self to a Ruby Date object; time portion is discarded
  68         def to_date
  69           ::Date.new(year, month, day)
  70         end
  71
  72         # Attempts to convert self to a Ruby Time object; returns self if out of range of Ruby Time class
  73         # If self has an offset other than 0, self will just be returned unaltered, since there's no clean way to map it to a Time
  74         def to_time
  75           self.offset == 0 ? ::Time.utc_time(year, month, day, hour, min, sec) : self
  76         end
  77
  78         # To be able to keep Times, Dates and DateTimes interchangeable on conversions
  79         def to_datetime
  80           self
  81         end
  82
  83         # Converts datetime to an appropriate format for use in XML
  84         def xmlschema
  85           strftime("%Y-%m-%dT%H:%M:%S%Z")
  86         end if RUBY_VERSION < '1.9'
  87
  88         # Converts self to a floating-point number of seconds since the Unix epoch
  89         def to_f
  90           days_since_unix_epoch = self - ::DateTime.civil(1970)
  91           (days_since_unix_epoch * 86_400).to_f
  92         end
  93       end
  94     end
  95   end
  96 end