[Feature #22118] Introduce Basic Bit Operations into String (#17353)

This patch adds the following methods to String class:

* String#bit_get(offset, lsb_first: true) -> 1 | 0 | nil
* String#bit_set?(offset, lsb_first: true) -> true | false | nil
* String#bit_set(offset, lsb_first: true) -> self
* String#bit_clear(offset, lsb_first: true) -> self
* String#bit_flip(offset, lsb_first: true) -> self
* String#bit_count -> Integer
* String#bitwise_not -> String
* String#bitwise_not! -> self
* String#bitwise_and(other) -> String
* String#bitwise_and!(other) -> self
* String#bitwise_or(other) -> String
* String#bitwise_or!(other) -> self
* String#bitwise_xor(other) -> String
* String#bitwise_xor!(other) -> self

Other than implementation, tests, specs, and docs are added.

Link: [Feature #22118]

## Note

In `string.c`, I wrote some big macro that create method functions and helper
functions:

* STR_DEFINE_BINARY_BITWISE_METHOD
* STR_DEFINE_UNARY_BITWISE_KERNEL
* STR_DEFINE_BINARY_BITWISE_KERNEL

While using macros like this reduces maintainability, I believe it's acceptable
because there are no plans to extend the `bitwise_*` methods beyond this
proposal, and the logic is stable.

On the other hand, other methods such as `bit_get` and `bit_count` are planned to
have argument extensions in the future.

Author: hasumikin

core/string/bit_clear_spec.rb

@@ -0,0 +1,33 @@
+# encoding: binary
+require_relative '../../spec_helper'
+
+ruby_version_is "4.1" do
+  describe "String#bit_clear" do
+    it "clears a bit in LSB-first order by default and returns self" do
+      str = +"\xFF"
+      str.bit_clear(1).should.equal?(str)
+      str.should == "\xFD"
+    end
+
+    it "clears a bit in MSB-first order" do
+      str = +"\xFF"
+      str.bit_clear(1, lsb_first: false)
+      str.should == "\xBF"
+    end
+
+    it "preserves byte order when using MSB-first order" do
+      str = +"\xFF\xFF"
+      str.bit_clear(8, lsb_first: false)
+      str.should == "\xFF\x7F"
+    end
+
+    it "raises an IndexError for an out of range bit offset" do
+      -> { "\x00".bit_clear(8) }.should.raise(IndexError)
+      -> { "\x00".bit_clear(-1) }.should.raise(IndexError)
+    end
+
+    it "raises a FrozenError if self is frozen" do
+      -> { "\x00".freeze.bit_clear(0) }.should.raise(FrozenError)
+    end
+  end
+end

core/string/bit_count_spec.rb

@@ -0,0 +1,18 @@
+# encoding: binary
+require_relative '../../spec_helper'
+
+ruby_version_is "4.1" do
+  describe "String#bit_count" do
+    it "returns the number of set bits in the string" do
+      "".bit_count.should == 0
+      "\x00".bit_count.should == 0
+      "\xFF".bit_count.should == 8
+      "\xAA\xF0".bit_count.should == 8
+    end
+
+    it "raises an ArgumentError when given an argument" do
+      -> { "\x00".bit_count(0) }.should.raise(ArgumentError)
+      -> { "\x00".bit_count(lsb_first: false) }.should.raise(ArgumentError)
+    end
+  end
+end

core/string/bit_flip_spec.rb

@@ -0,0 +1,35 @@
+# encoding: binary
+require_relative '../../spec_helper'
+
+ruby_version_is "4.1" do
+  describe "String#bit_flip" do
+    it "flips a bit in LSB-first order by default and returns self" do
+      str = +"\x00"
+      str.bit_flip(1).should.equal?(str)
+      str.should == "\x02"
+      str.bit_flip(1)
+      str.should == "\x00"
+    end
+
+    it "flips a bit in MSB-first order" do
+      str = +"\x00"
+      str.bit_flip(1, lsb_first: false)
+      str.should == "\x40"
+    end
+
+    it "preserves byte order when using MSB-first order" do
+      str = +"\x00\x00"
+      str.bit_flip(8, lsb_first: false)
+      str.should == "\x00\x80"
+    end
+
+    it "raises an IndexError for an out of range bit offset" do
+      -> { "\x00".bit_flip(8) }.should.raise(IndexError)
+      -> { "\x00".bit_flip(-1) }.should.raise(IndexError)
+    end
+
+    it "raises a FrozenError if self is frozen" do
+      -> { "\x00".freeze.bit_flip(0) }.should.raise(FrozenError)
+    end
+  end
+end

core/string/bit_get_spec.rb

@@ -0,0 +1,38 @@
+# encoding: binary
+require_relative '../../spec_helper'
+
+ruby_version_is "4.1" do
+  describe "String#bit_get" do
+    it "returns 0 or 1 for a bit offset in LSB-first order by default" do
+      str = "\xAA"
+      str.bit_get(0).should == 0
+      str.bit_get(1).should == 1
+      str.bit_get(7).should == 1
+    end
+
+    it "returns 0 or 1 for a bit offset in MSB-first order" do
+      str = "\xAA"
+      str.bit_get(0, lsb_first: false).should == 1
+      str.bit_get(1, lsb_first: false).should == 0
+      str.bit_get(7, lsb_first: false).should == 0
+    end
+
+    it "preserves byte order when using MSB-first order" do
+      str = "\x00\x80"
+      str.bit_get(8, lsb_first: false).should == 1
+    end
+
+    it "returns nil for a bit offset beyond the string" do
+      "\x00".bit_get(8).should == nil
+      "".bit_get(0).should == nil
+    end
+
+    it "raises an IndexError for a negative bit offset" do
+      -> { "\x00".bit_get(-1) }.should.raise(IndexError)
+    end
+
+    it "raises an ArgumentError for an invalid lsb_first value" do
+      -> { "\x00".bit_get(0, lsb_first: nil) }.should.raise(ArgumentError)
+    end
+  end
+end

core/string/bit_set_p_spec.rb

@@ -0,0 +1,38 @@
+# encoding: binary
+require_relative '../../spec_helper'
+
+ruby_version_is "4.1" do
+  describe "String#bit_set?" do
+    it "returns true or false for a bit offset in LSB-first order by default" do
+      str = "\xAA"
+      str.bit_set?(0).should == false
+      str.bit_set?(1).should == true
+      str.bit_set?(7).should == true
+    end
+
+    it "returns true or false for a bit offset in MSB-first order" do
+      str = "\xAA"
+      str.bit_set?(0, lsb_first: false).should == true
+      str.bit_set?(1, lsb_first: false).should == false
+      str.bit_set?(7, lsb_first: false).should == false
+    end
+
+    it "preserves byte order when using MSB-first order" do
+      str = "\x00\x80"
+      str.bit_set?(8, lsb_first: false).should == true
+    end
+
+    it "returns nil for a bit offset beyond the string" do
+      "\x00".bit_set?(8).should == nil
+      "".bit_set?(0).should == nil
+    end
+
+    it "raises an IndexError for a negative bit offset" do
+      -> { "\x00".bit_set?(-1) }.should.raise(IndexError)
+    end
+
+    it "raises an ArgumentError for an invalid lsb_first value" do
+      -> { "\x00".bit_set?(0, lsb_first: nil) }.should.raise(ArgumentError)
+    end
+  end
+end

core/string/bit_set_spec.rb

@@ -0,0 +1,33 @@
+# encoding: binary
+require_relative '../../spec_helper'
+
+ruby_version_is "4.1" do
+  describe "String#bit_set" do
+    it "sets a bit in LSB-first order by default and returns self" do
+      str = +"\x00"
+      str.bit_set(1).should.equal?(str)
+      str.should == "\x02"
+    end
+
+    it "sets a bit in MSB-first order" do
+      str = +"\x00"
+      str.bit_set(1, lsb_first: false)
+      str.should == "\x40"
+    end
+
+    it "preserves byte order when using MSB-first order" do
+      str = +"\x00\x00"
+      str.bit_set(8, lsb_first: false)
+      str.should == "\x00\x80"
+    end
+
+    it "raises an IndexError for an out of range bit offset" do
+      -> { "\x00".bit_set(8) }.should.raise(IndexError)
+      -> { "\x00".bit_set(-1) }.should.raise(IndexError)
+    end
+
+    it "raises a FrozenError if self is frozen" do
+      -> { "\x00".freeze.bit_set(0) }.should.raise(FrozenError)
+    end
+  end
+end

core/string/bitwise_and_spec.rb

@@ -0,0 +1,41 @@
+# encoding: binary
+require_relative '../../spec_helper'
+
+ruby_version_is "4.1" do
+  describe "String#bitwise_and" do
+    it "returns a new string containing the byte-wise AND with another string" do
+      str = "\xF0"
+      result = str.bitwise_and("\xCC")
+      result.should == "\xC0".b
+      result.should_not.equal?(str)
+      str.should == "\xF0"
+    end
+
+    it "converts the argument with to_str" do
+      other = mock("string")
+      other.should_receive(:to_str).and_return("\xCC")
+      "\xF0".bitwise_and(other).should == "\xC0".b
+    end
+
+    it "raises an ArgumentError if byte sizes differ" do
+      -> { "\xF0".bitwise_and("") }.should.raise(ArgumentError)
+      -> { "\xF0".bitwise_and("\x00\x00") }.should.raise(ArgumentError)
+    end
+
+    it "returns a BINARY string" do
+      (+"\xF0").force_encoding("UTF-8").bitwise_and("\xCC").encoding.should == Encoding::BINARY
+    end
+  end
+
+  describe "String#bitwise_and!" do
+    it "replaces self with the byte-wise AND and returns self" do
+      str = +"\xF0"
+      str.bitwise_and!("\xCC").should.equal?(str)
+      str.should == "\xC0"
+    end
+
+    it "raises a FrozenError if self is frozen" do
+      -> { "\x00".freeze.bitwise_and!("\x00") }.should.raise(FrozenError)
+    end
+  end
+end

core/string/bitwise_not_spec.rb

@@ -0,0 +1,31 @@
+# encoding: binary
+require_relative '../../spec_helper'
+
+ruby_version_is "4.1" do
+  describe "String#bitwise_not" do
+    it "returns a new string with every bit inverted" do
+      str = "\x00\xAA"
+      result = str.bitwise_not
+      result.should == "\xFF\x55".b
+      result.should_not.equal?(str)
+      str.should == "\x00\xAA"
+    end
+
+    it "returns a BINARY string" do
+      str = (+"\x00").force_encoding("US-ASCII")
+      str.bitwise_not.encoding.should == Encoding::BINARY
+    end
+  end
+
+  describe "String#bitwise_not!" do
+    it "inverts every bit in self and returns self" do
+      str = +"\x00\xAA"
+      str.bitwise_not!.should.equal?(str)
+      str.should == "\xFF\x55"
+    end
+
+    it "raises a FrozenError if self is frozen" do
+      -> { "\x00".freeze.bitwise_not! }.should.raise(FrozenError)
+    end
+  end
+end

core/string/bitwise_or_spec.rb

@@ -0,0 +1,41 @@
+# encoding: binary
+require_relative '../../spec_helper'
+
+ruby_version_is "4.1" do
+  describe "String#bitwise_or" do
+    it "returns a new string containing the byte-wise OR with another string" do
+      str = "\xF0"
+      result = str.bitwise_or("\x0C")
+      result.should == "\xFC".b
+      result.should_not.equal?(str)
+      str.should == "\xF0"
+    end
+
+    it "converts the argument with to_str" do
+      other = mock("string")
+      other.should_receive(:to_str).and_return("\x0C")
+      "\xF0".bitwise_or(other).should == "\xFC".b
+    end
+
+    it "raises an ArgumentError if byte sizes differ" do
+      -> { "\xF0".bitwise_or("") }.should.raise(ArgumentError)
+      -> { "\xF0".bitwise_or("\x00\x00") }.should.raise(ArgumentError)
+    end
+
+    it "returns a BINARY string" do
+      (+"\xF0").force_encoding("UTF-8").bitwise_or("\x0C").encoding.should == Encoding::BINARY
+    end
+  end
+
+  describe "String#bitwise_or!" do
+    it "replaces self with the byte-wise OR and returns self" do
+      str = +"\xF0"
+      str.bitwise_or!("\x0C").should.equal?(str)
+      str.should == "\xFC"
+    end
+
+    it "raises a FrozenError if self is frozen" do
+      -> { "\x00".freeze.bitwise_or!("\x00") }.should.raise(FrozenError)
+    end
+  end
+end

core/string/bitwise_xor_spec.rb

@@ -0,0 +1,41 @@
+# encoding: binary
+require_relative '../../spec_helper'
+
+ruby_version_is "4.1" do
+  describe "String#bitwise_xor" do
+    it "returns a new string containing the byte-wise XOR with another string" do
+      str = "\xF0"
+      result = str.bitwise_xor("\xCC")
+      result.should == "\x3C".b
+      result.should_not.equal?(str)
+      str.should == "\xF0"
+    end
+
+    it "converts the argument with to_str" do
+      other = mock("string")
+      other.should_receive(:to_str).and_return("\xCC")
+      "\xF0".bitwise_xor(other).should == "\x3C".b
+    end
+
+    it "raises an ArgumentError if byte sizes differ" do
+      -> { "\xF0".bitwise_xor("") }.should.raise(ArgumentError)
+      -> { "\xF0".bitwise_xor("\x00\x00") }.should.raise(ArgumentError)
+    end
+
+    it "returns a BINARY string" do
+      (+"\xF0").force_encoding("UTF-8").bitwise_xor("\xCC").encoding.should == Encoding::BINARY
+    end
+  end
+
+  describe "String#bitwise_xor!" do
+    it "replaces self with the byte-wise XOR and returns self" do
+      str = +"\xF0"
+      str.bitwise_xor!("\xCC").should.equal?(str)
+      str.should == "\x3C"
+    end
+
+    it "raises a FrozenError if self is frozen" do
+      -> { "\x00".freeze.bitwise_xor!("\x00") }.should.raise(FrozenError)
+    end
+  end
+end