activesupport 5.0.0 → 6.1.0

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

@@ -1,9 +1,11 @@
+# frozen_string_literal: true
+
 class String
   # If you pass a single integer, returns a substring of one character at that
   # position. The first character of the string is at position 0, the next at
   # position 1, and so on. If a range is supplied, a substring containing
   # characters at offsets given by the range is returned. In both cases, if an
-  # offset is negative, it is counted from the end of the string. Returns nil
+  # offset is negative, it is counted from the end of the string. Returns +nil+
   # if the initial offset falls outside the string. Returns an empty string if
   # the beginning of the range is greater than the end of the string.
   #
@@ -17,7 +19,7 @@ class String
   #
   # If a Regexp is given, the matching portion of the string is returned.
   # If a String is given, that given string is returned if it occurs in
-  # the string. In both cases, nil is returned if there is no match.
+  # the string. In both cases, +nil+ is returned if there is no match.
   #
   #   str = "hello"
   #   str.at(/lo/) # => "lo"
@@ -42,7 +44,7 @@ class String
   #   str.from(0).to(-1) # => "hello"
   #   str.from(1).to(-2) # => "ell"
   def from(position)
-    self[position..-1]
+    self[position, length]
   end
 
   # Returns a substring from the beginning of the string to the given position.
@@ -59,7 +61,8 @@ class String
   #   str.from(0).to(-1) # => "hello"
   #   str.from(1).to(-2) # => "ell"
   def to(position)
-    self[0..position]
+    position += size if position < 0
+    self[0, position + 1] || +""
   end
 
   # Returns the first character. If a limit is supplied, returns a substring
@@ -73,13 +76,7 @@ class String
   #   str.first(0) # => ""
   #   str.first(6) # => "hello"
   def first(limit = 1)
-    if limit == 0
-      ''
-    elsif limit >= size
-      self.dup
-    else
-      to(limit - 1)
-    end
+    self[0, limit] || raise(ArgumentError, "negative limit")
   end
 
   # Returns the last character of the string. If a limit is supplied, returns a substring
@@ -93,12 +90,6 @@ class String
   #   str.last(0) # => ""
   #   str.last(6) # => "hello"
   def last(limit = 1)
-    if limit == 0
-      ''
-    elsif limit >= size
-      self.dup
-    else
-      from(-limit)
-    end
+    self[[length - limit, 0].max, limit] || raise(ArgumentError, "negative limit")
   end
 end

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

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

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

@@ -1,5 +1,7 @@
-require 'date'
-require 'active_support/core_ext/time/calculations'
+# frozen_string_literal: true
+
+require "date"
+require "active_support/core_ext/time/calculations"
 
 class String
   # Converts a string to a Time value.
@@ -16,6 +18,7 @@ class String
   #   "2012-12-13T06:12".to_time         # => 2012-12-13 06:12:00 +0100
   #   "2012-12-13T06:12".to_time(:utc)   # => 2012-12-13 06:12:00 UTC
   #   "12/13/2012".to_time               # => ArgumentError: argument out of range
+  #   "1604326192".to_time               # => ArgumentError: argument out of range
   def to_time(form = :local)
     parts = Date._parse(self, false)
     used_keys = %i(year mon mday hour min sec sec_fraction offset)

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 class String
   # The inverse of <tt>String#include?</tt>. Returns true if the string
   # does not include the other string.

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 class String
   # Returns the string, first removing all whitespace on both ends of
   # the string, and then changing remaining consecutive whitespace
@@ -17,7 +19,7 @@ class String
   #   str.squish!                         # => "foo bar boo"
   #   str                                 # => "foo bar boo"
   def squish!
-    gsub!(/[[:space:]]+/, ' ')
+    gsub!(/[[:space:]]+/, " ")
     strip!
     self
   end
@@ -64,7 +66,7 @@ class String
   def truncate(truncate_at, options = {})
     return dup unless length > truncate_at
 
-    omission = options[:omission] || '...'
+    omission = options[:omission] || "..."
     length_with_room_for_omission = truncate_at - omission.length
     stop = \
       if options[:separator]
@@ -73,7 +75,48 @@ class String
         length_with_room_for_omission
       end
 
-    "#{self[0, stop]}#{omission}"
+    +"#{self[0, stop]}#{omission}"
+  end
+
+  # Truncates +text+ to at most <tt>bytesize</tt> bytes in length without
+  # breaking string encoding by splitting multibyte characters or breaking
+  # grapheme clusters ("perceptual characters") by truncating at combining
+  # characters.
+  #
+  #   >> "🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪".size
+  #   => 20
+  #   >> "🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪".bytesize
+  #   => 80
+  #   >> "🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪".truncate_bytes(20)
+  #   => "🔪🔪🔪🔪…"
+  #
+  # The truncated text ends with the <tt>:omission</tt> string, defaulting
+  # to "…", for a total length not exceeding <tt>bytesize</tt>.
+  def truncate_bytes(truncate_at, omission: "…")
+    omission ||= ""
+
+    case
+    when bytesize <= truncate_at
+      dup
+    when omission.bytesize > truncate_at
+      raise ArgumentError, "Omission #{omission.inspect} is #{omission.bytesize}, larger than the truncation length of #{truncate_at} bytes"
+    when omission.bytesize == truncate_at
+      omission.dup
+    else
+      self.class.new.tap do |cut|
+        cut_at = truncate_at - omission.bytesize
+
+        scan(/\X/) do |grapheme|
+          if cut.bytesize + grapheme.bytesize <= cut_at
+            cut << grapheme
+          else
+            break
+          end
+        end
+
+        cut << omission
+      end
+    end
   end
 
   # Truncates a given +text+ after a given number of words (<tt>words_count</tt>):
@@ -94,7 +137,7 @@ class String
     sep = options[:separator] || /\s+/
     sep = Regexp.escape(sep.to_s) unless Regexp === sep
     if self =~ /\A((?>.+?#{sep}){#{words_count - 1}}.+?)#{sep}.*/m
-      $1 + (options[:omission] || '...')
+      $1 + (options[:omission] || "...")
     else
       dup
     end

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

@@ -1,9 +1,11 @@
+# frozen_string_literal: true
+
 class String
   # Same as +indent+, except it indents the receiver in-place.
   #
   # Returns the indented string, or +nil+ if there was nothing to indent.
-  def indent!(amount, indent_string=nil, indent_empty_lines=false)
-    indent_string = indent_string || self[/^[ \t]/] || ' '
+  def indent!(amount, indent_string = nil, indent_empty_lines = false)
+    indent_string = indent_string || self[/^[ \t]/] || " "
     re = indent_empty_lines ? /^/ : /^(?!$)/
     gsub!(re, indent_string * amount)
   end
@@ -37,7 +39,7 @@ class String
   #   "foo\n\nbar".indent(2)            # => "  foo\n\n  bar"
   #   "foo\n\nbar".indent(2, nil, true) # => "  foo\n  \n  bar"
   #
-  def indent(amount, indent_string=nil, indent_empty_lines=false)
-    dup.tap {|_| _.indent!(amount, indent_string, indent_empty_lines)}
+  def indent(amount, indent_string = nil, indent_empty_lines = false)
+    dup.tap { |_| _.indent!(amount, indent_string, indent_empty_lines) }
   end
 end

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

@@ -1,5 +1,7 @@
-require 'active_support/inflector/methods'
-require 'active_support/inflector/transliterate'
+# frozen_string_literal: true
+
+require "active_support/inflector/methods"
+require "active_support/inflector/transliterate"
 
 # String inflections define new methods on the String class to transform names for different purposes.
 # For instance, you can figure out the name of a table from the name of a class.
@@ -28,10 +30,12 @@ class String
   #   'apple'.pluralize(2)         # => "apples"
   #   'ley'.pluralize(:es)         # => "leyes"
   #   'ley'.pluralize(1, :es)      # => "ley"
+  #
+  # See ActiveSupport::Inflector.pluralize.
   def pluralize(count = nil, locale = :en)
     locale = count if count.is_a?(Symbol)
     if count == 1
-      self.dup
+      dup
     else
       ActiveSupport::Inflector.pluralize(self, locale)
     end
@@ -51,28 +55,34 @@ class String
   #   'the blue mailmen'.singularize # => "the blue mailman"
   #   'CamelOctopi'.singularize      # => "CamelOctopus"
   #   'leyes'.singularize(:es)       # => "ley"
+  #
+  # See ActiveSupport::Inflector.singularize.
   def singularize(locale = :en)
     ActiveSupport::Inflector.singularize(self, locale)
   end
 
   # +constantize+ tries to find a declared constant with the name specified
   # in the string. It raises a NameError when the name is not in CamelCase
-  # or is not initialized.  See ActiveSupport::Inflector.constantize
+  # or is not initialized.
   #
   #   'Module'.constantize  # => Module
   #   'Class'.constantize   # => Class
   #   'blargle'.constantize # => NameError: wrong constant name blargle
+  #
+  # See ActiveSupport::Inflector.constantize.
   def constantize
     ActiveSupport::Inflector.constantize(self)
   end
 
   # +safe_constantize+ tries to find a declared constant with the name specified
-  # in the string. It returns nil when the name is not in CamelCase
-  # or is not initialized.  See ActiveSupport::Inflector.safe_constantize
+  # in the string. It returns +nil+ when the name is not in CamelCase
+  # or is not initialized.
   #
   #   'Module'.safe_constantize  # => Module
   #   'Class'.safe_constantize   # => Class
   #   'blargle'.safe_constantize # => nil
+  #
+  # See ActiveSupport::Inflector.safe_constantize.
   def safe_constantize
     ActiveSupport::Inflector.safe_constantize(self)
   end
@@ -86,12 +96,18 @@ class String
   #   'active_record'.camelize(:lower)        # => "activeRecord"
   #   'active_record/errors'.camelize         # => "ActiveRecord::Errors"
   #   'active_record/errors'.camelize(:lower) # => "activeRecord::Errors"
+  #
+  # +camelize+ is also aliased as +camelcase+.
+  #
+  # See ActiveSupport::Inflector.camelize.
   def camelize(first_letter = :upper)
     case first_letter
     when :upper
       ActiveSupport::Inflector.camelize(self, true)
     when :lower
       ActiveSupport::Inflector.camelize(self, false)
+    else
+      raise ArgumentError, "Invalid option, use either :upper or :lower."
     end
   end
   alias_method :camelcase, :camelize
@@ -100,12 +116,19 @@ class String
   # a nicer looking title. +titleize+ is meant for creating pretty output. It is not
   # used in the Rails internals.
   #
+  # The trailing '_id','Id'.. can be kept and capitalized by setting the
+  # optional parameter +keep_id_suffix+ to true.
+  # By default, this parameter is false.
+  #
+  #   'man from the boondocks'.titleize                       # => "Man From The Boondocks"
+  #   'x-men: the last stand'.titleize                        # => "X Men: The Last Stand"
+  #   'string_ending_with_id'.titleize(keep_id_suffix: true)  # => "String Ending With Id"
+  #
   # +titleize+ is also aliased as +titlecase+.
   #
-  #   'man from the boondocks'.titleize # => "Man From The Boondocks"
-  #   'x-men: the last stand'.titleize  # => "X Men: The Last Stand"
-  def titleize
-    ActiveSupport::Inflector.titleize(self)
+  # See ActiveSupport::Inflector.titleize.
+  def titleize(keep_id_suffix: false)
+    ActiveSupport::Inflector.titleize(self, keep_id_suffix: keep_id_suffix)
   end
   alias_method :titlecase, :titleize
 
@@ -115,6 +138,8 @@ class String
   #
   #   'ActiveModel'.underscore         # => "active_model"
   #   'ActiveModel::Errors'.underscore # => "active_model/errors"
+  #
+  # See ActiveSupport::Inflector.underscore.
   def underscore
     ActiveSupport::Inflector.underscore(self)
   end
@@ -122,16 +147,20 @@ class String
   # Replaces underscores with dashes in the string.
   #
   #   'puni_puni'.dasherize # => "puni-puni"
+  #
+  # See ActiveSupport::Inflector.dasherize.
   def dasherize
     ActiveSupport::Inflector.dasherize(self)
   end
 
   # Removes the module part from the constant expression in the string.
   #
-  #   'ActiveRecord::CoreExtensions::String::Inflections'.demodulize # => "Inflections"
-  #   'Inflections'.demodulize                                       # => "Inflections"
-  #   '::Inflections'.demodulize                                     # => "Inflections"
-  #   ''.demodulize                                                  # => ''
+  #   'ActiveSupport::Inflector::Inflections'.demodulize # => "Inflections"
+  #   'Inflections'.demodulize                           # => "Inflections"
+  #   '::Inflections'.demodulize                         # => "Inflections"
+  #   ''.demodulize                                      # => ''
+  #
+  # See ActiveSupport::Inflector.demodulize.
   #
   # See also +deconstantize+.
   def demodulize
@@ -146,6 +175,8 @@ class String
   #   '::String'.deconstantize    # => ""
   #   ''.deconstantize            # => ""
   #
+  # See ActiveSupport::Inflector.deconstantize.
+  #
   # See also +demodulize+.
   def deconstantize
     ActiveSupport::Inflector.deconstantize(self)
@@ -153,6 +184,11 @@ class String
 
   # Replaces special characters in a string so that it may be used as part of a 'pretty' URL.
   #
+  # If the optional parameter +locale+ is specified,
+  # the word will be parameterized as a word of that language.
+  # By default, this parameter is set to <tt>nil</tt> and it will use
+  # the configured <tt>I18n.locale</tt>.
+  #
   #   class Person
   #     def to_param
   #       "#{id}-#{name.parameterize}"
@@ -164,8 +200,8 @@ class String
   #
   #   <%= link_to(@person.name, person_path) %>
   #   # => <a href="/person/1-donald-e-knuth">Donald E. Knuth</a>
-  #   
-  # To preserve the case of the characters in a string, use the `preserve_case` argument.
+  #
+  # To preserve the case of the characters in a string, use the +preserve_case+ argument.
   #
   #   class Person
   #     def to_param
@@ -178,12 +214,10 @@ class String
   #
   #   <%= 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)
+  #
+  # See ActiveSupport::Inflector.parameterize.
+  def parameterize(separator: "-", preserve_case: false, locale: nil)
+    ActiveSupport::Inflector.parameterize(self, separator: separator, preserve_case: preserve_case, locale: locale)
   end
 
   # Creates the name of a table like Rails does for models to table names. This method
@@ -192,6 +226,8 @@ class String
   #   'RawScaledScorer'.tableize # => "raw_scaled_scorers"
   #   'ham_and_egg'.tableize     # => "ham_and_eggs"
   #   'fancyCategory'.tableize   # => "fancy_categories"
+  #
+  # See ActiveSupport::Inflector.tableize.
   def tableize
     ActiveSupport::Inflector.tableize(self)
   end
@@ -202,11 +238,13 @@ class String
   #
   #   'ham_and_eggs'.classify # => "HamAndEgg"
   #   'posts'.classify        # => "Post"
+  #
+  # See ActiveSupport::Inflector.classify.
   def classify
     ActiveSupport::Inflector.classify(self)
   end
 
-  # Capitalizes the first word, turns underscores into spaces, and strips a
+  # Capitalizes the first word, turns underscores into spaces, and (by default)strips a
   # trailing '_id' if present.
   # Like +titleize+, this is meant for creating pretty output.
   #
@@ -214,12 +252,19 @@ class String
   # optional parameter +capitalize+ to false.
   # By default, this parameter is true.
   #
-  #   'employee_salary'.humanize              # => "Employee salary"
-  #   'author_id'.humanize                    # => "Author"
-  #   'author_id'.humanize(capitalize: false) # => "author"
-  #   '_id'.humanize                          # => "Id"
-  def humanize(options = {})
-    ActiveSupport::Inflector.humanize(self, options)
+  # The trailing '_id' can be kept and capitalized by setting the
+  # optional parameter +keep_id_suffix+ to true.
+  # By default, this parameter is false.
+  #
+  #   'employee_salary'.humanize                    # => "Employee salary"
+  #   'author_id'.humanize                          # => "Author"
+  #   'author_id'.humanize(capitalize: false)       # => "author"
+  #   '_id'.humanize                                # => "Id"
+  #   'author_id'.humanize(keep_id_suffix: true)    # => "Author Id"
+  #
+  # See ActiveSupport::Inflector.humanize.
+  def humanize(capitalize: true, keep_id_suffix: false)
+    ActiveSupport::Inflector.humanize(self, capitalize: capitalize, keep_id_suffix: keep_id_suffix)
   end
 
   # Converts just the first character to uppercase.
@@ -227,6 +272,8 @@ class String
   #   'what a Lovely Day'.upcase_first # => "What a Lovely Day"
   #   'w'.upcase_first                 # => "W"
   #   ''.upcase_first                  # => ""
+  #
+  # See ActiveSupport::Inflector.upcase_first.
   def upcase_first
     ActiveSupport::Inflector.upcase_first(self)
   end
@@ -238,6 +285,8 @@ class String
   #   'Message'.foreign_key        # => "message_id"
   #   'Message'.foreign_key(false) # => "messageid"
   #   'Admin::Post'.foreign_key    # => "post_id"
+  #
+  # See ActiveSupport::Inflector.foreign_key.
   def foreign_key(separate_class_name_and_id_with_underscore = true)
     ActiveSupport::Inflector.foreign_key(self, separate_class_name_and_id_with_underscore)
   end

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

@@ -1,4 +1,7 @@
-require 'active_support/string_inquirer'
+# frozen_string_literal: true
+
+require "active_support/string_inquirer"
+require "active_support/environment_inquirer"
 
 class String
   # Wraps the current string in the <tt>ActiveSupport::StringInquirer</tt> class,

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

@@ -1,4 +1,6 @@
-require 'active_support/multibyte'
+# frozen_string_literal: true
+
+require "active_support/multibyte"
 
 class String
   # == Multibyte proxy
@@ -9,11 +11,14 @@ 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.
   #
-  #   >> "lj".upcase
-  #   => "lj"
   #   >> "lj".mb_chars.upcase.to_s
   #   => "LJ"
   #
+  # NOTE: Ruby 2.4 and later support native Unicode case mappings:
+  #
+  #   >> "lj".upcase
+  #   => "LJ"
+  #
   # == Method chaining
   #
   # All the methods on the Chars proxy which normally return a string will return a Chars object. This allows
@@ -42,9 +47,9 @@ class String
   #   iso_str.is_utf8?   # => false
   def is_utf8?
     case encoding
-    when Encoding::UTF_8
+    when Encoding::UTF_8, Encoding::US_ASCII
       valid_encoding?
-    when Encoding::ASCII_8BIT, Encoding::US_ASCII
+    when Encoding::ASCII_8BIT
       dup.force_encoding(Encoding::UTF_8).valid_encoding?
     else
       false