diff options
Diffstat (limited to 'activesupport/lib')
| -rw-r--r-- | activesupport/lib/active_support/core_ext/time/zones.rb | 27 | ||||
| -rw-r--r-- | activesupport/lib/active_support/time_with_zone.rb | 29 | ||||
| -rw-r--r-- | activesupport/lib/active_support/values/time_zone.rb | 21 |
3 files changed, 68 insertions, 9 deletions
diff --git a/activesupport/lib/active_support/core_ext/time/zones.rb b/activesupport/lib/active_support/core_ext/time/zones.rb index 3ffc71407c..cf28d0fa95 100644 --- a/activesupport/lib/active_support/core_ext/time/zones.rb +++ b/activesupport/lib/active_support/core_ext/time/zones.rb @@ -1,9 +1,7 @@ module ActiveSupport #:nodoc: module CoreExtensions #:nodoc: module Time #:nodoc: - # Methods for creating TimeWithZone objects from Time instances module Zones - def self.included(base) #:nodoc: base.extend(ClassMethods) if base == ::Time # i.e., don't include class methods in DateTime end @@ -11,18 +9,31 @@ module ActiveSupport #:nodoc: module ClassMethods attr_accessor :zone_default + # Returns the TimeZone for the current request, if this has been set (via Time.zone=). + # If Time.zone has not been set for the current request, returns the TimeZone specified in config.time_zone def zone Thread.current[:time_zone] || zone_default end - # Sets a global default time zone, separate from the system time zone in ENV['TZ']. - # Accepts either a Rails TimeZone object, a string that identifies a - # Rails TimeZone object (e.g., "Central Time (US & Canada)"), or a TZInfo::Timezone object. + # Sets Time.zone to a TimeZone object for the current request/thread. + # + # This method accepts any of the following: + # + # * a Rails TimeZone object + # * an identifier for a Rails TimeZone object (e.g., "Eastern Time (US & Canada)", -5.hours) + # * a TZInfo::Timezone object + # * an identifier for a TZInfo::Timezone object (e.g., "America/New_York") + # + # Here's an example of how you might set Time.zone on a per request basis -- current_user.time_zone + # just needs to return a string identifying the user's preferred TimeZone: # - # Any Time or DateTime object can use this default time zone, via <tt>in_time_zone</tt>. + # class ApplicationController < ActionController::Base + # before_filter :set_time_zone # - # Time.zone = 'Hawaii' # => 'Hawaii' - # Time.utc(2000).in_time_zone # => Fri, 31 Dec 1999 14:00:00 HST -10:00 + # def set_time_zone + # Time.zone = current_user.time_zone + # end + # end def zone=(time_zone) Thread.current[:time_zone] = get_zone(time_zone) end diff --git a/activesupport/lib/active_support/time_with_zone.rb b/activesupport/lib/active_support/time_with_zone.rb index 15145a2575..64c935717d 100644 --- a/activesupport/lib/active_support/time_with_zone.rb +++ b/activesupport/lib/active_support/time_with_zone.rb @@ -1,7 +1,34 @@ require 'tzinfo' module ActiveSupport # A Time-like class that can represent a time in any time zone. Necessary because standard Ruby Time instances are - # limited to UTC and the system's ENV['TZ'] zone + # limited to UTC and the system's ENV['TZ'] zone. + # + # You shouldn't ever need to create a TimeWithZone instance directly via .new -- instead, Rails provides the methods + # #local, #parse, #at and #now on TimeZone instances, and #in_time_zone on Time and DateTime instances, for a more + # user-friendly syntax. Examples: + # + # Time.zone = 'Eastern Time (US & Canada)' # => 'Eastern Time (US & Canada)' + # Time.zone.local(2007, 2, 10, 15, 30, 45) # => Sat, 10 Feb 2007 15:30:45 EST -05:00 + # Time.zone.parse('2007-02-01 15:30:45') # => Sat, 10 Feb 2007 15:30:45 EST -05:00 + # Time.zone.at(1170361845) # => Sat, 10 Feb 2007 15:30:45 EST -05:00 + # Time.zone.now # => Sun, 18 May 2008 13:07:55 EDT -04:00 + # Time.utc(2007, 2, 10, 20, 30, 45).in_time_zone # => Sat, 10 Feb 2007 15:30:45 EST -05:00 + # + # See TimeZone and ActiveSupport::CoreExtensions::Time::Zones for further documentation for these methods. + # + # TimeWithZone instances implement the same API as Ruby Time instances, so that Time and TimeWithZone instances are interchangable. Examples: + # + # t = Time.zone.now # => Sun, 18 May 2008 13:27:25 EDT -04:00 + # t.hour # => 13 + # t.dst? # => true + # t.utc_offset # => -14400 + # t.zone # => "EDT" + # t.to_s(:rfc822) # => "Sun, 18 May 2008 13:27:25 -0400" + # t + 1.day # => Mon, 19 May 2008 13:27:25 EDT -04:00 + # t.beginning_of_year # => Tue, 01 Jan 2008 00:00:00 EST -05:00 + # t > Time.utc(1999) # => true + # t.is_a?(Time) # => true + # t.is_a?(ActiveSupport::TimeWithZone) # => true class TimeWithZone include Comparable attr_reader :time_zone diff --git a/activesupport/lib/active_support/values/time_zone.rb b/activesupport/lib/active_support/values/time_zone.rb index f522b64108..5340b5ed28 100644 --- a/activesupport/lib/active_support/values/time_zone.rb +++ b/activesupport/lib/active_support/values/time_zone.rb @@ -1,3 +1,24 @@ +# The TimeZone class serves as a wrapper around TZInfo::Timezone instances. It allows us to do the following: +# +# * limit the set of zones provided by TZInfo to a meaningful subset of 142 zones +# * retrieve and display zones with a friendlier name (e.g., "Eastern Time (US & Canada)" instead of "America/New_York") +# * lazily load TZInfo::Timezone instances only when they're needed +# * create ActiveSupport::TimeWithZone instances via TimeZone #local, #parse, #at and #now methods +# +# If you set config.time_zone in the Rails Initializer, you can access this TimeZone object via Time.zone: +# +# # environment.rb: +# Rails::Initializer.run do |config| +# config.time_zone = "Eastern Time (US & Canada)" +# end +# +# Time.zone # => #<TimeZone:0x514834...> +# Time.zone.name # => "Eastern Time (US & Canada)" +# Time.zone.now # => Sun, 18 May 2008 14:30:44 EDT -04:00 +# +# The version of TZInfo bundled with ActiveSupport only includes the definitions necessary to support the zones +# defined by the TimeZone class. If you need to use zones that aren't defined by TimeZone, you'll need to install the TZInfo gem +# (if a recent version of the gem is installed locally, this will be used instead of the bundled version.) class TimeZone unless const_defined?(:MAPPING) # Keys are Rails TimeZone names, values are TZInfo identifiers |