pack.c: add an offset argument to unpack and unpack1

[Feature #18254]

This is useful to avoid repeteadly copying strings when parsing binary formats

core/string/unpack/shared/basic.rb

@@ -16,6 +16,12 @@
   it "raises a TypeError when passed an Integer" do
     -> { "abc".unpack(1) }.should raise_error(TypeError)
   end
+
+  ruby_version_is "3.1" do
+    it "starts unpacking from the given offset" do
+      "abc".unpack("CC", offset: 1).should == [98, 99]
+    end
+  end
 end
 
 describe :string_unpack_no_platform, shared: true do
@@ -26,4 +32,18 @@
   it "raises an ArgumentError when the format modifier is '!'" do
     -> { "abcdefgh".unpack(unpack_format("!")) }.should raise_error(ArgumentError)
   end
+
+  ruby_version_is "3.1" do
+    it "raises an ArgumentError when the offset is negative" do
+      -> { "a".unpack("C", offset: -1) }.should raise_error(ArgumentError)
+    end
+
+    it "returns nil if the offset is at the end of the string" do
+      "a".unpack("C", offset: 1).should == [nil]
+    end
+
+    it "raises an ArgumentError when the offset is larget than the string" do
+      -> { "a".unpack("C", offset: 2) }.should raise_error(ArgumentError)
+    end
+  end
 end

core/string/unpack1_spec.rb

@@ -7,4 +7,24 @@
     "aG9nZWZ1Z2E=".unpack1("m").should == "hogefuga"
     "A".unpack1("B*").should == "01000001"
   end
+
+  ruby_version_is "3.1" do
+    it "starts unpacking from the given offset" do
+      "ZZABCD".unpack1('x3C', offset: 2).should == "ABCD".unpack('x3C')[0]
+      "ZZZZaG9nZWZ1Z2E=".unpack1("m", offset: 4).should == "hogefuga"
+      "ZA".unpack1("B*", offset: 1).should == "01000001"
+    end
+
+    it "raises an ArgumentError when the offset is negative" do
+      -> { "a".unpack1("C", offset: -1) }.should raise_error(ArgumentError)
+    end
+
+    it "returns nil if the offset is at the end of the string" do
+      "a".unpack1("C", offset: 1).should == nil
+    end
+
+    it "raises an ArgumentError when the offset is larget than the string" do
+      -> { "a".unpack1("C", offset: 2) }.should raise_error(ArgumentError)
+    end
+  end
 end