Skip to content

Add String#bit_get, bit_set?, bit_set, bit_clear, bit_flip and bit_count (Feature #22118) - #10118

Draft
zev wants to merge 1 commit into
jruby:ruby-4.1from
zev:string-bit-ops
Draft

zev wants to merge 1 commit into
jruby:ruby-4.1from
zev:string-bit-ops

Conversation

@zev

@zev zev commented Nov 18, 2026

Copy link
Copy Markdown
Contributor

Adds the String bit methods from Ruby 4.1: bit_get, bit_set?, bit_set, bit_clear, bit_flip and bit_count (Feature #22118). It includes the region arguments (Feature #22279) and the frozen check before the bounds check (Bug #22316). These are on the #9746 checklist. The bitwise_* methods from the same feature come in a separate PR, based on this one.

CRuby changes: ruby/ruby@2461caebba, ruby/ruby@03a426ec8d, ruby/ruby@d8d75cee41. Current code: string.c#L7424-L8209.

Call CRuby 4.1 JRuby before JRuby after
"\xAA".b.bit_get(1) 1 NoMethodError: undefined method 'bit_get' ... 1
"\xAA".b.bit_get(0, lsb_first: false) 1 NoMethodError 1
"\xAA".b.bit_set?(8) nil NoMethodError nil
(+"\x00\x00").b.bit_set(4, 8) "\xF0\x0F" NoMethodError "\xF0\x0F"
(+"\xFF").b.bit_clear(0..3) "\xF0" NoMethodError "\xF0"
(+"\x00").b.bit_flip(0, 9) IndexError: bit range out of range NoMethodError same as CRuby
"\x00".b.freeze.bit_set(9, 0) FrozenError: can't modify frozen String: "\x00" NoMethodError same as CRuby
"\xFF\x0F".b.bit_count(4, 100) 8 NoMethodError 8
"\x00".b.bit_get(-1) IndexError: bit index out of range NoMethodError same as CRuby
"\x00".b.bit_count(0) ArgumentError: no bit length given NoMethodError same as CRuby

Changes

  • New org.jruby.util.StringBits. It holds the logic, split like CRuby's helpers: offset and length conversion, Range conversion, the byte mask for a region, the region write, and the bit count. Each method has a @CRuby annotation, with a note where it ports only part of a function.
  • Bit positions above 2**63. CRuby keeps positions as uint64_t. Positions from 2**63 to 2**64-1 are stored as Long.MAX_VALUE. They are past the end of every JRuby string, so every comparison gives the same result. Above 2**64-1, it raises ArgumentError, as CRuby does.
  • RubyString. It adds thin @JRubyMethod overloads with keywords = true, so a positional Hash is not read as lsb_first: (s.bit_get(0, {lsb_first: false}) raises ArgumentError, as in CRuby).
  • Order of checks, as in CRuby. Writes check frozen? after converting the arguments and before the bounds check. The string size is read after the frozen check, because a chilled-string warning handler can change the string. Writes clear the code range.
  • Bit counting. It reads eight bytes at a time with a VarHandle and Long.bitCount.

Specs

I copied CRuby's newer bit_set_spec.rb, bit_clear_spec.rb, bit_flip_spec.rb and bit_count_spec.rb from spec/ruby/core/string (CRuby d8d75cee41). They add the region and frozen cases. bit_get_spec.rb and bit_set_p_spec.rb already matched CRuby.

Testing

  • The six bit_* spec files: 47 examples, 0 failures, 0 errors on JRuby (interpreter and forced JIT) and CRuby 4.1.0-dev. CRuby 4.0.7 runs 0 examples, because of the version guard. On the base branch, all 29 old examples errored.
  • spec/ruby/core/string (mspec ci): no new failures. The 29 bit_* errors are gone. The remaining errors are the bitwise_* specs, which the next PR fixes.
  • test/mri/ruby/test_string.rb: 0 failures, as before. JRuby's copy has no bit tests yet.
  • CRuby's own test_string.rb (master, copied outside the tree): all test_bit_* tests pass, except the 9 *_chilled_string_warning tests. Those fail because of an existing JRuby issue (see below). The same tests pass by hand without --debug.
  • A script with about 300 calls (offsets and lengths of every kind, Ranges, lsb_first:, frozen strings, encodings, shared strings, and to_int that changes the receiver) gives the same output as CRuby 4.1.0-dev, except for the messages listed below.

Not in this PR

  • For a wrong argument count together with keywords, JRuby's arity check counts the keyword Hash as an argument: s.bit_get(0, 1, lsb_first: true) says (given 3, expected 1..2), while CRuby says (given 2, expected 1). s.bit_get with no arguments says expected 1..2, while CRuby says expected 1. Other methods that take keywords, like String#unpack1, already behave the same way.
  • With two unknown keywords, JRuby names only the first (unknown keyword: :foo). CRuby lists both (unknown keywords: :foo, :bar). The message comes from the shared ArgsUtil.extractKeywordArg.
  • With --debug, JRuby's chilled-string warning (RubyString DebugChilledString) is sent without category: :deprecated, so a Warning.warn handler that checks the category doesn't see it. JRuby's assert_separately adds --debug, so CRuby's *_chilled_string_warning tests (including the existing setbyte and << ones) fail on JRuby.
  • If a warning handler shrinks a chilled string, String#setbyte raises a Java ArrayIndexOutOfBoundsException, because it checks the index before the frozen check. CRuby fixed the same case in 0b60b0e4c5.

🤖 Generated with Claude Code

…unt (Feature #22118)

These read, change and count single bits of a string's bytes. Bit 0 is
the least significant bit of the first byte; lsb_first: false numbers
the bits in each byte from the most significant bit instead.

bit_set, bit_clear, bit_flip and bit_count also take a region, as an
offset and a length or as a Range (Feature #22279). Writes raise
IndexError when the region runs past the end; bit_count clips it. The
frozen check comes before the bounds check, as in CRuby (Bug #22316).

The logic lives in the new org.jruby.util.StringBits. Bit positions
from 2**63 to 2**64-1 are kept as Long.MAX_VALUE: they are past the end
of every JRuby string, so the results are the same as CRuby's.

Updates the bit_set, bit_clear, bit_flip and bit_count specs from
CRuby's spec/ruby, which add the region and frozen cases.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant