It should be part of the documented public API, since we have an entire
section of the guides dedicated to it. Documented in a way that
addresses the concerns which kept it undocumented in the past.

pattern removal

added example for string#remove and test case for remove of multiple occurence of pattern

removed extra whitespaces

1. spacing issues
2. spelling correction
3. grammar correction
4. Add missing docs

Ruby 2.2 knows this, and no longer matches it with [[:space:]], so it's
not a good candidate for testing String#squish.

(This is a manual merge of #9102)

before this change, we were allocating AS::SafeBuffer objects that were
being interpolated in to a string, so the safe buffer object was being
thrown away.  This change only allocates a string (vs a string *and* a
safebuffer) and interpolates the string.

On my test application, this reduced the AS::SafeBuffer objects from
1527k per request to about 500 per request.

html_escape_interpolated_argument is only used in mutation methods:

  https://github.com/rails/rails/blob/c07d09559ec171e1904b55c7ad7e8c7d586ca51b/activesupport/lib/active_support/core_ext/string/output_safety.rb#L174
  https://github.com/rails/rails/blob/c07d09559ec171e1904b55c7ad7e8c7d586ca51b/activesupport/lib/active_support/core_ext/string/output_safety.rb#L179

The return value doesn't need to be converted to an AS::SafeBuffer since
we know that the current object is an AS::SafeBuffer and will be
mutated, and the return value from html_escape_interpolated_argument
will be thrown away

Before:
  When calling String#pluralize with count=1 then it returned same
  string, but with count other than 1, returned new string.

After:
  String#pluralize always return a new string.

  => Prevent mutation of a string inadvertently.

While calling String#first or String#last with zero or a Fixnum < the
string's length returns a new string, a Fixnum >= the string's length
returns the string itself. This inconsistency can lead to inadvertent
mutation of a string.

Change to require all active_support/deprecation since that's the actual
entry point for the deprecation methods.

Make `#prepend` method modify instance in-place and return self
instead of just returning modified value. That is exactly what
`#prepend!` method was doing previously, so it's deprecated from
now on.

The behavior of json_escape was fixed in 2f1c5789, but the doc
changes and example in that commit incorrectly indicated that the
return value would be html-safe. Since quotation marks are
preserved, the raw value is not safe to use in other contexts
(specifically HTML attributes).

This reverts commit 2ef1fb2c.

As described in PR #13627 this commit broke functionality when passing
a negative Fixnum to the `String#to` method:

```ruby
assert_equal "hell", s.to(-2)
```

Before the revert, this failed with:

```
  1) Failure:
StringAccessTest#test_#to_with_negative_Fixnum,_position_is_counted_from_the_end [test/core_ext/string_ext_test.rb:275]:
Expected: "hell"
  Actual: nil
```

This revert is to keep the functionality on `master` working.
If there is another way to get the performance benefit and keep
the documented functionality we can add that.

/cc @amatsuda @carlosantoniodasilva

Interpolation was untested and did not work with hash arguments.

Adds
- support for interpolation with hash argument
- tests for the above
- tests for safe/unsafe interpolation

Use the already existing strings instead of creating a new one each time
just to test if it responds to the methods.

According to our guideline, we leave 1 space between `#` and `=>`, so we
want `# =>` instead of `#=>`.

Thanks to @fxn for the suggestion.

[ci skip]

So strings can be humanized without being capitalized:

    'employee_salary'.humanize                    # => "Employee salary"
    'employee_salary'.humanize(capitalize: false) # => "employee salary"

Benchmark:
          user     system      total        real
old   1.550000   0.040000   1.590000 (  1.585866)
new   1.250000   0.040000   1.290000 (  1.287693)

Benchmark:
1000000.times { str.to(30) }
          user     system      total        real
old   0.490000   0.110000   0.600000 (  0.607374)
new   0.390000   0.000000   0.390000 (  0.387306)

core extensions (`core_ext/string/encoding`).

This reverts commit 8ce3c1e5, reversing
changes made to f93da579.

Reason: It slow down the running time.

require "diffbench"
load 'output_safety.rb'

N = 10000
b = ActiveSupport::SafeBuffer.new("hello world")
DiffBench.bm do
  report "capitalize in safe buffer" do
    N.times do
      b.capitalize
    end
  end
end

> git checkout  069ea45c; diffbench bench.rb;
diffbench bench.rb;diffbench
bench.rb;diffbench bench.rb;diffbench
bench.rb;diffbench bench.rb;diffbench
bench.rb;

Running benchmark with current working tree
Checkout HEAD^
Running benchmark with HEAD^
Checkout to previous HEAD again

                    user     system      total
                    real
----------------------------------capitalize
in safe buffer
After patch:    0.010000   0.000000   0.010000
(  0.009733)
Before patch:   0.010000   0.000000   0.010000
(  0.007702)
Improvement: -26%

Running benchmark with current working tree
Checkout HEAD^
Running benchmark with HEAD^
Checkout to previous HEAD again

                    user     system      total
                    real
----------------------------------capitalize
in safe buffer
After patch:    0.010000   0.000000   0.010000
(  0.009768)
Before patch:   0.010000   0.000000   0.010000
(  0.007896)
Improvement: -24%

Running benchmark with current working tree
Checkout HEAD^
Running benchmark with HEAD^
Checkout to previous HEAD again

                    user     system      total
                    real
----------------------------------capitalize
in safe buffer
After patch:    0.010000   0.000000   0.010000
(  0.009938)
Before patch:   0.010000   0.000000   0.010000
(  0.007768)
Improvement: -28%

Running benchmark with current working tree
Checkout HEAD^
Running benchmark with HEAD^
Checkout to previous HEAD again

                    user     system      total
                    real
----------------------------------capitalize
in safe buffer
After patch:    0.010000   0.000000   0.010000
(  0.010001)
Before patch:   0.010000   0.000000   0.010000
(  0.007873)
Improvement: -27%

Running benchmark with current working tree
Checkout HEAD^
Running benchmark with HEAD^
Checkout to previous HEAD again

                    user     system      total
                    real
----------------------------------capitalize
in safe buffer
After patch:    0.010000   0.000000   0.010000
(  0.009670)
Before patch:   0.010000   0.000000   0.010000
(  0.007800)
Improvement: -24%

Running benchmark with current working tree
Checkout HEAD^
Running benchmark with HEAD^
Checkout to previous HEAD again

                    user     system      total
                    real
----------------------------------capitalize
in safe buffer
After patch:    0.010000   0.000000   0.010000
(  0.009949)
Before patch:   0.010000   0.000000   0.010000
(  0.007752)
Improvement: -28%