activesupport 3.1.0 → 5.0.0

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

@@ -0,0 +1,145 @@
+require 'active_support/core_ext/big_decimal/conversions'
+require 'active_support/number_helper'
+require 'active_support/core_ext/module/deprecation'
+
+module ActiveSupport::NumericWithFormat
+
+  # Provides options for converting numbers into formatted strings.
+  # Options are provided for phone numbers, currency, percentage,
+  # precision, positional notation, file size and pretty printing.
+  #
+  # ==== Options
+  #
+  # For details on which formats use which options, see ActiveSupport::NumberHelper
+  #
+  # ==== Examples
+  #
+  #  Phone Numbers:
+  #  5551234.to_s(:phone)                                     # => "555-1234"
+  #  1235551234.to_s(:phone)                                  # => "123-555-1234"
+  #  1235551234.to_s(:phone, area_code: true)                 # => "(123) 555-1234"
+  #  1235551234.to_s(:phone, delimiter: ' ')                  # => "123 555 1234"
+  #  1235551234.to_s(:phone, area_code: true, extension: 555) # => "(123) 555-1234 x 555"
+  #  1235551234.to_s(:phone, country_code: 1)                 # => "+1-123-555-1234"
+  #  1235551234.to_s(:phone, country_code: 1, extension: 1343, delimiter: '.')
+  #  # => "+1.123.555.1234 x 1343"
+  #
+  #  Currency:
+  #  1234567890.50.to_s(:currency)                 # => "$1,234,567,890.50"
+  #  1234567890.506.to_s(:currency)                # => "$1,234,567,890.51"
+  #  1234567890.506.to_s(:currency, precision: 3)  # => "$1,234,567,890.506"
+  #  1234567890.506.to_s(:currency, locale: :fr)   # => "1 234 567 890,51 €"
+  #  -1234567890.50.to_s(:currency, negative_format: '(%u%n)')
+  #  # => "($1,234,567,890.50)"
+  #  1234567890.50.to_s(:currency, unit: '£', separator: ',', delimiter: '')
+  #  # => "£1234567890,50"
+  #  1234567890.50.to_s(:currency, unit: '£', separator: ',', delimiter: '', format: '%n %u')
+  #  # => "1234567890,50 £"
+  #
+  #  Percentage:
+  #  100.to_s(:percentage)                                  # => "100.000%"
+  #  100.to_s(:percentage, precision: 0)                    # => "100%"
+  #  1000.to_s(:percentage, delimiter: '.', separator: ',') # => "1.000,000%"
+  #  302.24398923423.to_s(:percentage, precision: 5)        # => "302.24399%"
+  #  1000.to_s(:percentage, locale: :fr)                    # => "1 000,000%"
+  #  100.to_s(:percentage, format: '%n  %')                 # => "100.000  %"
+  #
+  #  Delimited:
+  #  12345678.to_s(:delimited)                     # => "12,345,678"
+  #  12345678.05.to_s(:delimited)                  # => "12,345,678.05"
+  #  12345678.to_s(:delimited, delimiter: '.')     # => "12.345.678"
+  #  12345678.to_s(:delimited, delimiter: ',')     # => "12,345,678"
+  #  12345678.05.to_s(:delimited, separator: ' ')  # => "12,345,678 05"
+  #  12345678.05.to_s(:delimited, locale: :fr)     # => "12 345 678,05"
+  #  98765432.98.to_s(:delimited, delimiter: ' ', separator: ',')
+  #  # => "98 765 432,98"
+  #
+  #  Rounded:
+  #  111.2345.to_s(:rounded)                                      # => "111.235"
+  #  111.2345.to_s(:rounded, precision: 2)                        # => "111.23"
+  #  13.to_s(:rounded, precision: 5)                              # => "13.00000"
+  #  389.32314.to_s(:rounded, precision: 0)                       # => "389"
+  #  111.2345.to_s(:rounded, significant: true)                   # => "111"
+  #  111.2345.to_s(:rounded, precision: 1, significant: true)     # => "100"
+  #  13.to_s(:rounded, precision: 5, significant: true)           # => "13.000"
+  #  111.234.to_s(:rounded, locale: :fr)                          # => "111,234"
+  #  13.to_s(:rounded, precision: 5, significant: true, strip_insignificant_zeros: true)
+  #  # => "13"
+  #  389.32314.to_s(:rounded, precision: 4, significant: true)    # => "389.3"
+  #  1111.2345.to_s(:rounded, precision: 2, separator: ',', delimiter: '.')
+  #  # => "1.111,23"
+  #
+  #  Human-friendly size in Bytes:
+  #  123.to_s(:human_size)                                   # => "123 Bytes"
+  #  1234.to_s(:human_size)                                  # => "1.21 KB"
+  #  12345.to_s(:human_size)                                 # => "12.1 KB"
+  #  1234567.to_s(:human_size)                               # => "1.18 MB"
+  #  1234567890.to_s(:human_size)                            # => "1.15 GB"
+  #  1234567890123.to_s(:human_size)                         # => "1.12 TB"
+  #  1234567890123456.to_s(:human_size)                      # => "1.1 PB"
+  #  1234567890123456789.to_s(:human_size)                   # => "1.07 EB"
+  #  1234567.to_s(:human_size, precision: 2)                 # => "1.2 MB"
+  #  483989.to_s(:human_size, precision: 2)                  # => "470 KB"
+  #  1234567.to_s(:human_size, precision: 2, separator: ',') # => "1,2 MB"
+  #  1234567890123.to_s(:human_size, precision: 5)           # => "1.1228 TB"
+  #  524288000.to_s(:human_size, precision: 5)               # => "500 MB"
+  #
+  #  Human-friendly format:
+  #  123.to_s(:human)                                       # => "123"
+  #  1234.to_s(:human)                                      # => "1.23 Thousand"
+  #  12345.to_s(:human)                                     # => "12.3 Thousand"
+  #  1234567.to_s(:human)                                   # => "1.23 Million"
+  #  1234567890.to_s(:human)                                # => "1.23 Billion"
+  #  1234567890123.to_s(:human)                             # => "1.23 Trillion"
+  #  1234567890123456.to_s(:human)                          # => "1.23 Quadrillion"
+  #  1234567890123456789.to_s(:human)                       # => "1230 Quadrillion"
+  #  489939.to_s(:human, precision: 2)                      # => "490 Thousand"
+  #  489939.to_s(:human, precision: 4)                      # => "489.9 Thousand"
+  #  1234567.to_s(:human, precision: 4,
+  #                   significant: false)                   # => "1.2346 Million"
+  #  1234567.to_s(:human, precision: 1,
+  #                   separator: ',',
+  #                   significant: false)                   # => "1,2 Million"
+  def to_s(*args)
+    format, options = args
+    options ||= {}
+
+    case format
+    when :phone
+      return ActiveSupport::NumberHelper.number_to_phone(self, options)
+    when :currency
+      return ActiveSupport::NumberHelper.number_to_currency(self, options)
+    when :percentage
+      return ActiveSupport::NumberHelper.number_to_percentage(self, options)
+    when :delimited
+      return ActiveSupport::NumberHelper.number_to_delimited(self, options)
+    when :rounded
+      return ActiveSupport::NumberHelper.number_to_rounded(self, options)
+    when :human
+      return ActiveSupport::NumberHelper.number_to_human(self, options)
+    when :human_size
+      return ActiveSupport::NumberHelper.number_to_human_size(self, options)
+    else
+      if is_a?(Float) || format.is_a?(Symbol)
+        super()
+      else
+        super
+      end
+    end
+  end
+
+  def to_formatted_s(*args)
+    to_s(*args)
+  end
+  deprecate to_formatted_s: :to_s
+end
+
+# Ruby 2.4+ unifies Fixnum & Bignum into Integer.
+if Integer == Fixnum
+  Integer.prepend ActiveSupport::NumericWithFormat
+else
+  Fixnum.prepend ActiveSupport::NumericWithFormat
+  Bignum.prepend ActiveSupport::NumericWithFormat
+end
+Float.prepend ActiveSupport::NumericWithFormat
+BigDecimal.prepend ActiveSupport::NumericWithFormat

data/lib/active_support/core_ext/numeric/inquiry.rb

@@ -0,0 +1,26 @@
+unless 1.respond_to?(:positive?) # TODO: Remove this file when we drop support to ruby < 2.3
+class Numeric
+  # Returns true if the number is positive.
+  #
+  #   1.positive?  # => true
+  #   0.positive?  # => false
+  #   -1.positive? # => false
+  def positive?
+    self > 0
+  end
+
+  # Returns true if the number is negative.
+  #
+  #   -1.negative? # => true
+  #   0.negative?  # => false
+  #   1.negative?  # => false
+  def negative?
+    self < 0
+  end
+end
+
+class Complex
+  undef :positive?
+  undef :negative?
+end
+end

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

@@ -1,6 +1,8 @@
 require 'active_support/duration'
 require 'active_support/core_ext/time/calculations'
 require 'active_support/core_ext/time/acts_like'
+require 'active_support/core_ext/date/calculations'
+require 'active_support/core_ext/date/acts_like'
 
 class Numeric
   # Enables the use of time calculations and declarations, like 45.minutes + 2.hours + 4.years.
@@ -8,72 +10,65 @@ class Numeric
   # These methods use Time#advance for precise date calculations when using from_now, ago, etc.
   # as well as adding or subtracting their results from a Time object. For example:
   #
-  #   # equivalent to Time.now.advance(:months => 1)
+  #   # equivalent to Time.current.advance(months: 1)
   #   1.month.from_now
   #
-  #   # equivalent to Time.now.advance(:years => 2)
+  #   # equivalent to Time.current.advance(years: 2)
   #   2.years.from_now
   #
-  #   # equivalent to Time.now.advance(:months => 4, :years => 5)
+  #   # equivalent to Time.current.advance(months: 4, years: 5)
   #   (4.months + 5.years).from_now
-  #
-  # While these methods provide precise calculation when used as in the examples above, care
-  # should be taken to note that this is not true if the result of `months', `years', etc is
-  # converted before use:
-  #
-  #   # equivalent to 30.days.to_i.from_now
-  #   1.month.to_i.from_now
-  #
-  #   # equivalent to 365.25.days.to_f.from_now
-  #   1.year.to_f.from_now
-  #
-  # In such cases, Ruby's core
-  # Date[http://stdlib.rubyonrails.org/libdoc/date/rdoc/index.html] and
-  # Time[http://stdlib.rubyonrails.org/libdoc/time/rdoc/index.html] should be used for precision
-  # date and time arithmetic
   def seconds
     ActiveSupport::Duration.new(self, [[:seconds, self]])
   end
   alias :second :seconds
 
+  # Returns a Duration instance matching the number of minutes provided.
+  #
+  #   2.minutes # => 2 minutes
   def minutes
-    ActiveSupport::Duration.new(self * 60, [[:seconds, self * 60]])
+    ActiveSupport::Duration.new(self * 60, [[:minutes, self]])
   end
   alias :minute :minutes
 
+  # Returns a Duration instance matching the number of hours provided.
+  #
+  #   2.hours # => 2 hours
   def hours
-    ActiveSupport::Duration.new(self * 3600, [[:seconds, self * 3600]])
+    ActiveSupport::Duration.new(self * 3600, [[:hours, self]])
   end
   alias :hour :hours
 
+  # Returns a Duration instance matching the number of days provided.
+  #
+  #   2.days # => 2 days
   def days
     ActiveSupport::Duration.new(self * 24.hours, [[:days, self]])
   end
   alias :day :days
 
+  # Returns a Duration instance matching the number of weeks provided.
+  #
+  #   2.weeks # => 2 weeks
   def weeks
-    ActiveSupport::Duration.new(self * 7.days, [[:days, self * 7]])
+    ActiveSupport::Duration.new(self * 7.days, [[:weeks, self]])
   end
   alias :week :weeks
 
+  # Returns a Duration instance matching the number of fortnights provided.
+  #
+  #   2.fortnights # => 4 weeks
   def fortnights
-    ActiveSupport::Duration.new(self * 2.weeks, [[:days, self * 14]])
+    ActiveSupport::Duration.new(self * 2.weeks, [[:weeks, self * 2]])
   end
   alias :fortnight :fortnights
 
-  # Reads best without arguments:  10.minutes.ago
-  def ago(time = ::Time.current)
-    time - self
-  end
-
-  # Reads best with argument:  10.minutes.until(time)
-  alias :until :ago
-
-  # Reads best with argument:  10.minutes.since(time)
-  def since(time = ::Time.current)
-    time + self
+  # Returns the number of milliseconds equivalent to the seconds provided.
+  # Used with the standard time durations, like 1.hour.in_milliseconds --
+  # so we can feed them to JavaScript functions like getTime().
+  #
+  #   2.in_milliseconds # => 2_000
+  def in_milliseconds
+    self * 1000
   end
-
-  # Reads best without arguments:  10.minutes.from_now
-  alias :from_now :since
 end

data/lib/active_support/core_ext/numeric.rb

@@ -1,2 +1,4 @@
 require 'active_support/core_ext/numeric/bytes'
 require 'active_support/core_ext/numeric/time'
+require 'active_support/core_ext/numeric/inquiry'
+require 'active_support/core_ext/numeric/conversions'

data/lib/active_support/core_ext/object/acts_like.rb

@@ -1,9 +1,9 @@
 class Object
   # A duck-type assistant method. For example, Active Support extends Date
-  # to define an acts_like_date? method, and extends Time to define
-  # acts_like_time?. As a result, we can do "x.acts_like?(:time)" and
-  # "x.acts_like?(:date)" to do duck-type-safe comparisons, since classes that
-  # we want to act like Time simply need to define an acts_like_time? method.
+  # to define an <tt>acts_like_date?</tt> method, and extends Time to define
+  # <tt>acts_like_time?</tt>. As a result, we can do <tt>x.acts_like?(:time)</tt> and
+  # <tt>x.acts_like?(:date)</tt> to do duck-type-safe comparisons, since classes that
+  # we want to act like Time simply need to define an <tt>acts_like_time?</tt> method.
   def acts_like?(duck)
     respond_to? :"acts_like_#{duck}?"
   end

data/lib/active_support/core_ext/object/blank.rb

@@ -1,37 +1,43 @@
 class Object
   # An object is blank if it's false, empty, or a whitespace string.
-  # For example, "", "   ", +nil+, [], and {} are all blank.
+  # For example, +false+, '', '   ', +nil+, [], and {} are all blank.
   #
-  # This simplifies:
+  # This simplifies
   #
-  #   if address.nil? || address.empty?
+  #   !address || address.empty?
   #
-  # ...to:
+  # to
   #
-  #   if address.blank?
+  #   address.blank?
+  #
+  # @return [true, false]
   def blank?
-    respond_to?(:empty?) ? empty? : !self
+    respond_to?(:empty?) ? !!empty? : !self
   end
 
-  # An object is present if it's not <tt>blank?</tt>.
+  # An object is present if it's not blank.
+  #
+  # @return [true, false]
   def present?
     !blank?
   end
 
-  # Returns object if it's <tt>present?</tt> otherwise returns +nil+.
-  # <tt>object.presence</tt> is equivalent to <tt>object.present? ? object : nil</tt>.
+  # Returns the receiver if it's present otherwise returns +nil+.
+  # <tt>object.presence</tt> is equivalent to
   #
-  # This is handy for any representation of objects where blank is the same
-  # as not present at all.  For example, this simplifies a common check for
-  # HTTP POST/query parameters:
+  #    object.present? ? object : nil
+  #
+  # For example, something like
   #
   #   state   = params[:state]   if params[:state].present?
   #   country = params[:country] if params[:country].present?
   #   region  = state || country || 'US'
   #
-  # ...becomes:
+  # becomes
   #
   #   region = params[:state].presence || params[:country].presence || 'US'
+  #
+  # @return [Object]
   def presence
     self if present?
   end
@@ -42,6 +48,7 @@ class NilClass
   #
   #   nil.blank? # => true
   #
+  # @return [true]
   def blank?
     true
   end
@@ -52,6 +59,7 @@ class FalseClass
   #
   #   false.blank? # => true
   #
+  # @return [true]
   def blank?
     true
   end
@@ -62,6 +70,7 @@ class TrueClass
   #
   #   true.blank? # => false
   #
+  # @return [false]
   def blank?
     false
   end
@@ -73,6 +82,7 @@ class Array
   #   [].blank?      # => true
   #   [1,2,3].blank? # => false
   #
+  # @return [true, false]
   alias_method :blank?, :empty?
 end
 
@@ -80,20 +90,32 @@ class Hash
   # A hash is blank if it's empty:
   #
   #   {}.blank?                # => true
-  #   {:key => 'value'}.blank? # => false
+  #   { key: 'value' }.blank?  # => false
   #
+  # @return [true, false]
   alias_method :blank?, :empty?
 end
 
 class String
+  BLANK_RE = /\A[[:space:]]*\z/
+
   # A string is blank if it's empty or contains whitespaces only:
   #
-  #   "".blank?                 # => true
-  #   "   ".blank?              # => true
-  #   " something here ".blank? # => false
+  #   ''.blank?       # => true
+  #   '   '.blank?    # => true
+  #   "\t\n\r".blank? # => true
+  #   ' blah '.blank? # => false
+  #
+  # Unicode whitespace is supported:
+  #
+  #   "\u00a0".blank? # => true
   #
+  # @return [true, false]
   def blank?
-    self !~ /\S/
+    # The regexp that matches blank strings is expensive. For the case of empty
+    # strings we can speed up this method (~3.5x) with an empty? call. The
+    # penalty for the rest of strings is marginal.
+    empty? || BLANK_RE === self
   end
 end
 
@@ -103,6 +125,18 @@ class Numeric #:nodoc:
   #   1.blank? # => false
   #   0.blank? # => false
   #
+  # @return [false]
+  def blank?
+    false
+  end
+end
+
+class Time #:nodoc:
+  # No Time is blank:
+  #
+  #   Time.now.blank? # => false
+  #
+  # @return [false]
   def blank?
     false
   end

data/lib/active_support/core_ext/object/deep_dup.rb

@@ -0,0 +1,53 @@
+require 'active_support/core_ext/object/duplicable'
+
+class Object
+  # Returns a deep copy of object if it's duplicable. If it's
+  # not duplicable, returns +self+.
+  #
+  #   object = Object.new
+  #   dup    = object.deep_dup
+  #   dup.instance_variable_set(:@a, 1)
+  #
+  #   object.instance_variable_defined?(:@a) # => false
+  #   dup.instance_variable_defined?(:@a)    # => true
+  def deep_dup
+    duplicable? ? dup : self
+  end
+end
+
+class Array
+  # Returns a deep copy of array.
+  #
+  #   array = [1, [2, 3]]
+  #   dup   = array.deep_dup
+  #   dup[1][2] = 4
+  #
+  #   array[1][2] # => nil
+  #   dup[1][2]   # => 4
+  def deep_dup
+    map(&:deep_dup)
+  end
+end
+
+class Hash
+  # Returns a deep copy of hash.
+  #
+  #   hash = { a: { b: 'b' } }
+  #   dup  = hash.deep_dup
+  #   dup[:a][:c] = 'c'
+  #
+  #   hash[:a][:c] # => nil
+  #   dup[:a][:c]  # => "c"
+  def deep_dup
+    hash = dup
+    each_pair do |key, value|
+      if key.frozen? && ::String === key
+        hash[key] = value.deep_dup
+      else
+        hash.delete(key)
+        hash[key.deep_dup] = value.deep_dup
+      end
+    end
+    hash
+  end
+end

data/lib/active_support/core_ext/object/duplicable.rb

@@ -19,7 +19,7 @@
 class Object
   # Can you safely dup this object?
   #
-  # False for +nil+, +false+, +true+, symbols, numbers, class and module objects;
+  # False for +nil+, +false+, +true+, symbol, number, method objects;
   # true otherwise.
   def duplicable?
     true
@@ -31,7 +31,6 @@ class NilClass
   #
   #   nil.duplicable? # => false
   #   nil.dup         # => TypeError: can't dup NilClass
-  #
   def duplicable?
     false
   end
@@ -42,7 +41,6 @@ class FalseClass
   #
   #   false.duplicable? # => false
   #   false.dup         # => TypeError: can't dup FalseClass
-  #
   def duplicable?
     false
   end
@@ -53,7 +51,6 @@ class TrueClass
   #
   #   true.duplicable? # => false
   #   true.dup         # => TypeError: can't dup TrueClass
-  #
   def duplicable?
     false
   end
@@ -64,7 +61,6 @@ class Symbol
   #
   #   :my_symbol.duplicable? # => false
   #   :my_symbol.dup         # => TypeError: can't dup Symbol
-  #
   def duplicable?
     false
   end
@@ -74,32 +70,28 @@ class Numeric
   # Numbers are not duplicable:
   #
   #  3.duplicable? # => false
-  #  3.dup         # => TypeError: can't dup Fixnum
-  #
+  #  3.dup         # => TypeError: can't dup Integer
   def duplicable?
     false
   end
 end
 
-class Class
-  # Classes are not duplicable:
+require 'bigdecimal'
+class BigDecimal
+  # BigDecimals are duplicable:
   #
-  #  c = Class.new # => #<Class:0x10328fd80>
-  #  c.dup         # => #<Class:0x10328fd80>
-  #
-  # Note +dup+ returned the same class object.
+  # BigDecimal.new("1.2").duplicable? # => true
+  # BigDecimal.new("1.2").dup         # => #<BigDecimal:...,'0.12E1',18(18)>
   def duplicable?
-    false
+    true
   end
 end
 
-class Module
-  # Modules are not duplicable:
-  #
-  #  m = Module.new # => #<Module:0x10328b6e0>
-  #  m.dup          # => #<Module:0x10328b6e0>
+class Method
+  # Methods are not duplicable:
   #
-  # Note +dup+ returned the same module object.
+  #  method(:puts).duplicable? # => false
+  #  method(:puts).dup         # => TypeError: allocator undefined for Method
   def duplicable?
     false
   end

data/lib/active_support/core_ext/object/inclusion.rb

@@ -5,11 +5,23 @@ class Object
   #   characters = ["Konata", "Kagami", "Tsukasa"]
   #   "Konata".in?(characters) # => true
   #
-  # This will throw an ArgumentError if the argument doesn't respond
+  # This will throw an +ArgumentError+ if the argument doesn't respond
   # to +#include?+.
   def in?(another_object)
     another_object.include?(self)
   rescue NoMethodError
     raise ArgumentError.new("The parameter passed to #in? must respond to #include?")
   end
+
+  # Returns the receiver if it's included in the argument otherwise returns +nil+.
+  # Argument must be any object which responds to +#include?+. Usage:
+  #
+  #   params[:bucket_type].presence_in %w( project calendar )
+  #
+  # This will throw an +ArgumentError+ if the argument doesn't respond to +#include?+.
+  #
+  # @return [Object]
+  def presence_in(another_object)
+    self.in?(another_object) ? self : nil
+  end
 end

data/lib/active_support/core_ext/object/instance_variables.rb

@@ -1,6 +1,6 @@
 class Object
-  # Returns a hash that maps instance variable names without "@" to their
-  # corresponding values. Keys are strings both in Ruby 1.8 and 1.9.
+  # Returns a hash with string keys that maps instance variable names without "@" to their
+  # corresponding values.
   #
   #   class C
   #     def initialize(x, y)
@@ -9,12 +9,11 @@ class Object
   #   end
   #
   #   C.new(0, 1).instance_values # => {"x" => 0, "y" => 1}
-  def instance_values #:nodoc:
-    Hash[instance_variables.map { |name| [name.to_s[1..-1], instance_variable_get(name)] }]
+  def instance_values
+    Hash[instance_variables.map { |name| [name[1..-1], instance_variable_get(name)] }]
   end
 
-  # Returns an array of instance variable names including "@". They are strings
-  # both in Ruby 1.8 and 1.9.
+  # Returns an array of instance variable names as strings including "@".
   #
   #   class C
   #     def initialize(x, y)
@@ -23,11 +22,7 @@ class Object
   #   end
   #
   #   C.new(0, 1).instance_variable_names # => ["@y", "@x"]
-  if RUBY_VERSION >= '1.9'
-    def instance_variable_names
-      instance_variables.map { |var| var.to_s }
-    end
-  else
-    alias_method :instance_variable_names, :instance_variables
+  def instance_variable_names
+    instance_variables.map(&:to_s)
   end
 end