activesupport 4.2.11.3 → 5.0.7.2

data/lib/active_support/core_ext/range/conversions.rb

@@ -1,19 +1,31 @@
-class Range
+module ActiveSupport::RangeWithFormat
   RANGE_FORMATS = {
     :db => Proc.new { |start, stop| "BETWEEN '#{start.to_s(:db)}' AND '#{stop.to_s(:db)}'" }
   }
 
-  # Gives a human readable format of the range.
+  # Convert range to a formatted string. See RANGE_FORMATS for predefined formats.
   #
-  #   (1..100).to_formatted_s # => "1..100"
-  def to_formatted_s(format = :default)
+  #   range = (1..100)           # => 1..100
+  #
+  #   range.to_s                 # => "1..100"
+  #   range.to_s(:db)            # => "BETWEEN '1' AND '100'"
+  #
+  # == Adding your own range formats to to_s
+  # You can add your own formats to the Range::RANGE_FORMATS hash.
+  # Use the format name as the hash key and a Proc instance.
+  #
+  #   # config/initializers/range_formats.rb
+  #   Range::RANGE_FORMATS[:short] = ->(start, stop) { "Between #{start.to_s(:db)} and #{stop.to_s(:db)}" }
+  def to_s(format = :default)
     if formatter = RANGE_FORMATS[format]
       formatter.call(first, last)
     else
-      to_default_s
+      super()
     end
   end
 
   alias_method :to_default_s, :to_s
-  alias_method :to_s, :to_formatted_s
+  alias_method :to_formatted_s, :to_s
 end
+
+Range.prepend(ActiveSupport::RangeWithFormat)

data/lib/active_support/core_ext/range/each.rb

@@ -1,23 +1,21 @@
-require 'active_support/core_ext/module/aliasing'
+module ActiveSupport
+  module EachTimeWithZone #:nodoc:
+    def each(&block)
+      ensure_iteration_allowed
+      super
+    end
 
-class Range #:nodoc:
+    def step(n = 1, &block)
+      ensure_iteration_allowed
+      super
+    end
 
-  def each_with_time_with_zone(&block)
-    ensure_iteration_allowed
-    each_without_time_with_zone(&block)
-  end
-  alias_method_chain :each, :time_with_zone
+    private
 
-  def step_with_time_with_zone(n = 1, &block)
-    ensure_iteration_allowed
-    step_without_time_with_zone(n, &block)
-  end
-  alias_method_chain :step, :time_with_zone
-
-  private
-  def ensure_iteration_allowed
-    if first.is_a?(Time)
-      raise TypeError, "can't iterate from #{first.class}"
-    end
+      def ensure_iteration_allowed
+        raise TypeError, "can't iterate from #{first.class}" if first.is_a?(Time)
+      end
   end
 end
+
+Range.prepend(ActiveSupport::EachTimeWithZone)

data/lib/active_support/core_ext/range/include_range.rb

@@ -1,23 +1,23 @@
-require 'active_support/core_ext/module/aliasing'
-
-class Range
-  # Extends the default Range#include? to support range comparisons.
-  #  (1..5).include?(1..5) # => true
-  #  (1..5).include?(2..3) # => true
-  #  (1..5).include?(2..6) # => false
-  #
-  # The native Range#include? behavior is untouched.
-  #  ('a'..'f').include?('c') # => true
-  #  (5..9).include?(11) # => false
-  def include_with_range?(value)
-    if value.is_a?(::Range)
-      # 1...10 includes 1..9 but it does not include 1..10.
-      operator = exclude_end? && !value.exclude_end? ? :< : :<=
-      include_without_range?(value.first) && value.last.send(operator, last)
-    else
-      include_without_range?(value)
+module ActiveSupport
+  module IncludeWithRange #:nodoc:
+    # Extends the default Range#include? to support range comparisons.
+    #  (1..5).include?(1..5) # => true
+    #  (1..5).include?(2..3) # => true
+    #  (1..5).include?(2..6) # => false
+    #
+    # The native Range#include? behavior is untouched.
+    #  ('a'..'f').include?('c') # => true
+    #  (5..9).include?(11) # => false
+    def include?(value)
+      if value.is_a?(::Range)
+        # 1...10 includes 1..9 but it does not include 1..10.
+        operator = exclude_end? && !value.exclude_end? ? :< : :<=
+        super(value.first) && value.last.send(operator, last)
+      else
+        super
+      end
     end
   end
-
-  alias_method_chain :include?, :range
 end
+
+Range.prepend(ActiveSupport::IncludeWithRange)

data/lib/active_support/core_ext/securerandom.rb

@@ -0,0 +1,23 @@
+require 'securerandom'
+
+module SecureRandom
+  BASE58_ALPHABET = ('0'..'9').to_a  + ('A'..'Z').to_a + ('a'..'z').to_a - ['0', 'O', 'I', 'l']
+  # SecureRandom.base58 generates a random base58 string.
+  #
+  # The argument _n_ specifies the length, of the random string to be generated.
+  #
+  # If _n_ is not specified or is nil, 16 is assumed. It may be larger in the future.
+  #
+  # The result may contain alphanumeric characters except 0, O, I and l
+  #
+  #   p SecureRandom.base58 # => "4kUgL2pdQMSCQtjE"
+  #   p SecureRandom.base58(24) # => "77TMHrHJFvFDwodq8w7Ev2m7"
+  #
+  def self.base58(n = 16)
+    SecureRandom.random_bytes(n).unpack("C*").map do |byte|
+      idx = byte % 64
+      idx = SecureRandom.random_number(58) if idx >= 58
+      BASE58_ALPHABET[idx]
+    end.join
+  end
+end

data/lib/active_support/core_ext/string/behavior.rb

@@ -1,5 +1,5 @@
 class String
-  # Enable more predictable duck-typing on String-like classes. See <tt>Object#acts_like?</tt>.
+  # Enables more predictable duck-typing on String-like classes. See <tt>Object#acts_like?</tt>.
   def acts_like_string?
     true
   end

data/lib/active_support/core_ext/string/conversions.rb

@@ -14,11 +14,12 @@ class String
   #   "06:12".to_time                    # => 2012-12-13 06:12:00 +0100
   #   "2012-12-13 06:12".to_time         # => 2012-12-13 06:12:00 +0100
   #   "2012-12-13T06:12".to_time         # => 2012-12-13 06:12:00 +0100
-  #   "2012-12-13T06:12".to_time(:utc)   # => 2012-12-13 05:12:00 UTC
+  #   "2012-12-13T06:12".to_time(:utc)   # => 2012-12-13 06:12:00 UTC
   #   "12/13/2012".to_time               # => ArgumentError: argument out of range
   def to_time(form = :local)
     parts = Date._parse(self, false)
-    return if parts.empty?
+    used_keys = %i(year mon mday hour min sec sec_fraction offset)
+    return if (parts.keys & used_keys).empty?
 
     now = Time.now
     time = Time.new(

data/lib/active_support/core_ext/string/filters.rb

@@ -17,9 +17,8 @@ class String
   #   str.squish!                         # => "foo bar boo"
   #   str                                 # => "foo bar boo"
   def squish!
-    gsub!(/\A[[:space:]]+/, '')
-    gsub!(/[[:space:]]+\z/, '')
     gsub!(/[[:space:]]+/, ' ')
+    strip!
     self
   end
 

data/lib/active_support/core_ext/string/inflections.rb

@@ -164,25 +164,43 @@ class String
   #
   #   <%= link_to(@person.name, person_path) %>
   #   # => <a href="/person/1-donald-e-knuth">Donald E. Knuth</a>
-  def parameterize(sep = '-')
-    ActiveSupport::Inflector.parameterize(self, sep)
+  #   
+  # To preserve the case of the characters in a string, use the `preserve_case` argument.
+  #
+  #   class Person
+  #     def to_param
+  #       "#{id}-#{name.parameterize(preserve_case: true)}"
+  #     end
+  #   end
+  #
+  #   @person = Person.find(1)
+  #   # => #<Person id: 1, name: "Donald E. Knuth">
+  #
+  #   <%= link_to(@person.name, person_path) %>
+  #   # => <a href="/person/1-Donald-E-Knuth">Donald E. Knuth</a>
+  def parameterize(sep = :unused, separator: '-', preserve_case: false)
+    unless sep == :unused
+      ActiveSupport::Deprecation.warn("Passing the separator argument as a positional parameter is deprecated and will soon be removed. Use `separator: '#{sep}'` instead.")
+      separator = sep
+    end
+    ActiveSupport::Inflector.parameterize(self, separator: separator, preserve_case: preserve_case)
   end
 
   # Creates the name of a table like Rails does for models to table names. This method
   # uses the +pluralize+ method on the last word in the string.
   #
   #   'RawScaledScorer'.tableize # => "raw_scaled_scorers"
-  #   'egg_and_ham'.tableize     # => "egg_and_hams"
+  #   'ham_and_egg'.tableize     # => "ham_and_eggs"
   #   'fancyCategory'.tableize   # => "fancy_categories"
   def tableize
     ActiveSupport::Inflector.tableize(self)
   end
 
-  # Create a class name from a plural table name like Rails does for table names to models.
+  # Creates a class name from a plural table name like Rails does for table names to models.
   # Note that this returns a string and not a class. (To convert to an actual class
   # follow +classify+ with +constantize+.)
   #
-  #   'egg_and_hams'.classify # => "EggAndHam"
+  #   'ham_and_eggs'.classify # => "HamAndEgg"
   #   'posts'.classify        # => "Post"
   def classify
     ActiveSupport::Inflector.classify(self)
@@ -204,6 +222,15 @@ class String
     ActiveSupport::Inflector.humanize(self, options)
   end
 
+  # Converts just the first character to uppercase.
+  #
+  #   'what a Lovely Day'.upcase_first # => "What a Lovely Day"
+  #   'w'.upcase_first                 # => "W"
+  #   ''.upcase_first                  # => ""
+  def upcase_first
+    ActiveSupport::Inflector.upcase_first(self)
+  end
+
   # Creates a foreign key name from a class name.
   # +separate_class_name_and_id_with_underscore+ sets whether
   # the method should put '_' between the name and 'id'.

data/lib/active_support/core_ext/string/multibyte.rb

@@ -1,4 +1,3 @@
-# encoding: utf-8
 require 'active_support/multibyte'
 
 class String
@@ -10,12 +9,10 @@ class String
   # encapsulates the original string. A Unicode safe version of all the String methods are defined on this proxy
   # class. If the proxy class doesn't respond to a certain method, it's forwarded to the encapsulated string.
   #
-  #   name = 'Claus Müller'
-  #   name.reverse # => "rell??M sualC"
-  #   name.length  # => 13
-  #
-  #   name.mb_chars.reverse.to_s # => "rellüM sualC"
-  #   name.mb_chars.length       # => 12
+  #   >> "lj".upcase
+  #   => "lj"
+  #   >> "lj".mb_chars.upcase.to_s
+  #   => "LJ"
   #
   # == Method chaining
   #
@@ -36,6 +33,13 @@ class String
     ActiveSupport::Multibyte.proxy_class.new(self)
   end
 
+  # Returns +true+ if string has utf_8 encoding.
+  #
+  #   utf_8_str = "some string".encode "UTF-8"
+  #   iso_str = "some string".encode "ISO-8859-1"
+  #
+  #   utf_8_str.is_utf8? # => true
+  #   iso_str.is_utf8?   # => false
   def is_utf8?
     case encoding
     when Encoding::UTF_8

data/lib/active_support/core_ext/string/output_safety.rb

@@ -1,12 +1,10 @@
 require 'erb'
 require 'active_support/core_ext/kernel/singleton_class'
-require 'active_support/deprecation'
 
 class ERB
   module Util
     HTML_ESCAPE = { '&' => '&amp;',  '>' => '&gt;',   '<' => '&lt;', '"' => '&quot;', "'" => '&#39;' }
     JSON_ESCAPE = { '&' => '\u0026', '>' => '\u003e', '<' => '\u003c', "\u2028" => '\u2028', "\u2029" => '\u2029' }
-    HTML_ESCAPE_REGEXP = /[&"'><]/
     HTML_ESCAPE_ONCE_REGEXP = /["><']|&(?!([a-zA-Z]+|(#\d+)|(#[xX][\dA-Fa-f]+));)/
     JSON_ESCAPE_REGEXP = /[\u2028\u2029&><]/u
 
@@ -14,7 +12,7 @@ class ERB
     # This method is also aliased as <tt>h</tt>.
     #
     # In your ERB templates, use this method to escape any unsafe content. For example:
-    #   <%=h @person.name %>
+    #   <%= h @person.name %>
     #
     #   puts html_escape('is a > 0 & a < 10?')
     #   # => is a &gt; 0 &amp; a &lt; 10?
@@ -38,7 +36,7 @@ class ERB
       if s.html_safe?
         s
       else
-        s.gsub(HTML_ESCAPE_REGEXP, HTML_ESCAPE)
+        CGI.escapeHTML(ActiveSupport::Multibyte::Unicode.tidy_bytes(s))
       end
     end
     module_function :unwrapped_html_escape
@@ -51,7 +49,7 @@ class ERB
     #   html_escape_once('&lt;&lt; Accept & Checkout')
     #   # => "&lt;&lt; Accept &amp; Checkout"
     def html_escape_once(s)
-      result = s.to_s.gsub(HTML_ESCAPE_ONCE_REGEXP, HTML_ESCAPE)
+      result = ActiveSupport::Multibyte::Unicode.tidy_bytes(s.to_s).gsub(HTML_ESCAPE_ONCE_REGEXP, HTML_ESCAPE)
       s.html_safe? ? result.html_safe : result
     end
 
@@ -86,6 +84,11 @@ class ERB
     # automatically flag the result as HTML safe, since the raw value is unsafe to
     # use inside HTML attributes.
     #
+    # If your JSON is being used downstream for insertion into the DOM, be aware of
+    # whether or not it is being inserted via +html()+. Most jQuery plugins do this.
+    # If that is the case, be sure to +html_escape+ or +sanitize+ any user-generated
+    # content returned by your JSON.
+    #
     # If you need to output JSON elsewhere in your HTML, you can just do something
     # like this, as any unsafe characters (including quotation marks) will be
     # automatically escaped for you:
@@ -138,6 +141,7 @@ module ActiveSupport #:nodoc:
     alias_method :original_concat, :concat
     private :original_concat
 
+    # Raised when <tt>ActiveSupport::SafeBuffer#safe_concat</tt> is called on unsafe buffers.
     class SafeConcatError < StandardError
       def initialize
         super 'Could not concatenate to the buffer because it is not html safe.'
@@ -167,7 +171,7 @@ module ActiveSupport #:nodoc:
       original_concat(value)
     end
 
-    def initialize(*)
+    def initialize(str = '')
       @html_safe = true
       super
     end
@@ -190,11 +194,6 @@ module ActiveSupport #:nodoc:
       super(html_escape_interpolated_argument(value))
     end
 
-    def prepend!(value)
-      ActiveSupport::Deprecation.deprecation_warning "ActiveSupport::SafeBuffer#prepend!", :prepend
-      prepend value
-    end
-
     def +(other)
       dup.concat(other)
     end
@@ -244,15 +243,14 @@ module ActiveSupport #:nodoc:
     private
 
     def html_escape_interpolated_argument(arg)
-      (!html_safe? || arg.html_safe?) ? arg :
-        arg.to_s.gsub(ERB::Util::HTML_ESCAPE_REGEXP, ERB::Util::HTML_ESCAPE)
+      (!html_safe? || arg.html_safe?) ? arg : CGI.escapeHTML(arg.to_s)
     end
   end
 end
 
 class String
   # Marks a string as trusted safe. It will be inserted into HTML with no
-  # additional escaping performed. It is your responsibilty to ensure that the
+  # additional escaping performed. It is your responsibility to ensure that the
   # string contains no malicious content. This method is equivalent to the
   # `raw` helper in views. It is recommended that you use `sanitize` instead of
   # this method. It should never be called on user input.

data/lib/active_support/core_ext/string/strip.rb

@@ -1,5 +1,3 @@
-require 'active_support/core_ext/object/try'
-
 class String
   # Strips indentation in heredocs.
   #
@@ -17,10 +15,9 @@ class String
   #
   # the user would see the usage message aligned against the left margin.
   #
-  # Technically, it looks for the least indented line in the whole string, and removes
-  # that amount of leading whitespace.
+  # Technically, it looks for the least indented non-empty line
+  # in the whole string, and removes that amount of leading whitespace.
   def strip_heredoc
-    indent = scan(/^[ \t]*(?=\S)/).min.try(:size) || 0
-    gsub(/^[ \t]{#{indent}}/, '')
+    gsub(/^#{scan(/^[ \t]*(?=\S)/).min}/, ''.freeze)
   end
 end

data/lib/active_support/core_ext/struct.rb

@@ -1,6 +1,3 @@
-#  Backport of Struct#to_h from Ruby 2.0
-class Struct # :nodoc:
-  def to_h
-    Hash[members.zip(values)]
-  end
-end unless Struct.instance_methods.include?(:to_h)
+require 'active_support/deprecation'
+
+ActiveSupport::Deprecation.warn("This file is deprecated and will be removed in Rails 5.1 with no replacement.")

data/lib/active_support/core_ext/time/calculations.rb

@@ -16,9 +16,9 @@ class Time
       super || (self == Time && other.is_a?(ActiveSupport::TimeWithZone))
     end
 
-    # Return the number of days in the given month.
+    # Returns the number of days in the given month.
     # If no year is specified, it will use the current year.
-    def days_in_month(month, year = now.year)
+    def days_in_month(month, year = current.year)
       if month == 2 && ::Date.gregorian_leap?(year)
         29
       else
@@ -26,6 +26,12 @@ class Time
       end
     end
 
+    # Returns the number of days in the given year.
+    # If no year is specified, it will use the current year.
+    def days_in_year(year = current.year)
+      days_in_month(2, year) + 337
+    end
+
     # Returns <tt>Time.zone.now</tt> when <tt>Time.zone</tt> or <tt>config.time_zone</tt> are set, otherwise just returns <tt>Time.now</tt>.
     def current
       ::Time.zone ? ::Time.zone.now : ::Time.now
@@ -49,7 +55,11 @@ class Time
     alias_method :at, :at_with_coercion
   end
 
-  # Seconds since midnight: Time.now.seconds_since_midnight
+  # Returns the number of seconds since 00:00:00.
+  #
+  #   Time.new(2012, 8, 29,  0,  0,  0).seconds_since_midnight # => 0.0
+  #   Time.new(2012, 8, 29, 12, 34, 56).seconds_since_midnight # => 45296.0
+  #   Time.new(2012, 8, 29, 23, 59, 59).seconds_since_midnight # => 86399.0
   def seconds_since_midnight
     to_i - change(:hour => 0).to_i + (usec / 1.0e+6)
   end
@@ -77,7 +87,7 @@ class Time
   # and minute is passed, then sec, usec and nsec is set to 0. The +options+
   # parameter takes a hash with any of these keys: <tt>:year</tt>, <tt>:month</tt>,
   # <tt>:day</tt>, <tt>:hour</tt>, <tt>:min</tt>, <tt>:sec</tt>, <tt>:usec</tt>
-  # <tt>:nsec</tt>. Path either <tt>:usec</tt> or <tt>:nsec</tt>, not both.
+  # <tt>:nsec</tt>. Pass either <tt>:usec</tt> or <tt>:nsec</tt>, not both.
   #
   #   Time.new(2012, 8, 29, 22, 35, 0).change(day: 1)              # => Time.new(2012, 8, 1, 22, 35, 0)
   #   Time.new(2012, 8, 29, 22, 35, 0).change(year: 1981, day: 1)  # => Time.new(1981, 8, 1, 22, 35, 0)
@@ -159,7 +169,6 @@ class Time
 
   # Returns a new Time representing the start of the day (0:00)
   def beginning_of_day
-    #(self - seconds_since_midnight).change(usec: 0)
     change(:hour => 0)
   end
   alias :midnight :beginning_of_day
@@ -176,7 +185,7 @@ class Time
   alias :at_noon :middle_of_day
   alias :at_middle_of_day :middle_of_day
 
-  # Returns a new Time representing the end of the day, 23:59:59.999999 (.999999999 in ruby1.9)
+  # Returns a new Time representing the end of the day, 23:59:59.999999
   def end_of_day
     change(
       :hour => 23,
@@ -193,7 +202,7 @@ class Time
   end
   alias :at_beginning_of_hour :beginning_of_hour
 
-  # Returns a new Time representing the end of the hour, x:59:59.999999 (.999999999 in ruby1.9)
+  # Returns a new Time representing the end of the hour, x:59:59.999999
   def end_of_hour
     change(
       :min => 59,
@@ -209,7 +218,7 @@ class Time
   end
   alias :at_beginning_of_minute :beginning_of_minute
 
-  # Returns a new Time representing the end of the minute, x:xx:59.999999 (.999999999 in ruby1.9)
+  # Returns a new Time representing the end of the minute, x:xx:59.999999
   def end_of_minute
     change(
       :sec => 59,
@@ -256,7 +265,7 @@ class Time
   # Layers additional behavior on Time#<=> so that DateTime and ActiveSupport::TimeWithZone instances
   # can be chronologically compared with a Time
   def compare_with_coercion(other)
-    # we're avoiding Time#to_datetime cause it's expensive
+    # we're avoiding Time#to_datetime and Time#to_time because they're expensive
     if other.class == Time
       compare_without_coercion(other)
     elsif other.is_a?(Time)

data/lib/active_support/core_ext/time/conversions.rb

@@ -6,6 +6,7 @@ class Time
     :db           => '%Y-%m-%d %H:%M:%S',
     :number       => '%Y%m%d%H%M%S',
     :nsec         => '%Y%m%d%H%M%S%9N',
+    :usec         => '%Y%m%d%H%M%S%6N',
     :time         => '%H:%M',
     :short        => '%d %b %H:%M',
     :long         => '%B %d, %Y %H:%M',
@@ -24,7 +25,7 @@ class Time
   #
   # This method is aliased to <tt>to_s</tt>.
   #
-  #   time = Time.now                    # => Thu Jan 18 06:10:17 CST 2007
+  #   time = Time.now                    # => 2007-01-18 06:10:17 -06:00
   #
   #   time.to_formatted_s(:time)         # => "06:10"
   #   time.to_s(:time)                   # => "06:10"
@@ -55,7 +56,8 @@ class Time
   alias_method :to_default_s, :to_s
   alias_method :to_s, :to_formatted_s
 
-  # Returns the UTC offset as an +HH:MM formatted string.
+  # Returns a formatted string of the offset from UTC, or an alternative
+  # string if the time zone is already UTC.
   #
   #   Time.local(2000).formatted_offset        # => "-06:00"
   #   Time.local(2000).formatted_offset(false) # => "-0600"

data/lib/active_support/core_ext/time/marshal.rb

@@ -1,30 +1,3 @@
-# Ruby 1.9.2 adds utc_offset and zone to Time, but marshaling only
-# preserves utc_offset. Preserve zone also, even though it may not
-# work in some edge cases.
-if Time.local(2010).zone != Marshal.load(Marshal.dump(Time.local(2010))).zone
-  class Time
-    class << self
-      alias_method :_load_without_zone, :_load
-      def _load(marshaled_time)
-        time = _load_without_zone(marshaled_time)
-        time.instance_eval do
-          if zone = defined?(@_zone) && remove_instance_variable('@_zone')
-            ary = to_a
-            ary[0] += subsec if ary[0] == sec
-            ary[-1] = zone
-            utc? ? Time.utc(*ary) : Time.local(*ary)
-          else
-            self
-          end
-        end
-      end
-    end
+require 'active_support/deprecation'
 
-    alias_method :_dump_without_zone, :_dump
-    def _dump(*args)
-      obj = dup
-      obj.instance_variable_set('@_zone', zone)
-      obj.send :_dump_without_zone, *args
-    end
-  end
-end
+ActiveSupport::Deprecation.warn("This is deprecated and will be removed in Rails 5.1 with no replacement.")

data/lib/active_support/core_ext/time/zones.rb

@@ -26,7 +26,7 @@ class Time
     # <tt>current_user.time_zone</tt> just needs to return a string identifying the user's preferred time zone:
     #
     #   class ApplicationController < ActionController::Base
-    #     around_filter :set_time_zone
+    #     around_action :set_time_zone
     #
     #     def set_time_zone
     #       if logged_in?
@@ -40,7 +40,23 @@ class Time
       Thread.current[:time_zone] = find_zone!(time_zone)
     end
 
-    # Allows override of <tt>Time.zone</tt> locally inside supplied block; resets <tt>Time.zone</tt> to existing value when done.
+    # Allows override of <tt>Time.zone</tt> locally inside supplied block;
+    # resets <tt>Time.zone</tt> to existing value when done.
+    #
+    #   class ApplicationController < ActionController::Base
+    #     around_action :set_time_zone
+    #
+    #     private
+    #
+    #     def set_time_zone
+    #       Time.use_zone(current_user.timezone) { yield }
+    #     end
+    #   end
+    #
+    #  NOTE: This won't affect any <tt>ActiveSupport::TimeWithZone</tt>
+    #  objects that have already been created, e.g. any model timestamp
+    #  attributes that have been read before the block will remain in
+    #  the application's default timezone.
     def use_zone(time_zone)
       new_zone = find_zone!(time_zone)
       begin
@@ -51,12 +67,22 @@ class Time
       end
     end
 
-    # Returns a TimeZone instance or nil, or raises an ArgumentError for invalid timezones.
+    # Returns a TimeZone instance matching the time zone provided.
+    # Accepts the time zone in any format supported by <tt>Time.zone=</tt>.
+    # Raises an +ArgumentError+ for invalid time zones.
+    #
+    #   Time.find_zone! "America/New_York" # => #<ActiveSupport::TimeZone @name="America/New_York" ...>
+    #   Time.find_zone! "EST"              # => #<ActiveSupport::TimeZone @name="EST" ...>
+    #   Time.find_zone! -5.hours           # => #<ActiveSupport::TimeZone @name="Bogota" ...>
+    #   Time.find_zone! nil                # => nil
+    #   Time.find_zone! false              # => false
+    #   Time.find_zone! "NOT-A-TIMEZONE"   # => ArgumentError: Invalid Timezone: NOT-A-TIMEZONE
     def find_zone!(time_zone)
       if !time_zone || time_zone.is_a?(ActiveSupport::TimeZone)
         time_zone
       else
-        # lookup timezone based on identifier (unless we've been passed a TZInfo::Timezone)
+        # Look up the timezone based on the identifier (unless we've been
+        # passed a TZInfo::Timezone)
         unless time_zone.respond_to?(:period_for_local)
           time_zone = ActiveSupport::TimeZone[time_zone] || TZInfo::Timezone.get(time_zone)
         end
@@ -72,6 +98,12 @@ class Time
       raise ArgumentError, "Invalid Timezone: #{time_zone}"
     end
 
+    # Returns a TimeZone instance matching the time zone provided.
+    # Accepts the time zone in any format supported by <tt>Time.zone=</tt>.
+    # Returns +nil+ for invalid time zones.
+    #
+    #   Time.find_zone "America/New_York" # => #<ActiveSupport::TimeZone @name="America/New_York" ...>
+    #   Time.find_zone "NOT-A-TIMEZONE"   # => nil
     def find_zone(time_zone)
       find_zone!(time_zone) rescue nil
     end

data/lib/active_support/core_ext/time.rb

@@ -2,5 +2,4 @@ require 'active_support/core_ext/time/acts_like'
 require 'active_support/core_ext/time/calculations'
 require 'active_support/core_ext/time/compatibility'
 require 'active_support/core_ext/time/conversions'
-require 'active_support/core_ext/time/marshal'
 require 'active_support/core_ext/time/zones'

data/lib/active_support/core_ext/uri.rb

@@ -1,5 +1,3 @@
-# encoding: utf-8
-
 require 'uri'
 str = "\xE6\x97\xA5\xE6\x9C\xAC\xE8\xAA\x9E" # Ni-ho-nn-go in UTF-8, means Japanese.
 parser = URI::Parser.new
@@ -12,7 +10,7 @@ unless str == parser.unescape(parser.escape(str))
       # YK: My initial experiments say yes, but let's be sure please
       enc = str.encoding
       enc = Encoding::UTF_8 if enc == Encoding::US_ASCII
-      str.gsub(escaped) { [$&[1, 2].hex].pack('C') }.force_encoding(enc)
+      str.gsub(escaped) { |match| [match[1, 2].hex].pack('C') }.force_encoding(enc)
     end
   end
 end