Deprecate Encoding#replicate

* See [Feature #18949].

5 files changed, 71 insertions, 53 deletions

diff --git a/NEWS.md b/NEWS.md
index 4dd8cbbe2b..407458bbe5 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -96,6 +96,9 @@ Note that each entry is kept to a minimum, see links for details.
 
 Note: We're only listing outstanding class updates.
 
+* Encoding
+    * Encoding#replicate has been deprecated and will be removed in 3.3. [[Feature #18949]]
+
 * Enumerator
     * Enumerator.product has been added.  Enumerator::Product is the implementation. [[Feature #18685]]
 
@@ -292,3 +295,4 @@ The following deprecated APIs are removed.
 [Feature #18788]: https://bugs.ruby-lang.org/issues/18788
 [Feature #18809]: https://bugs.ruby-lang.org/issues/18809
 [Feature #18481]: https://bugs.ruby-lang.org/issues/18481
+[Feature #18949]: https://bugs.ruby-lang.org/issues/18949
diff --git a/common.mk b/common.mk
index fc05b3bd45..94c5a3a994 100644
--- a/common.mk
+++ b/common.mk
@@ -5418,6 +5418,7 @@ encoding.$(OBJEXT): $(top_srcdir)/internal/class.h
 encoding.$(OBJEXT): $(top_srcdir)/internal/compilers.h
 encoding.$(OBJEXT): $(top_srcdir)/internal/enc.h
 encoding.$(OBJEXT): $(top_srcdir)/internal/encoding.h
+encoding.$(OBJEXT): $(top_srcdir)/internal/error.h
 encoding.$(OBJEXT): $(top_srcdir)/internal/gc.h
 encoding.$(OBJEXT): $(top_srcdir)/internal/inits.h
 encoding.$(OBJEXT): $(top_srcdir)/internal/load.h
diff --git a/encoding.c b/encoding.c
index b8fedfb797..5c4dfad3f0 100644
--- a/encoding.c
+++ b/encoding.c
@@ -17,6 +17,7 @@
 #include "internal.h"
 #include "internal/enc.h"
 #include "internal/encoding.h"
+#include "internal/error.h"
 #include "internal/inits.h"
 #include "internal/load.h"
 #include "internal/object.h"
@@ -569,7 +570,10 @@ rb_enc_replicate(const char *name, rb_encoding *encoding)
 static VALUE
 enc_replicate_m(VALUE encoding, VALUE name)
 {
-    int idx = rb_enc_replicate(name_for_encoding(&name), rb_to_encoding(encoding));
+    int idx;
+    rb_warn_deprecated_to_remove("3.3", "Encoding#replicate", "the original encoding");
+
+    idx = rb_enc_replicate(name_for_encoding(&name), rb_to_encoding(encoding));
     RB_GC_GUARD(name);
     return rb_enc_from_encoding_index(idx);
 }
diff --git a/spec/ruby/core/encoding/replicate_spec.rb b/spec/ruby/core/encoding/replicate_spec.rb
index 45727a5c0d..848415eeb4 100644
--- a/spec/ruby/core/encoding/replicate_spec.rb
+++ b/spec/ruby/core/encoding/replicate_spec.rb
@@ -2,66 +2,74 @@
 require_relative '../../spec_helper'
 
 describe "Encoding#replicate" do
-  before :all do
-    @i = 0
-  end
+  ruby_version_is ""..."3.3" do
+    before :all do
+      @i = 0
+    end
 
-  before :each do
-    @i += 1
-    @prefix = "RS#{@i}"
-  end
+    before :each do
+      @i += 1
+      @prefix = "RS#{@i}"
+    end
 
-  it "returns a replica of ASCII" do
-    name = @prefix + '-ASCII'
-    e = Encoding::ASCII.replicate(name)
-    e.name.should == name
-    Encoding.find(name).should == e
+    it "returns a replica of ASCII" do
+      name = @prefix + '-ASCII'
+      e = suppress_warning { Encoding::ASCII.replicate(name) }
+      e.name.should == name
+      Encoding.find(name).should == e
 
-    "a".force_encoding(e).valid_encoding?.should be_true
-    "\x80".force_encoding(e).valid_encoding?.should be_false
-  end
+      "a".force_encoding(e).valid_encoding?.should be_true
+      "\x80".force_encoding(e).valid_encoding?.should be_false
+    end
 
-  it "returns a replica of UTF-8" do
-    name = @prefix + 'UTF-8'
-    e = Encoding::UTF_8.replicate(name)
-    e.name.should == name
-    Encoding.find(name).should == e
+    it "returns a replica of UTF-8" do
+      name = @prefix + 'UTF-8'
+      e = suppress_warning { Encoding::UTF_8.replicate(name) }
+      e.name.should == name
+      Encoding.find(name).should == e
 
-    "a".force_encoding(e).valid_encoding?.should be_true
-    "\u3042".force_encoding(e).valid_encoding?.should be_true
-    "\x80".force_encoding(e).valid_encoding?.should be_false
-  end
+      "a".force_encoding(e).valid_encoding?.should be_true
+      "\u3042".force_encoding(e).valid_encoding?.should be_true
+      "\x80".force_encoding(e).valid_encoding?.should be_false
+    end
 
-  it "returns a replica of UTF-16BE" do
-    name = @prefix + 'UTF-16-BE'
-    e = Encoding::UTF_16BE.replicate(name)
-    e.name.should == name
-    Encoding.find(name).should == e
+    it "returns a replica of UTF-16BE" do
+      name = @prefix + 'UTF-16-BE'
+      e = suppress_warning { Encoding::UTF_16BE.replicate(name) }
+      e.name.should == name
+      Encoding.find(name).should == e
 
-    "a".force_encoding(e).valid_encoding?.should be_false
-    "\x30\x42".force_encoding(e).valid_encoding?.should be_true
-    "\x80".force_encoding(e).valid_encoding?.should be_false
-  end
+      "a".force_encoding(e).valid_encoding?.should be_false
+      "\x30\x42".force_encoding(e).valid_encoding?.should be_true
+      "\x80".force_encoding(e).valid_encoding?.should be_false
+    end
 
-  it "returns a replica of ISO-2022-JP" do
-    name = @prefix + 'ISO-2022-JP'
-    e = Encoding::ISO_2022_JP.replicate(name)
-    Encoding.find(name).should == e
+    it "returns a replica of ISO-2022-JP" do
+      name = @prefix + 'ISO-2022-JP'
+      e = suppress_warning { Encoding::ISO_2022_JP.replicate(name) }
+      Encoding.find(name).should == e
 
-    e.name.should == name
-    e.dummy?.should be_true
-  end
+      e.name.should == name
+      e.dummy?.should be_true
+    end
 
-  # NOTE: it's unclear of the value of this (for the complexity cost of it),
-  # but it is the current CRuby behavior.
-  it "can be associated with a String" do
-    name = @prefix + '-US-ASCII'
-    e = Encoding::US_ASCII.replicate(name)
-    e.name.should == name
-    Encoding.find(name).should == e
+    # NOTE: it's unclear of the value of this (for the complexity cost of it),
+    # but it is the current CRuby behavior.
+    it "can be associated with a String" do
+      name = @prefix + '-US-ASCII'
+      e = suppress_warning { Encoding::US_ASCII.replicate(name) }
+      e.name.should == name
+      Encoding.find(name).should == e
+
+      s = "abc".force_encoding(e)
+      s.encoding.should == e
+      s.encoding.name.should == name
+    end
+  end
 
-    s = "abc".force_encoding(e)
-    s.encoding.should == e
-    s.encoding.name.should == name
+  ruby_version_is "3.3" do
+    it "has been removed" do
+      Encoding::US_ASCII.should_not.respond_to?(:replicate, true)
+    end
   end
 end
diff --git a/test/ruby/test_encoding.rb b/test/ruby/test_encoding.rb
index 4a6dd932ed..64af8b488a 100644
--- a/test/ruby/test_encoding.rb
+++ b/test/ruby/test_encoding.rb
@@ -57,6 +57,7 @@ class TestEncoding < Test::Unit::TestCase
 
   def test_replicate
     assert_separately([], "#{<<~'END;'}")
+    Warning[:deprecated] = false
     assert_instance_of(Encoding, Encoding::UTF_8.replicate("UTF-8-ANOTHER#{Time.now.to_f}"))
     assert_instance_of(Encoding, Encoding::ISO_2022_JP.replicate("ISO-2022-JP-ANOTHER#{Time.now.to_f}"))
     bug3127 = '[ruby-dev:40954]'
@@ -69,7 +70,7 @@ class TestEncoding < Test::Unit::TestCase
     assert_separately([], "#{<<~"begin;"}\n#{<<~'end;'}")
     begin;
       200.times {|i|
-        Encoding::UTF_8.replicate("dummy#{i}")
+        EnvUtil.suppress_warning { Encoding::UTF_8.replicate("dummy#{i}") }
       }
       e = Encoding.list.last
       format = "%d".force_encoding(e)
@@ -82,7 +83,7 @@ class TestEncoding < Test::Unit::TestCase
 
       name = "A" * 64
       Encoding.list.each do |enc|
-        assert_raise(ArgumentError) {enc.replicate(name)}
+        assert_raise(ArgumentError) { EnvUtil.suppress_warning { enc.replicate(name) } }
         name.succ!
       end
     end;