string_bits 0.1.0 → 0.2.1

data/ext/string_bits/string_bits.c

@@ -2,10 +2,40 @@
 #include "ruby/encoding.h"
 
 #include <limits.h>     /* CHAR_BIT */
-#include <stdint.h>     /* uint64_t, UINT64_MAX */
+#include <stdint.h>     /* uint64_t, UINT64_MAX, int64_t, intptr_t */
+#include <inttypes.h>   /* PRIdPTR (ssize_t via intptr_t), PRId64 */
 #include <string.h>     /* memcpy */
 #include <sys/types.h>  /* ssize_t (Ruby typedefs it on Windows) */
 
+/* Whole-string bit length, computed in 64 bits.
+ *
+ * RSTRING_LEN returns a pointer-width signed length, so `RSTRING_LEN(s) * 8`
+ * overflows a signed 32-bit ssize_t once a string reaches 2**28 bytes (256 MiB)
+ * on an ILP32 build, corrupting every bounds check that compares a bit offset
+ * against it. Valid bit indices are confined to the Fixnum range and always fit
+ * ssize_t, so only this whole-string bit length needs the wider type: computing
+ * it in int64_t keeps the bounds checks correct on 32-bit without changing the
+ * public pointer-width bit-index contract (see Discussion.md, "Error behavior
+ * for out-of-range bit indices").
+ *
+ * Porting to Ruby Core:
+ *   1. Core String lengths are `long` (RSTRING_LEN), which is pointer-width,
+ *      so `RSTRING_LEN(str) * 8` overflows on ILP32 for strings >= 256 MiB
+ *      exactly as it does for ssize_t here. Keep the whole-string bit length
+ *      in a 64-bit intermediate at every bounds check; do not hold it in a
+ *      `long`. Reuse this macro (or an equivalent inline) rather than open-
+ *      coding `len * 8`.
+ *   2. Keep the public bit-index type pointer-width and keep rejecting
+ *      out-of-range positions with ArgumentError (see the cross-reference
+ *      above). Only this internal length is widened, so the contract that
+ *      core inherits is unchanged.
+ *   3. The error-message format specifiers below (<inttypes.h>: (intptr_t)
+ *      with PRIdPTR for bit offsets, PRId64 for this widened length) exist
+ *      only because this length is wider than the offsets. In core, follow
+ *      the local convention for formatting `long` offsets and pick a 64-bit
+ *      specifier for the widened length accordingly. */
+#define SB_BIT_LEN(byte_len) ((int64_t)(byte_len) * 8)
+
 /* popcount ----------------------------------------------------------------- */
 /*
  * Porting to Ruby Core:
@@ -70,7 +100,7 @@ sb_popcount64(uint64_t x)
 /* ctz / clz helpers for set-bit iteration ---------------------------------- */
 
 static ID id_bracket;
-static VALUE sym_lsb_first, sym_lsb, sym_msb, sym_invert;
+static VALUE sym_lsb_first, sym_invert;
 
 enum sb_kw_flag {
     SB_KW_INVERT = 1 << 0,
@@ -190,27 +220,10 @@ integer_to_bit_idx(VALUE n)
     UNREACHABLE_RETURN(0);
 }
 
-static ssize_t
-check_bit_index(VALUE self, VALUE n, int lsb_first)
-{
-    if (!rb_integer_type_p(n)) {
-        rb_raise(rb_eTypeError, "bit index must be an integer");
-    }
-    ssize_t idx = integer_to_bit_idx(n);
-    ssize_t size = RSTRING_LEN(self) * 8;
-    if (idx < 0 || idx >= size) {
-        rb_raise(rb_eIndexError, "bit index out of range");
-    }
-    if (!lsb_first) idx = (idx & ~7L) | (7 - (idx & 7L));
-    return idx;
-}
-
-static inline ssize_t
-physical_to_count_from(ssize_t physical, int lsb_first)
-{
-    return lsb_first ? physical : ((physical & ~7L) | (7 - (physical & 7L)));
-}
-
+/* Bit numbering between byte-with-LSB-as-bit-0 and byte-with-MSB-as-bit-0
+ * is an involution: swapping in either direction uses the same formula
+ * `(x & ~7) | (7 - (x & 7))`. logical_to_physical is therefore symmetric and
+ * is reused on the return path (physical -> logical) as well. */
 static inline ssize_t
 logical_to_physical(ssize_t logical, int lsb_first)
 {
@@ -237,6 +250,20 @@ logical_write_bit(unsigned char *ptr, ssize_t logical_index, int lsb_first, int
     physical_write_bit(ptr, logical_to_physical(logical_index, lsb_first), bit);
 }
 
+static ssize_t
+check_bit_index(VALUE self, VALUE n, int lsb_first)
+{
+    if (!rb_integer_type_p(n)) {
+        rb_raise(rb_eTypeError, "bit index must be an integer");
+    }
+    ssize_t idx = integer_to_bit_idx(n);
+    int64_t size = SB_BIT_LEN(RSTRING_LEN(self));
+    if (idx < 0 || idx >= size) {
+        rb_raise(rb_eIndexError, "bit index out of range");
+    }
+    return logical_to_physical(idx, lsb_first);
+}
+
 /* ssize_t-interface wrapper around rb_range_beg_len.
  *
  * rb_range_beg_len() takes (long *begp, long *lenp, long len), but this
@@ -266,11 +293,49 @@ sb_range_beg_len_call(VALUE arg)
     return rb_range_beg_len(a->range, a->lbegp, a->llenp, a->len, a->err);
 }
 
+/* Validate Range endpoints for bit position arguments.
+ * Raises ArgumentError for:
+ *   - any explicit (non-nil) Bignum endpoint: cannot address any real string,
+ *     consistent with integer_to_bit_idx behavior for scalar indices.
+ *   - any explicit (non-nil) negative endpoint: count-from-end semantics
+ *     interact confusingly with lsb_first: true/false.
+ * RBIGNUM_NEGATIVE_P is used for the negativity check on Bignums to avoid
+ * calling NUM2LL on values that do not fit in long long.
+ *
+ * Porting to Ruby Core:
+ *   Replace rb_range_values() with direct struct access:
+ *     #include "internal/range.h"
+ *     beg  = RANGE_BEG(range);
+ *     end  = RANGE_END(range);
+ *     excl = RANGE_EXCL(range);
+ */
+static void
+sb_range_validate_endpoints(VALUE range)
+{
+    VALUE beg, end;
+    int excl;
+    rb_range_values(range, &beg, &end, &excl);
+    if (!NIL_P(beg) && rb_integer_type_p(beg)) {
+        if (!FIXNUM_P(beg))
+            rb_raise(rb_eArgError, "bit index out of representable range");
+        if (FIX2LONG(beg) < 0)
+            rb_raise(rb_eIndexError,
+                     "negative Range endpoint is not allowed for bit positions");
+    }
+    if (!NIL_P(end) && rb_integer_type_p(end)) {
+        if (!FIXNUM_P(end))
+            rb_raise(rb_eArgError, "bit index out of representable range");
+        if (FIX2LONG(end) < 0)
+            rb_raise(rb_eIndexError,
+                     "negative Range endpoint is not allowed for bit positions");
+    }
+}
+
 static inline VALUE
-sb_range_beg_len(VALUE range, ssize_t *begp, ssize_t *lenp, ssize_t len, int err)
+sb_range_beg_len(VALUE range, ssize_t *begp, ssize_t *lenp, int64_t len, int err)
 {
     long lbeg = 0, llen = 0;
-    long clipped = (len > (ssize_t)LONG_MAX) ? LONG_MAX : (long)len;
+    long clipped = (len > (int64_t)LONG_MAX) ? LONG_MAX : (long)len;
     struct sb_range_args args = { range, &lbeg, &llen, clipped, err };
     int state = 0;
     VALUE result = rb_protect(sb_range_beg_len_call, (VALUE)&args, &state);
@@ -325,53 +390,42 @@ parse_lsb_first_opt(VALUE opts)
     return parse_bool_opt(opts, sym_lsb_first, "lsb_first", 1);
 }
 
-static int
-parse_lsb_first(int argc, VALUE *argv)
+/* Parse an optional start_offset positional argument (Qnil => 0).
+ * Raises ArgumentError for Bignum, IndexError for negative Fixnum. */
+static ssize_t
+parse_start_offset(VALUE v)
 {
-    VALUE opts = Qnil;
-    rb_scan_args(argc, argv, "0:", &opts);
-    validate_option_hash(opts, SB_KW_LSB_FIRST);
-    return parse_lsb_first_opt(opts);
+    if (NIL_P(v)) return 0;
+    ssize_t start_offset = integer_to_bit_idx(v);  /* raises ArgumentError for Bignum */
+    if (start_offset < 0)
+        rb_raise(rb_eIndexError, "bit_offset must be non-negative");
+    return start_offset;
 }
 
 /* read -------------------------------------------------------------------- */
 
-/* String#bit_at(n, lsb_first: true) -> true or false
- *
- * bit_at uses flat/Arrow convention: byte_index = n/8 from start, bit = n%8 from LSB
- * e.g. "\xAA\xCC": bit 0..7 live in byte[0]=0xAA, bit 8..15 live in byte[1]=0xCC
- *
- *   str = "\xFF\xAA" # 11111111 10101010
- *   str.bit_at(0) # => true (1st bit is set)
- *   str.bit_at(7) # => true (8th bit is set)
- *   str.bit_at(8) # => false (9th bit is clear)
- *   str.bit_at(9) # => true (10th bit is set)
- *   str.bit_at(16) # => nil
- */
+/* Return true/false/nil for the bit at flat position n. */
 static VALUE
 rb_str_bit_at(int argc, VALUE *argv, VALUE self)
 {
-    VALUE n, opts;
-    rb_scan_args(argc, argv, "1:", &n, &opts);
+    VALUE bit_offset_v, opts;
+    rb_scan_args(argc, argv, "1:", &bit_offset_v, &opts);
     validate_option_hash(opts, SB_KW_LSB_FIRST);
 
-    if (!rb_integer_type_p(n)) {
+    if (!rb_integer_type_p(bit_offset_v)) {
         rb_raise(rb_eTypeError, "bit index must be an integer");
     }
-    ssize_t idx = integer_to_bit_idx(n);
-    if (idx < 0) {
-        rb_raise(rb_eArgError, "bit index must be non-negative");
+    ssize_t bit_offset = integer_to_bit_idx(bit_offset_v);
+    if (bit_offset < 0) {
+        rb_raise(rb_eIndexError, "bit index out of range");
     }
-    ssize_t size = RSTRING_LEN(self) * 8;
-    if (size <= idx) {
+    int64_t size = SB_BIT_LEN(RSTRING_LEN(self));
+    if (size <= bit_offset) {
         return Qnil;
     }
 
     int lsb_first = parse_lsb_first_opt(opts);
-
-    if (!lsb_first) {
-        idx = (idx & ~7L) | (7 - (idx & 7L));
-    }
+    ssize_t idx = logical_to_physical(bit_offset, lsb_first);
 
     if (test_bit(RSTRING_PTR(self), idx)) {
         return Qtrue;
@@ -380,19 +434,21 @@ rb_str_bit_at(int argc, VALUE *argv, VALUE self)
     }
 }
 
-static VALUE
-rb_str_bit_count(VALUE self)
+/* count_set_bits: popcount over a raw byte buffer.
+ *
+ * Uses a 32-byte (4 x uint64_t) unrolled inner loop, falls back to 8-byte
+ * steps, and finally collects the partial trailing bytes into a single
+ * uint64_t for one more popcount. memcpy avoids unaligned-load issues on
+ * strict-alignment platforms (SPARC, MIPS); modern compilers fold the 8-byte
+ * memcpy into a single load on platforms that allow unaligned access. */
+static ssize_t
+count_set_bits(const unsigned char *str, ssize_t len)
 {
     ssize_t count = 0;
-    ssize_t len = RSTRING_LEN(self);
-    const char *str = RSTRING_PTR(self);
     ssize_t off = 0;
     ssize_t unrolled_end = len & ~31L;
     ssize_t aligned_end  = len & ~7L;
 
-    /* Use memcpy to avoid unaligned loads (SIGBUS on SPARC, MIPS, etc.)
-     * and strict-aliasing violations. Modern compilers fold 8-byte memcpy
-     * into a single load on platforms that allow unaligned access. */
     for (; off < unrolled_end; off += 32) {
         uint64_t w0, w1, w2, w3;
         memcpy(&w0, str + off,      8);
@@ -414,208 +470,374 @@ rb_str_bit_count(VALUE self)
     ssize_t remainder = len - aligned_end;
     if (remainder > 0) {
         uint64_t last = 0;
-        const unsigned char *tail = (const unsigned char *)(str + aligned_end);
+        const unsigned char *tail = str + aligned_end;
         for (ssize_t i = 0; i < remainder; i++) {
             last |= (uint64_t)tail[i] << (i * 8);
         }
         count += sb_popcount64(last);
     }
 
-    return SSIZET2NUM(count);
+    return count;
 }
 
-/* iterate bits ------------------------------------------------------------ */
+/* count_set_bits_range: popcount over [start, start+length) in LSB-first numbering.
+ * Handles non-byte-aligned start and length by masking partial first/last bytes. */
+static ssize_t
+count_set_bits_range(const unsigned char *str, ssize_t total_bytes,
+                     ssize_t start, ssize_t length)
+{
+    if (length <= 0) return 0;
+    int64_t total_bits = SB_BIT_LEN(total_bytes);
+    if (start >= total_bits) return 0;
+    if (start + length > total_bits) length = (ssize_t)(total_bits - start);
 
-static VALUE
-rb_str_each_bit(int argc, VALUE *argv, VALUE self)
+    ssize_t byte_start = start >> 3;
+    int bit_lo = (int)(start & 7);
+    ssize_t end_bit = start + length;
+    ssize_t last_byte = (end_bit - 1) >> 3;
+    int e_bit = (int)(end_bit & 7);  /* bits to use in last byte; 0 means full byte */
+
+    if (byte_start == last_byte) {
+        unsigned int b = (unsigned int)str[byte_start] >> bit_lo;
+        b &= (1u << (unsigned)length) - 1u;
+        return (ssize_t)sb_popcount64(b);
+    }
+
+    ssize_t count = 0;
+    if (bit_lo != 0) {
+        count += sb_popcount64((unsigned int)str[byte_start] >> bit_lo);
+        byte_start++;
+    }
+    ssize_t full_last = (e_bit == 0) ? last_byte + 1 : last_byte;
+    count += count_set_bits(str + byte_start, full_last - byte_start);
+    if (e_bit != 0) {
+        unsigned int b = (unsigned int)str[last_byte] & ((1u << (unsigned)e_bit) - 1u);
+        count += sb_popcount64(b);
+    }
+    return count;
+}
+
+/* count_set_bits_range_msb: same as count_set_bits_range but for MSB-first numbering.
+ * In MSB-first, position 0 within a byte is physical bit 7 (the MSB). */
+static ssize_t
+count_set_bits_range_msb(const unsigned char *str, ssize_t total_bytes,
+                          ssize_t start, ssize_t length)
 {
-    RETURN_ENUMERATOR(self, argc, argv);
+    if (length <= 0) return 0;
+    int64_t total_bits = SB_BIT_LEN(total_bytes);
+    if (start >= total_bits) return 0;
+    if (start + length > total_bits) length = (ssize_t)(total_bits - start);
 
-    int lsb_first = parse_lsb_first(argc, argv);
-    ssize_t len = RSTRING_LEN(self);
-    const unsigned char *str = (const unsigned char *)RSTRING_PTR(self);
+    ssize_t byte_start = start >> 3;
+    int s_bit = (int)(start & 7);      /* MSB-first within-byte start index */
+    ssize_t end_bit = start + length;
+    ssize_t last_byte = (end_bit - 1) >> 3;
+    int e_bit = (int)(end_bit & 7);    /* bits to use in last byte; 0 means full byte */
 
-    for (ssize_t i = 0; i < len; i++) {
-        unsigned char b = str[i];
-        if (lsb_first) {
-            for (int j = 0; j < 8; j++) {
-                rb_yield((b >> j) & 1 ? Qtrue : Qfalse);
-            }
-        } else {
-            for (int j = 7; j >= 0; j--) {
-                rb_yield((b >> j) & 1 ? Qtrue : Qfalse);
-            }
-        }
+    if (byte_start == last_byte) {
+        /* physical bits (7-s_bit) down to (7-s_bit-length+1) */
+        unsigned int b = (unsigned int)str[byte_start] >> (unsigned)(8 - s_bit - (int)length);
+        b &= (1u << (unsigned)length) - 1u;
+        return (ssize_t)sb_popcount64(b);
     }
 
-    return self;
+    ssize_t count = 0;
+    /* partial first byte: MSB-first positions s_bit..7 = physical bits 0..(7-s_bit) */
+    if (s_bit != 0) {
+        unsigned int b = (unsigned int)str[byte_start] & ((1u << (unsigned)(8 - s_bit)) - 1u);
+        count += sb_popcount64(b);
+        byte_start++;
+    }
+    ssize_t full_last = (e_bit == 0) ? last_byte + 1 : last_byte;
+    count += count_set_bits(str + byte_start, full_last - byte_start);
+    /* partial last byte: MSB-first positions 0..(e_bit-1) = physical bits (8-e_bit)..7 */
+    if (e_bit != 0) {
+        unsigned int b = (unsigned int)str[last_byte] >> (unsigned)(8 - e_bit);
+        count += sb_popcount64(b);
+    }
+    return count;
 }
 
 static VALUE
-rb_str_bits(int argc, VALUE *argv, VALUE self)
+rb_str_bit_count(int argc, VALUE *argv, VALUE self)
 {
-    int lsb_first = parse_lsb_first(argc, argv);
-    ssize_t len = RSTRING_LEN(self);
     const unsigned char *str = (const unsigned char *)RSTRING_PTR(self);
-    ssize_t total_bits = len * 8;
-    int have_block = rb_block_given_p();
+    ssize_t src_len = RSTRING_LEN(self);
 
-    VALUE ary = have_block ? Qnil : rb_ary_new_capa(total_bits);
+    VALUE v0 = Qnil, v1 = Qnil, opts = Qnil;
+    rb_scan_args(argc, argv, "02:", &v0, &v1, &opts);
+    validate_option_hash(opts, SB_KW_LSB_FIRST);
 
-    for (ssize_t i = 0; i < len; i++) {
-        unsigned char b = str[i];
-        if (lsb_first) {
-            for (int j = 0; j < 8; j++) {
-                VALUE bit = (b >> j) & 1 ? Qtrue : Qfalse;
-                have_block ? rb_yield(bit) : rb_ary_push(ary, bit);
-            }
-        } else {
-            for (int j = 7; j >= 0; j--) {
-                VALUE bit = (b >> j) & 1 ? Qtrue : Qfalse;
-                have_block ? rb_yield(bit) : rb_ary_push(ary, bit);
-            }
-        }
+    /* No positional args: count the whole string; lsb_first: is ignored (order-independent) */
+    if (NIL_P(v0))
+        return SSIZET2NUM(count_set_bits(str, src_len));
+
+    int lsb_first = parse_lsb_first_opt(opts);
+    int64_t total_bits = SB_BIT_LEN(src_len);
+    ssize_t bit_offset, bit_length;
+
+    if (rb_obj_is_kind_of(v0, rb_cRange)) {
+        if (!NIL_P(v1))
+            rb_raise(rb_eArgError, "wrong number of arguments");
+        sb_range_validate_endpoints(v0);
+        ssize_t beg, len;
+        if (!RTEST(sb_range_beg_len(v0, &beg, &len, total_bits, 0)))
+            return INT2FIX(0);
+        bit_offset = beg;
+        bit_length = len;
+    }
+    else if (!NIL_P(v1)) {
+        if (!rb_integer_type_p(v0))
+            rb_raise(rb_eTypeError, "bit_offset must be an integer");
+        if (!rb_integer_type_p(v1))
+            rb_raise(rb_eTypeError, "bit_length must be an integer");
+        bit_offset = integer_to_bit_idx(v0);
+        if (bit_offset < 0)
+            rb_raise(rb_eIndexError, "bit_offset must be non-negative");
+        bit_length = integer_to_bit_idx(v1);
+        if (bit_length < 0)
+            rb_raise(rb_eArgError, "bit_length must be non-negative");
+    }
+    else {
+        rb_raise(rb_eArgError,
+                 "wrong number of arguments (given 1, expected 0, 1 Range, or 2)");
     }
 
-    return have_block ? self : ary;
+    if (lsb_first)
+        return SSIZET2NUM(count_set_bits_range(str, src_len, bit_offset, bit_length));
+    else
+        return SSIZET2NUM(count_set_bits_range_msb(str, src_len, bit_offset, bit_length));
 }
 
-/* iterate set-bit positions ----------------------------------------------- */
+/* iterate bits ------------------------------------------------------------ */
 
-static VALUE
-rb_str_each_set_bit_offset(int argc, VALUE *argv, VALUE self)
+/* Unified emitter for each_bit / bits.
+ *
+ * Yields (when ary == Qnil) or pushes to a pre-allocated Array. lsb_first is
+ * hoisted outside the byte loop so the inner walk direction is straight-line
+ * code, removing a per-byte branch.
+ */
+static void
+emit_bits(const unsigned char *str, ssize_t len, int lsb_first, ssize_t start_offset, VALUE ary)
 {
-    RETURN_ENUMERATOR(self, argc, argv);
+    if (start_offset >= SB_BIT_LEN(len)) return;
+
+#define SB_EMIT(v) \
+    do { VALUE _b = (v); \
+         if (ary == Qnil) rb_yield(_b); else rb_ary_push(ary, _b); } while (0)
+
+    ssize_t byte_start = start_offset >> 3;
+    int bit_start = (int)(start_offset & 7);
 
-    int lsb_first = parse_lsb_first(argc, argv);
-    ssize_t len = RSTRING_LEN(self);
-    const unsigned char *str = (const unsigned char *)RSTRING_PTR(self);
     if (lsb_first) {
-        /* LSB-first: ascending positions 0, 1, 2, ...
-         * On little-endian, loading 8 bytes as a uint64_t preserves the flat
-         * LSB-first bit numbering: word bit 0 == position 0, bit 63 == 63.
-         * memcpy avoids unaligned-load SIGBUS on strict-alignment platforms. */
-#if SB_LITTLE_ENDIAN
-        ssize_t n_words = len >> 3;
-        for (ssize_t wi = 0; wi < n_words; wi++) {
-            uint64_t w;
-            memcpy(&w, str + wi * 8, 8);
-            while (w != 0) {
-                int bit = sb_ctzll(w);
-                rb_yield(SSIZET2NUM(wi * 64 + bit));
-                w &= w - 1;
+        for (ssize_t i = byte_start; i < len; i++) {
+            unsigned char b = str[i];
+            int j_start = (i == byte_start) ? bit_start : 0;
+            for (int j = j_start; j < 8; j++) {
+                SB_EMIT((b >> j) & 1 ? Qtrue : Qfalse);
             }
         }
-        for (ssize_t bi = n_words << 3; bi < len; bi++) {
-            unsigned int b = str[bi];
-            while (b != 0) {
-                int bit = sb_ctz8(b);
-                rb_yield(SSIZET2NUM(bi * 8 + bit));
-                b &= b - 1;
-            }
-        }
-#else
-        for (ssize_t bi = 0; bi < len; bi++) {
-            unsigned int b = str[bi];
-            while (b != 0) {
-                int bit = sb_ctz8(b);
-                rb_yield(SSIZET2NUM(bi * 8 + bit));
-                b &= b - 1;
-            }
-        }
-#endif
-    }
-    else {
-        /* lsb_first: false => byte order preserved, bits 7..0 map to logical 0..7 */
-        for (ssize_t bi = 0; bi < len; bi++) {
-            unsigned int b = str[bi];
-            while (b != 0) {
-                int bit = sb_highest_bit8(b);
-                ssize_t physical = bi * 8 + bit;
-                rb_yield(SSIZET2NUM(physical_to_count_from(physical, 0)));
-                b ^= (1u << bit);  /* clear highest set bit */
+    } else {
+        for (ssize_t i = byte_start; i < len; i++) {
+            unsigned char b = str[i];
+            int j_end = (i == byte_start) ? (7 - bit_start) : 7;
+            for (int j = j_end; j >= 0; j--) {
+                SB_EMIT((b >> j) & 1 ? Qtrue : Qfalse);
             }
         }
     }
 
+#undef SB_EMIT
+}
+
+static VALUE
+rb_str_each_bit(int argc, VALUE *argv, VALUE self)
+{
+    RETURN_ENUMERATOR(self, argc, argv);
+
+    VALUE start_offset_v = Qnil, opts = Qnil;
+    rb_scan_args(argc, argv, "01:", &start_offset_v, &opts);
+    validate_option_hash(opts, SB_KW_LSB_FIRST);
+    int lsb_first = parse_lsb_first_opt(opts);
+    ssize_t start_offset = parse_start_offset(start_offset_v);
+
+    emit_bits((const unsigned char *)RSTRING_PTR(self), RSTRING_LEN(self),
+              lsb_first, start_offset, Qnil);
     return self;
 }
 
 static VALUE
-rb_str_set_bit_offsets(int argc, VALUE *argv, VALUE self)
+rb_str_bits(int argc, VALUE *argv, VALUE self)
 {
-    int lsb_first = parse_lsb_first(argc, argv);
+    VALUE start_offset_v = Qnil, opts = Qnil;
+    rb_scan_args(argc, argv, "01:", &start_offset_v, &opts);
+    validate_option_hash(opts, SB_KW_LSB_FIRST);
+    int lsb_first = parse_lsb_first_opt(opts);
+    ssize_t start_offset = parse_start_offset(start_offset_v);
     ssize_t len = RSTRING_LEN(self);
     const unsigned char *str = (const unsigned char *)RSTRING_PTR(self);
-    int have_block = rb_block_given_p();
 
-    VALUE ary;
-    if (have_block) {
-        ary = Qnil;
-    }
-    else {
-        /* Pre-size the Array with popcount to avoid repeated reallocation.
-         * memcpy avoids unaligned-load issues on strict-alignment platforms. */
-        ssize_t count = 0;
-        ssize_t nw = len >> 3;
-        for (ssize_t wi = 0; wi < nw; wi++) {
-            uint64_t w;
-            memcpy(&w, str + wi * 8, 8);
-            count += sb_popcount64(w);
-        }
-        for (ssize_t bi = nw << 3; bi < len; bi++)
-            count += sb_popcount64((uint64_t)(unsigned char)str[bi]);
-        ary = rb_ary_new_capa(count);
+    if (rb_block_given_p()) {
+        emit_bits(str, len, lsb_first, start_offset, Qnil);
+        return self;
     }
 
+    int64_t total_bits = SB_BIT_LEN(len);
+    ssize_t nbits = (start_offset >= total_bits) ? 0 : (ssize_t)(total_bits - start_offset);
+    VALUE ary = rb_ary_new_capa(nbits);
+    emit_bits(str, len, lsb_first, start_offset, ary);
+    return ary;
+}
+
+/* iterate bit positions matching `bit` ------------------------------------ */
+
+/* parse the required `bit` argument (true/false/1/0) to 0 or 1 */
+static int
+parse_bit_target(VALUE bit_val)
+{
+    if (bit_val == Qtrue || bit_val == INT2FIX(1)) return 1;
+    if (bit_val == Qfalse || bit_val == INT2FIX(0)) return 0;
+    rb_raise(rb_eArgError, "bit must be 0, 1, false, or true");
+    UNREACHABLE_RETURN(0);
+}
+
+/* Unified scanner for each_bit_offset / bit_offsets.
+ *
+ * Emit each bit position equal to `target` either by yielding to the block
+ * (when ary == Qnil) or by pushing to the pre-allocated Array. Both call
+ * paths share the same hot loops; the only per-emit cost is one branch on
+ * (ary == Qnil), which the compiler can lift out of the inner while loop.
+ *
+ * LSB-first path: on little-endian, an 8-byte memcpy preserves the flat
+ * LSB-first bit numbering (word bit 0 == position 0), so we can scan 64 bits
+ * per ctzll. For target=0, invert the loaded word/byte; all 8/64 bits of the
+ * inverted unit are valid positions since each byte contributes exactly 8.
+ *
+ * MSB-first path: walk byte-by-byte with sb_highest_bit8, mapping each
+ * physical (LSB-first) bit position into the MSB-first count via
+ * logical_to_physical (the operation is its own inverse).
+ */
+static void
+emit_bit_offsets(const unsigned char *str, ssize_t len, int target, int lsb_first,
+                 ssize_t start_offset, VALUE ary)
+{
+    if (start_offset >= SB_BIT_LEN(len)) return;
+
+#define SB_EMIT(pos_val) \
+    do { VALUE _p = (pos_val); \
+         if (ary == Qnil) rb_yield(_p); else rb_ary_push(ary, _p); } while (0)
+
+    ssize_t byte_start = start_offset >> 3;
+    int bit_lo = (int)(start_offset & 7);
+
     if (lsb_first) {
+        /* Handle the partial first byte before aligning to byte boundary */
+        if (bit_lo != 0) {
+            unsigned int b = str[byte_start];
+            if (target == 0) b = (~b) & 0xFF;
+            b >>= bit_lo;
+            while (b != 0) {
+                int bit = sb_ctz8(b);
+                SB_EMIT(SSIZET2NUM(byte_start * 8 + bit_lo + bit));
+                b &= b - 1;
+            }
+            byte_start++;
+        }
 #if SB_LITTLE_ENDIAN
-        ssize_t n_words = len >> 3;
+        ssize_t n_words = (len - byte_start) >> 3;
         for (ssize_t wi = 0; wi < n_words; wi++) {
             uint64_t w;
-            memcpy(&w, str + wi * 8, 8);
+            memcpy(&w, str + byte_start + wi * 8, 8);
+            if (target == 0) w = ~w;
             while (w != 0) {
                 int bit = sb_ctzll(w);
-                VALUE pos = SSIZET2NUM(wi * 64 + bit);
-                have_block ? rb_yield(pos) : rb_ary_push(ary, pos);
+                SB_EMIT(SSIZET2NUM((byte_start + wi * 8) * 8 + bit));
                 w &= w - 1;
             }
         }
-        for (ssize_t bi = n_words << 3; bi < len; bi++) {
+        for (ssize_t bi = byte_start + (n_words << 3); bi < len; bi++) {
             unsigned int b = str[bi];
+            if (target == 0) b = (~b) & 0xFF;
             while (b != 0) {
                 int bit = sb_ctz8(b);
-                VALUE pos = SSIZET2NUM(bi * 8 + bit);
-                have_block ? rb_yield(pos) : rb_ary_push(ary, pos);
+                SB_EMIT(SSIZET2NUM(bi * 8 + bit));
                 b &= b - 1;
             }
         }
 #else
-        for (ssize_t bi = 0; bi < len; bi++) {
+        for (ssize_t bi = byte_start; bi < len; bi++) {
             unsigned int b = str[bi];
+            if (target == 0) b = (~b) & 0xFF;
             while (b != 0) {
                 int bit = sb_ctz8(b);
-                VALUE pos = SSIZET2NUM(bi * 8 + bit);
-                have_block ? rb_yield(pos) : rb_ary_push(ary, pos);
+                SB_EMIT(SSIZET2NUM(bi * 8 + bit));
                 b &= b - 1;
             }
         }
 #endif
     }
     else {
-        for (ssize_t bi = 0; bi < len; bi++) {
+        /* lsb_first: false => byte order preserved, bits 7..0 map to logical 0..7.
+         * In the first (possibly partial) byte, skip the top bit_lo bits. */
+        for (ssize_t bi = byte_start; bi < len; bi++) {
             unsigned int b = str[bi];
+            if (target == 0) b = (~b) & 0xFF;
+            if (bi == byte_start && bit_lo != 0)
+                b &= (1u << (8 - bit_lo)) - 1;  /* clear top bit_lo bits */
             while (b != 0) {
                 int bit = sb_highest_bit8(b);
                 ssize_t physical = bi * 8 + bit;
-                VALUE pos = SSIZET2NUM(physical_to_count_from(physical, 0));
-                have_block ? rb_yield(pos) : rb_ary_push(ary, pos);
+                SB_EMIT(SSIZET2NUM(logical_to_physical(physical, 0)));
                 b ^= (1u << bit);
             }
         }
     }
 
-    return have_block ? self : ary;
+#undef SB_EMIT
+}
+
+static VALUE
+rb_str_each_bit_offset(int argc, VALUE *argv, VALUE self)
+{
+    RETURN_ENUMERATOR(self, argc, argv);
+
+    VALUE bit_val, start_offset_v = Qnil, opts = Qnil;
+    rb_scan_args(argc, argv, "11:", &bit_val, &start_offset_v, &opts);
+    validate_option_hash(opts, SB_KW_LSB_FIRST);
+    int lsb_first = parse_lsb_first_opt(opts);
+    int target    = parse_bit_target(bit_val);
+    ssize_t start_offset = parse_start_offset(start_offset_v);
+
+    emit_bit_offsets((const unsigned char *)RSTRING_PTR(self), RSTRING_LEN(self),
+                     target, lsb_first, start_offset, Qnil);
+    return self;
+}
+
+static VALUE
+rb_str_bit_offsets(int argc, VALUE *argv, VALUE self)
+{
+    VALUE bit_val, start_offset_v = Qnil, opts = Qnil;
+    rb_scan_args(argc, argv, "11:", &bit_val, &start_offset_v, &opts);
+    validate_option_hash(opts, SB_KW_LSB_FIRST);
+    int lsb_first = parse_lsb_first_opt(opts);
+    int target    = parse_bit_target(bit_val);
+    ssize_t start_offset = parse_start_offset(start_offset_v);
+
+    ssize_t len = RSTRING_LEN(self);
+    const unsigned char *str = (const unsigned char *)RSTRING_PTR(self);
+
+    if (rb_block_given_p()) {
+        emit_bit_offsets(str, len, target, lsb_first, start_offset, Qnil);
+        return self;
+    }
+
+    /* Pre-size the Array using popcount to avoid repeated reallocation.
+     * For target=0 the expected count is (len * 8 - popcount). */
+    ssize_t set_count = count_set_bits(str, len);
+    ssize_t count     = (target == 1) ? set_count : (ssize_t)(SB_BIT_LEN(len) - set_count);
+    VALUE ary = rb_ary_new_capa(count);
+    emit_bit_offsets(str, len, target, lsb_first, start_offset, ary);
+    return ary;
 }
 
 /* multi-bit mutation ------------------------------------------------------ */
@@ -712,40 +934,36 @@ bit_copy_core(unsigned char *dst, ssize_t dst_bit_off,
     if (tmp != stack_tmp) ruby_xfree(tmp);
 }
 
-/* String#bit_slice(bit_offset, bit_length) -> String
- * String#bit_slice(range) -> String
- *
- *   str = "\xFF\x00" # 11111111 00000000
- *   str.bit_slice(4, 8) # => "\xF0" (11110000)
- */
+/* Extract a sub-sequence of bits into a new String. */
 static VALUE
 rb_str_bit_slice(int argc, VALUE *argv, VALUE self)
 {
     ssize_t src_len = RSTRING_LEN(self);
-    ssize_t total_bits = src_len * 8;
-    ssize_t offset, length;
+    int64_t total_bits = SB_BIT_LEN(src_len);
+    ssize_t bit_offset, bit_length;
     VALUE v0, v1, opts;
     int n_pos = rb_scan_args(argc, argv, "11:", &v0, &v1, &opts);
     validate_option_hash(opts, SB_KW_LSB_FIRST);
     int lsb_first = parse_lsb_first_opt(opts);
 
     if (n_pos == 1 && rb_obj_is_kind_of(v0, rb_cRange)) {
+        sb_range_validate_endpoints(v0);
         ssize_t beg, len;
         if (!RTEST(sb_range_beg_len(v0, &beg, &len, total_bits, 0))) {
             return Qnil;
         }
-        offset = beg;
-        length = len;
+        bit_offset = beg;
+        bit_length = len;
     }
     else if (n_pos == 2) {
         if (!rb_integer_type_p(v0) || !rb_integer_type_p(v1)) {
             return Qnil;
         }
 
-        offset = integer_to_bit_idx(v0);
-        length = integer_to_bit_idx(v1);
+        bit_offset = integer_to_bit_idx(v0);
+        bit_length = integer_to_bit_idx(v1);
 
-        if (offset < 0 || length < 0) return Qnil;
+        if (bit_offset < 0 || bit_length < 0) return Qnil;
     }
     else if (n_pos == 1) {
         return Qnil;
@@ -755,13 +973,13 @@ rb_str_bit_slice(int argc, VALUE *argv, VALUE self)
                  "wrong number of arguments (given %d, expected 1 or 2)", n_pos);
     }
 
-    if (offset > total_bits) return Qnil;
-    ssize_t available = total_bits - offset;
-    if (length > available) length = available;
+    if (bit_offset > total_bits) return Qnil;
+    int64_t available = total_bits - bit_offset;
+    if (bit_length > available) bit_length = (ssize_t)available;
 
-    if (length == 0) return rb_str_new("", 0);
+    if (bit_length == 0) return rb_str_new("", 0);
 
-    ssize_t out_bytes = (length + 7) / 8;
+    ssize_t out_bytes = (bit_length + 7) / 8;
     VALUE result = rb_str_buf_new(out_bytes);
     rb_str_resize(result, out_bytes);
     rb_enc_associate(result, rb_enc_get(self));
@@ -771,17 +989,17 @@ rb_str_bit_slice(int argc, VALUE *argv, VALUE self)
     memset(dst, 0, out_bytes);
 
     if (lsb_first) {
-        bit_copy_core(dst, 0, src, src_len, offset, length);
+        bit_copy_core(dst, 0, src, src_len, bit_offset, bit_length);
     } else {
         ssize_t dst_bit = 0;
-        ssize_t start_byte = offset >> 3;
-        ssize_t end_byte = (offset + length - 1) >> 3;
+        ssize_t start_byte = bit_offset >> 3;
+        ssize_t end_byte = (bit_offset + bit_length - 1) >> 3;
 
         for (ssize_t b = start_byte; b <= end_byte; b++) {
             ssize_t b_start_l = b << 3;
             ssize_t b_end_l = b_start_l + 7;
-            ssize_t l_min = (offset > b_start_l) ? offset : b_start_l;
-            ssize_t l_max = ((offset + length - 1) < b_end_l) ? (offset + length - 1) : b_end_l;
+            ssize_t l_min = (bit_offset > b_start_l) ? bit_offset : b_start_l;
+            ssize_t l_max = ((bit_offset + bit_length - 1) < b_end_l) ? (bit_offset + bit_length - 1) : b_end_l;
 
             ssize_t p_min = b_start_l + (7 - (l_max & 7L));
             ssize_t p_max = b_start_l + (7 - (l_min & 7L));
@@ -805,8 +1023,8 @@ enum sb_mutation_op {
 static VALUE
 rb_str_mutate_bits(int argc, VALUE *argv, VALUE self, enum sb_mutation_op op)
 {
-    VALUE target, opts;
-    rb_scan_args(argc, argv, "1:", &target, &opts);
+    VALUE target, bit_length_v = Qnil, opts = Qnil;
+    rb_scan_args(argc, argv, "11:", &target, &bit_length_v, &opts);
     validate_option_hash(opts, SB_KW_LSB_FIRST);
     int lsb_first = parse_lsb_first_opt(opts);
 
@@ -814,18 +1032,48 @@ rb_str_mutate_bits(int argc, VALUE *argv, VALUE self, enum sb_mutation_op op)
     unsigned char *ptr = (unsigned char *)RSTRING_PTR(self);
 
     if (rb_integer_type_p(target)) {
-        ssize_t idx = check_bit_index(self, target, lsb_first);
-        unsigned char mask = (unsigned char)(1u << (idx % 8));
-        switch (op) {
-          case SB_MUT_SET:   ptr[idx / 8] |= mask; break;
-          case SB_MUT_CLEAR: ptr[idx / 8] &= (unsigned char)~mask; break;
-          case SB_MUT_FLIP:  ptr[idx / 8] ^= mask; break;
+        if (NIL_P(bit_length_v)) {
+            /* Single-bit form: bit_set(n) */
+            ssize_t idx = check_bit_index(self, target, lsb_first);
+            unsigned char mask = (unsigned char)(1u << (idx % 8));
+            switch (op) {
+              case SB_MUT_SET:   ptr[idx / 8] |= mask; break;
+              case SB_MUT_CLEAR: ptr[idx / 8] &= (unsigned char)~mask; break;
+              case SB_MUT_FLIP:  ptr[idx / 8] ^= mask; break;
+            }
+            return self;
+        }
+        /* 2-arg form: bit_set(bit_offset, bit_length) */
+        if (!rb_integer_type_p(bit_length_v))
+            rb_raise(rb_eTypeError, "bit_length must be an integer");
+        ssize_t bit_offset = integer_to_bit_idx(target);
+        if (bit_offset < 0)
+            rb_raise(rb_eIndexError, "bit_offset must be non-negative");
+        ssize_t bit_length = integer_to_bit_idx(bit_length_v);
+        if (bit_length < 0)
+            rb_raise(rb_eArgError, "bit_length must be non-negative");
+        if (bit_length == 0) return self;
+        int64_t total_bits = SB_BIT_LEN(RSTRING_LEN(self));
+        if (bit_offset >= total_bits || bit_offset + bit_length > total_bits)
+            rb_raise(rb_eIndexError, "bit range out of range");
+        for (ssize_t logical = bit_offset; logical < bit_offset + bit_length; logical++) {
+            ssize_t idx = logical_to_physical(logical, lsb_first);
+            unsigned char mask = (unsigned char)(1u << (idx % 8));
+            switch (op) {
+              case SB_MUT_SET:   ptr[idx / 8] |= mask; break;
+              case SB_MUT_CLEAR: ptr[idx / 8] &= (unsigned char)~mask; break;
+              case SB_MUT_FLIP:  ptr[idx / 8] ^= mask; break;
+            }
         }
         return self;
     }
 
+    if (!NIL_P(bit_length_v))
+        rb_raise(rb_eArgError, "wrong number of arguments");
+
     if (rb_obj_is_kind_of(target, rb_cRange)) {
-        ssize_t total_bits = RSTRING_LEN(self) * 8;
+        sb_range_validate_endpoints(target);
+        int64_t total_bits = SB_BIT_LEN(RSTRING_LEN(self));
         ssize_t beg, len;
 
         /* err=0 returns Qnil for out-of-range begin (after negative normalization);
@@ -836,19 +1084,20 @@ rb_str_mutate_bits(int argc, VALUE *argv, VALUE self, enum sb_mutation_op op)
 
         /* err=0 silently clamps end > total. Detect that and raise instead,
          * to stay consistent with bit_splice and single-bit mutation. */
-        VALUE rng_end = rb_funcall(target, rb_intern("end"), 0);
-        if (!NIL_P(rng_end)) {
-            ssize_t end_val = integer_to_bit_idx(rng_end);
-            if (end_val < 0) end_val += total_bits;
-            int exclusive = RTEST(rb_funcall(target, rb_intern("exclude_end?"), 0));
-            ssize_t end_excl = exclusive ? end_val : end_val + 1;
+        VALUE rng_beg_unused, rng_end_v;
+        int excl;
+        rb_range_values(target, &rng_beg_unused, &rng_end_v, &excl);
+        (void)rng_beg_unused;
+        if (!NIL_P(rng_end_v)) {
+            ssize_t end_val = integer_to_bit_idx(rng_end_v);
+            ssize_t end_excl = excl ? end_val : end_val + 1;
             if (end_excl > total_bits) {
                 rb_raise(rb_eIndexError, "bit range out of range");
             }
         }
 
         for (ssize_t logical = beg; logical < beg + len; logical++) {
-            ssize_t idx = lsb_first ? logical : ((logical & ~7L) | (7 - (logical & 7L)));
+            ssize_t idx = logical_to_physical(logical, lsb_first);
             unsigned char mask = (unsigned char)(1u << (idx % 8));
             switch (op) {
               case SB_MUT_SET:   ptr[idx / 8] |= mask; break;
@@ -864,19 +1113,19 @@ rb_str_mutate_bits(int argc, VALUE *argv, VALUE self, enum sb_mutation_op op)
 }
 
 static VALUE
-rb_str_set_bit(int argc, VALUE *argv, VALUE self)
+rb_str_bit_set(int argc, VALUE *argv, VALUE self)
 {
     return rb_str_mutate_bits(argc, argv, self, SB_MUT_SET);
 }
 
 static VALUE
-rb_str_clear_bit(int argc, VALUE *argv, VALUE self)
+rb_str_bit_clear(int argc, VALUE *argv, VALUE self)
 {
     return rb_str_mutate_bits(argc, argv, self, SB_MUT_CLEAR);
 }
 
 static VALUE
-rb_str_flip_bit(int argc, VALUE *argv, VALUE self)
+rb_str_bit_flip(int argc, VALUE *argv, VALUE self)
 {
     return rb_str_mutate_bits(argc, argv, self, SB_MUT_FLIP);
 }
@@ -902,101 +1151,141 @@ alloc_result(VALUE self)
     return result;
 }
 
-static VALUE
-rb_str_bit_not(VALUE self)
-{
-    ssize_t len = RSTRING_LEN(self);
-    VALUE result = alloc_result(self);
-    const unsigned char *src = (const unsigned char *)RSTRING_PTR(self);
-    unsigned char *dst = (unsigned char *)RSTRING_PTR(result);
-    for (ssize_t i = 0; i < len; i++) dst[i] = ~src[i];
-    return result;
-}
-
-static VALUE
-rb_str_bit_not_bang(VALUE self)
-{
-    rb_str_modify(self);
-    ssize_t len = RSTRING_LEN(self);
-    unsigned char *ptr = (unsigned char *)RSTRING_PTR(self);
-    for (ssize_t i = 0; i < len; i++) ptr[i] = ~ptr[i];
-    return self;
-}
-
-static VALUE
-rb_str_bit_and(VALUE self, VALUE other)
-{
-    check_binary_op_lengths(self, other);
-    ssize_t len = RSTRING_LEN(self);
-    VALUE result = alloc_result(self);
-    const unsigned char *a = (const unsigned char *)RSTRING_PTR(self);
-    const unsigned char *b = (const unsigned char *)RSTRING_PTR(other);
-    unsigned char *dst = (unsigned char *)RSTRING_PTR(result);
-    for (ssize_t i = 0; i < len; i++) dst[i] = a[i] & b[i];
-    return result;
-}
-
-static VALUE
-rb_str_bit_and_bang(VALUE self, VALUE other)
-{
-    check_binary_op_lengths(self, other);
-    rb_str_modify(self);
-    ssize_t len = RSTRING_LEN(self);
-    unsigned char *a = (unsigned char *)RSTRING_PTR(self);
-    const unsigned char *b = (const unsigned char *)RSTRING_PTR(other);
-    for (ssize_t i = 0; i < len; i++) a[i] &= b[i];
-    return self;
-}
-
-static VALUE
-rb_str_bit_or(VALUE self, VALUE other)
-{
-    check_binary_op_lengths(self, other);
-    ssize_t len = RSTRING_LEN(self);
-    VALUE result = alloc_result(self);
-    const unsigned char *a = (const unsigned char *)RSTRING_PTR(self);
-    const unsigned char *b = (const unsigned char *)RSTRING_PTR(other);
-    unsigned char *dst = (unsigned char *)RSTRING_PTR(result);
-    for (ssize_t i = 0; i < len; i++) dst[i] = a[i] | b[i];
-    return result;
-}
-
-static VALUE
-rb_str_bit_or_bang(VALUE self, VALUE other)
-{
-    check_binary_op_lengths(self, other);
-    rb_str_modify(self);
-    ssize_t len = RSTRING_LEN(self);
-    unsigned char *a = (unsigned char *)RSTRING_PTR(self);
-    const unsigned char *b = (const unsigned char *)RSTRING_PTR(other);
-    for (ssize_t i = 0; i < len; i++) a[i] |= b[i];
-    return self;
-}
-
-static VALUE
-rb_str_bit_xor(VALUE self, VALUE other)
-{
-    check_binary_op_lengths(self, other);
-    ssize_t len = RSTRING_LEN(self);
-    VALUE result = alloc_result(self);
-    const unsigned char *a = (const unsigned char *)RSTRING_PTR(self);
-    const unsigned char *b = (const unsigned char *)RSTRING_PTR(other);
-    unsigned char *dst = (unsigned char *)RSTRING_PTR(result);
-    for (ssize_t i = 0; i < len; i++) dst[i] = a[i] ^ b[i];
-    return result;
-}
-
-static VALUE
-rb_str_bit_xor_bang(VALUE self, VALUE other)
-{
-    check_binary_op_lengths(self, other);
-    rb_str_modify(self);
-    ssize_t len = RSTRING_LEN(self);
-    unsigned char *a = (unsigned char *)RSTRING_PTR(self);
-    const unsigned char *b = (const unsigned char *)RSTRING_PTR(other);
-    for (ssize_t i = 0; i < len; i++) a[i] ^= b[i];
-    return self;
-}
+/*
+ * Bitwise op kernels: process 32 bytes (4 x uint64_t) per loop iteration via
+ * memcpy + word-wise op + memcpy, then any 8-byte tail, then byte-by-byte for
+ * the final < 8 bytes. memcpy avoids unaligned-load/store issues on strict-
+ * alignment platforms; modern compilers fold each 8-byte memcpy into a single
+ * load/store. Macro-generated to avoid 8 near-identical functions.
+ *
+ * NOT operands take only `src`; binary AND/OR/XOR take `a` and `b`.
+ */
+#define SB_DEFINE_UNARY_KERNEL(name, expr_word, expr_byte)            \
+    static void                                                       \
+    name(unsigned char *dst, const unsigned char *src, ssize_t len)   \
+    {                                                                 \
+        ssize_t off = 0;                                              \
+        ssize_t unrolled_end = len & ~31L;                            \
+        ssize_t aligned_end  = len & ~7L;                             \
+        for (; off < unrolled_end; off += 32) {                       \
+            uint64_t s0, s1, s2, s3;                                  \
+            memcpy(&s0, src + off,      8);                           \
+            memcpy(&s1, src + off + 8,  8);                           \
+            memcpy(&s2, src + off + 16, 8);                           \
+            memcpy(&s3, src + off + 24, 8);                           \
+            uint64_t d0 = (expr_word(s0));                            \
+            uint64_t d1 = (expr_word(s1));                            \
+            uint64_t d2 = (expr_word(s2));                            \
+            uint64_t d3 = (expr_word(s3));                            \
+            memcpy(dst + off,      &d0, 8);                           \
+            memcpy(dst + off + 8,  &d1, 8);                           \
+            memcpy(dst + off + 16, &d2, 8);                           \
+            memcpy(dst + off + 24, &d3, 8);                           \
+        }                                                             \
+        for (; off < aligned_end; off += 8) {                         \
+            uint64_t s;                                               \
+            memcpy(&s, src + off, 8);                                 \
+            uint64_t d = (expr_word(s));                              \
+            memcpy(dst + off, &d, 8);                                 \
+        }                                                             \
+        for (; off < len; off++) dst[off] = (expr_byte(src[off]));    \
+    }
+
+#define SB_DEFINE_BINARY_KERNEL(name, expr_word, expr_byte)                       \
+    static void                                                                   \
+    name(unsigned char *dst, const unsigned char *a, const unsigned char *b,      \
+         ssize_t len)                                                             \
+    {                                                                             \
+        ssize_t off = 0;                                                          \
+        ssize_t unrolled_end = len & ~31L;                                        \
+        ssize_t aligned_end  = len & ~7L;                                         \
+        for (; off < unrolled_end; off += 32) {                                   \
+            uint64_t a0, a1, a2, a3, b0, b1, b2, b3;                              \
+            memcpy(&a0, a + off,      8); memcpy(&b0, b + off,      8);           \
+            memcpy(&a1, a + off + 8,  8); memcpy(&b1, b + off + 8,  8);           \
+            memcpy(&a2, a + off + 16, 8); memcpy(&b2, b + off + 16, 8);           \
+            memcpy(&a3, a + off + 24, 8); memcpy(&b3, b + off + 24, 8);           \
+            uint64_t d0 = expr_word(a0, b0);                                      \
+            uint64_t d1 = expr_word(a1, b1);                                      \
+            uint64_t d2 = expr_word(a2, b2);                                      \
+            uint64_t d3 = expr_word(a3, b3);                                      \
+            memcpy(dst + off,      &d0, 8);                                       \
+            memcpy(dst + off + 8,  &d1, 8);                                       \
+            memcpy(dst + off + 16, &d2, 8);                                       \
+            memcpy(dst + off + 24, &d3, 8);                                       \
+        }                                                                         \
+        for (; off < aligned_end; off += 8) {                                     \
+            uint64_t av, bv;                                                      \
+            memcpy(&av, a + off, 8); memcpy(&bv, b + off, 8);                     \
+            uint64_t d = expr_word(av, bv);                                       \
+            memcpy(dst + off, &d, 8);                                             \
+        }                                                                         \
+        for (; off < len; off++) dst[off] = expr_byte(a[off], b[off]);            \
+    }
+
+#define SB_NOT_WORD(x)    (~(x))
+#define SB_NOT_BYTE(x)    ((unsigned char)~(x))
+#define SB_AND_WORD(x, y) ((x) & (y))
+#define SB_AND_BYTE(x, y) ((unsigned char)((x) & (y)))
+#define SB_OR_WORD(x, y)  ((x) | (y))
+#define SB_OR_BYTE(x, y)  ((unsigned char)((x) | (y)))
+#define SB_XOR_WORD(x, y) ((x) ^ (y))
+#define SB_XOR_BYTE(x, y) ((unsigned char)((x) ^ (y)))
+
+SB_DEFINE_UNARY_KERNEL (kern_not, SB_NOT_WORD, SB_NOT_BYTE)
+SB_DEFINE_BINARY_KERNEL(kern_and, SB_AND_WORD, SB_AND_BYTE)
+SB_DEFINE_BINARY_KERNEL(kern_or,  SB_OR_WORD,  SB_OR_BYTE)
+SB_DEFINE_BINARY_KERNEL(kern_xor, SB_XOR_WORD, SB_XOR_BYTE)
+
+/* Method wrappers: allocate-and-return form, and the in-place (!) form. */
+#define SB_DEFINE_UNARY_METHODS(op_name, kernel)                          \
+    static VALUE                                                          \
+    rb_str_bitwise_##op_name(VALUE self)                                  \
+    {                                                                     \
+        ssize_t len = RSTRING_LEN(self);                                  \
+        VALUE result = alloc_result(self);                                \
+        kernel((unsigned char *)RSTRING_PTR(result),                      \
+               (const unsigned char *)RSTRING_PTR(self), len);            \
+        return result;                                                    \
+    }                                                                     \
+    static VALUE                                                          \
+    rb_str_bitwise_##op_name##_bang(VALUE self)                           \
+    {                                                                     \
+        rb_str_modify(self);                                              \
+        ssize_t len = RSTRING_LEN(self);                                  \
+        unsigned char *ptr = (unsigned char *)RSTRING_PTR(self);          \
+        kernel(ptr, ptr, len);                                            \
+        return self;                                                      \
+    }
+
+#define SB_DEFINE_BINARY_METHODS(op_name, kernel)                         \
+    static VALUE                                                          \
+    rb_str_bitwise_##op_name(VALUE self, VALUE other)                     \
+    {                                                                     \
+        check_binary_op_lengths(self, other);                             \
+        ssize_t len = RSTRING_LEN(self);                                  \
+        VALUE result = alloc_result(self);                                \
+        kernel((unsigned char *)RSTRING_PTR(result),                      \
+               (const unsigned char *)RSTRING_PTR(self),                  \
+               (const unsigned char *)RSTRING_PTR(other), len);           \
+        return result;                                                    \
+    }                                                                     \
+    static VALUE                                                          \
+    rb_str_bitwise_##op_name##_bang(VALUE self, VALUE other)              \
+    {                                                                     \
+        check_binary_op_lengths(self, other);                             \
+        rb_str_modify(self);                                              \
+        ssize_t len = RSTRING_LEN(self);                                  \
+        unsigned char *a = (unsigned char *)RSTRING_PTR(self);            \
+        const unsigned char *b = (const unsigned char *)RSTRING_PTR(other); \
+        kernel(a, a, b, len);                                             \
+        return self;                                                      \
+    }
+
+SB_DEFINE_UNARY_METHODS (not, kern_not)
+SB_DEFINE_BINARY_METHODS(and, kern_and)
+SB_DEFINE_BINARY_METHODS(or,  kern_or)
+SB_DEFINE_BINARY_METHODS(xor, kern_xor)
 
 /* packed bit-field iteration ---------------------------------------------- */
 /*
@@ -1051,25 +1340,7 @@ extract_uint64(const unsigned char *src, ssize_t src_len,
     return val;
 }
 
-/* String#each_bit_field(*bitlens, lsb_first: true) -> self
- * String#each_bit_field(*bitlens, lsb_first: true) -> Enumerator
- *
- * Iterates over the string as a sequence of packed bit-field records. Each
- * positional argument specifies the width (in bits) of one field in the record.
- * On each iteration, one Integer per field is yielded (LSB-first bit layout).
- * Each bitlen must be in the range 1..64.
- *
- * lsb_first:   true (default)  -- intra-byte field extraction uses bit 0..7.
- * lsb_first:   false           -- intra-byte field extraction uses bit 7..0.
- *
- * Incomplete trailing bits (when bytesize*8 is not a multiple of sum(bitlens))
- * are silently dropped, matching the behavior of Enumerable#each_slice.
- *
- * Porting to Ruby Core:
- *   1. Move extract_uint64 and this function into string.c.
- *   2. Register with rb_define_method in Init_String().
- *   3. Replace ALLOCA_N with stack arrays for small field counts and heap otherwise.
- */
+/* Yield each packed bit-field record as one Integer per field. */
 static VALUE
 rb_str_each_bit_field(int argc, VALUE *argv, VALUE self)
 {
@@ -1096,7 +1367,7 @@ rb_str_each_bit_field(int argc, VALUE *argv, VALUE self)
             rb_raise(rb_eArgError, "bitlen must be positive");
         }
         if (bl > 64) {
-            rb_raise(rb_eArgError, "bitlen must be <= 64 (got %ld)", bl);
+            rb_raise(rb_eArgError, "bitlen must be <= 64 (got %" PRIdPTR ")", (intptr_t)bl);
         }
         bitlens[f] = bl;
         step += bl;
@@ -1105,8 +1376,8 @@ rb_str_each_bit_field(int argc, VALUE *argv, VALUE self)
     int lsb_first = parse_lsb_first_opt(opts);
 
     ssize_t src_len = RSTRING_LEN(self);
-    ssize_t total_bits = src_len * 8;
-    ssize_t iterations = total_bits / step;
+    int64_t total_bits = SB_BIT_LEN(src_len);
+    ssize_t iterations = (ssize_t)(total_bits / step);
 
     VALUE *field_vals = ALLOCA_N(VALUE, num_fields);
 
@@ -1125,22 +1396,7 @@ rb_str_each_bit_field(int argc, VALUE *argv, VALUE self)
     return self;
 }
 
-/* String#bit_fields(*bitlens, lsb_first: true) -> Array
- * String#bit_fields(*bitlens, lsb_first: true) { |*fields| } -> self
- *
- * Non-iterator complement of each_bit_field.  Without a block, returns an
- * Array of all extracted records.  With a single bitlen the array is flat
- * (matching each_bit_field(n).to_a); with multiple bitlens each record is
- * itself an Array (matching each_bit_field(a, b, ...).to_a).
- *
- * With a block, behaves identically to each_bit_field without with: ---
- * yielding one Integer per field and returning self.
- *
- * Porting to Ruby Core:
- *   1. Move alongside each_bit_field in string.c.
- *   2. Share extract_uint64 and the bitlen validation logic.
- *   3. Register with rb_define_method in Init_String().
- */
+/* Non-iterator form of each_bit_field; collect bit-field records into an Array. */
 static VALUE
 rb_str_bit_fields(int argc, VALUE *argv, VALUE self)
 {
@@ -1165,7 +1421,7 @@ rb_str_bit_fields(int argc, VALUE *argv, VALUE self)
             rb_raise(rb_eArgError, "bitlen must be positive");
         }
         if (bl > 64) {
-            rb_raise(rb_eArgError, "bitlen must be <= 64 (got %ld)", bl);
+            rb_raise(rb_eArgError, "bitlen must be <= 64 (got %" PRIdPTR ")", (intptr_t)bl);
         }
         bitlens[f] = bl;
         step += bl;
@@ -1174,8 +1430,8 @@ rb_str_bit_fields(int argc, VALUE *argv, VALUE self)
     int lsb_first = parse_lsb_first_opt(opts);
 
     ssize_t src_len = RSTRING_LEN(self);
-    ssize_t total_bits = src_len * 8;
-    ssize_t iterations = total_bits / step;
+    int64_t total_bits = SB_BIT_LEN(src_len);
+    ssize_t iterations = (ssize_t)(total_bits / step);
 
     int have_block = rb_block_given_p();
     VALUE result = have_block ? Qnil : rb_ary_new_capa(iterations);
@@ -1207,7 +1463,7 @@ rb_str_bit_fields(int argc, VALUE *argv, VALUE self)
 
 /*
  * count_run_lsb: count consecutive bits equal to `target` starting at flat
- * position `pos` (LSB-first).  Uses ctz / ctzll to skip bits in bulk:
+ * position `bit_offset` (LSB-first).  Uses ctz / ctzll to skip bits in bulk:
  *   - partial first byte: ctz on the inverted masked nibble
  *   - full 64-bit words (LE): ctzll on the inverted word (64 bits per step)
  *   - remaining bytes: ctz on the inverted byte
@@ -1217,11 +1473,11 @@ rb_str_bit_fields(int argc, VALUE *argv, VALUE self)
  *   2. Share sb_ctz8 / sb_ctzll with the existing set-bit helpers.
  */
 static ssize_t
-count_run_lsb(const unsigned char *src, ssize_t src_len, ssize_t pos, int target)
+count_run_lsb(const unsigned char *src, ssize_t src_len, ssize_t bit_offset, int target)
 {
-    ssize_t max_run  = src_len * 8 - pos;
-    ssize_t byte_idx = pos >> 3;
-    int  bit_off  = pos & 7;
+    int64_t max_run  = SB_BIT_LEN(src_len) - bit_offset;
+    ssize_t byte_idx = bit_offset >> 3;
+    int  bit_off  = bit_offset & 7;
     ssize_t count    = 0;
 
     /* partial first byte: shift pos to bit 0, mask remaining bits */
@@ -1236,7 +1492,7 @@ count_run_lsb(const unsigned char *src, ssize_t src_len, ssize_t pos, int target
         count                 += run;
         byte_idx++;
         if (run < remaining)
-            return count < max_run ? count : max_run;
+            return (ssize_t)(count < max_run ? count : max_run);
     }
 
 #if SB_LITTLE_ENDIAN
@@ -1250,7 +1506,7 @@ count_run_lsb(const unsigned char *src, ssize_t src_len, ssize_t pos, int target
             byte_idx += 8;
         } else {
             count += sb_ctzll(~word);
-            return count < max_run ? count : max_run;
+            return (ssize_t)(count < max_run ? count : max_run);
         }
     }
 #endif
@@ -1265,218 +1521,146 @@ count_run_lsb(const unsigned char *src, ssize_t src_len, ssize_t pos, int target
             byte_idx++;
         } else {
             count += sb_ctz8(~b);
-            return count < max_run ? count : max_run;
+            return (ssize_t)(count < max_run ? count : max_run);
         }
     }
 
-    return count < max_run ? count : max_run;
+    return (ssize_t)(count < max_run ? count : max_run);
 }
 
-/* String#bit_run_count(pos, bit) -> Integer | nil
- *
- * Returns the length of the consecutive run of `bit` starting at flat
- * position `pos`.  Returns nil when `pos` is out of range or the bit at `pos`
- * does not equal `bit`.
- *
- * `bit` accepts 0, 1, false, or true (false/true are aliases for 0/1,
- * matching the values yielded by each_bit_run).
- *
- * Counts forward from `pos` toward higher bit indices.
- *
- * Inspired by Gauche Scheme's (bitvector-count-run bit bvec i).
- *
- * Uses the same flat LSB-first addressing as bit_at: byte[pos/8] bit pos%8.
- *
- * Porting to Ruby Core:
- *   1. Move to string.c; register in Init_String().
- *   2. Reuse integer_to_bit_idx for consistent Bignum handling.
- */
+/* Return the length of the consecutive run of `bit` starting at pos, or nil. */
 static VALUE
 rb_str_bit_run_count(int argc, VALUE *argv, VALUE self)
 {
-    VALUE pos_val, bit_val, opts;
-    rb_scan_args(argc, argv, "20:", &pos_val, &bit_val, &opts);
+    VALUE bit_offset_v, bit_val, opts;
+    rb_scan_args(argc, argv, "20:", &bit_val, &bit_offset_v, &opts);
     validate_option_hash(opts, SB_KW_LSB_FIRST);
     int lsb_first = parse_lsb_first_opt(opts);
 
-    if (!rb_integer_type_p(pos_val)) {
+    if (!rb_integer_type_p(bit_offset_v)) {
         rb_raise(rb_eTypeError, "position must be an integer");
     }
-    int target;
-    if (bit_val == Qtrue || bit_val == INT2FIX(1)) {
-        target = 1;
-    } else if (bit_val == Qfalse || bit_val == INT2FIX(0)) {
-        target = 0;
-    } else {
-        rb_raise(rb_eArgError, "bit must be 0, 1, false, or true");
-    }
-    ssize_t pos     = integer_to_bit_idx(pos_val);
+    int target = parse_bit_target(bit_val);
+    ssize_t bit_offset = integer_to_bit_idx(bit_offset_v);
     ssize_t src_len = RSTRING_LEN(self);
-    if (pos < 0 || pos >= src_len * 8) return Qnil;
+    if (bit_offset < 0 || bit_offset >= SB_BIT_LEN(src_len)) return Qnil;
 
     const unsigned char *src = (const unsigned char *)RSTRING_PTR(self);
     if (lsb_first) {
-        if (((src[pos >> 3] >> (pos & 7)) & 1) != target) return Qnil;
-        return SSIZET2NUM(count_run_lsb(src, src_len, pos, target));
+        if (((src[bit_offset >> 3] >> (bit_offset & 7)) & 1) != target) return Qnil;
+        return SSIZET2NUM(count_run_lsb(src, src_len, bit_offset, target));
     }
 
-    if (logical_get_bit(src, pos, 0) != target) return Qnil;
+    if (logical_get_bit(src, bit_offset, 0) != target) return Qnil;
 
     ssize_t run = 1;
-    ssize_t total_bits = src_len * 8;
-    while (pos + run < total_bits && logical_get_bit(src, pos + run, 0) == target) {
+    int64_t total_bits = SB_BIT_LEN(src_len);
+    while (bit_offset + run < total_bits && logical_get_bit(src, bit_offset + run, 0) == target) {
         run++;
     }
     return SSIZET2NUM(run);
 }
 
-/* String#each_bit_run(lsb_first: true) { |bit, len| } -> self
- * String#each_bit_run(lsb_first: true) -> Enumerator
- *
- * Yields (bit, run_length) pairs for each consecutive run of identical bits.
- * Run-length boundary detection and counting happen entirely in C, replacing
- * the Ruby-level current/count state machine required when using each_bit.
+/* Yield (bit, offset, run_length) triples for each consecutive run of identical bits. */
+/* Unified emitter for each_bit_run / bit_runs.
  *
- * For random data (~50% density) each_bit_run yields ~half as many times as
- * each_bit.  For structured data (sparse validity bitmaps, sensor bursts) the
- * ratio is proportional to the average run length.
+ * Walks the bitmap in (bit, run_length) chunks. Yields each pair (when
+ * ary == Qnil) or pushes (bit, run_length) Arrays to the pre-allocated
+ * result. The LSB-first path uses the fast count_run_lsb (word-at-a-time
+ * via ctzll); the MSB-first path scans bit by bit through logical_get_bit.
  *
- * lsb_first: true (default) iterates bit 0..7 within each byte.
- * lsb_first: false iterates bit 7..0 within each byte.
- *
- * Porting to Ruby Core:
- *   1. Move to string.c; register in Init_String().
- *   2. count_run_lsb / count_run_msb move with it.
+ * self is re-read inside the loop because rb_yield can invoke Ruby code
+ * that mutates the receiver, potentially invalidating RSTRING_PTR.
  */
-static VALUE
-rb_str_each_bit_run(int argc, VALUE *argv, VALUE self)
+static void
+emit_bit_runs(VALUE self, int lsb_first, ssize_t start_offset, VALUE ary)
 {
-    RETURN_ENUMERATOR(self, argc, argv);
-
-    int lsb_first = parse_lsb_first(argc, argv);
-    ssize_t src_len  = RSTRING_LEN(self);
-    if (src_len == 0) return self;
+    ssize_t src_len    = RSTRING_LEN(self);
+    int64_t total_bits = SB_BIT_LEN(src_len);
+    if (src_len == 0 || start_offset >= total_bits) return;
+    ssize_t offset     = start_offset;
 
-    ssize_t total_bits = src_len * 8;
+#define SB_EMIT_TRIPLE(bval, oval, lval) \
+    do { if (ary == Qnil) rb_yield_values(3, (bval), (oval), (lval)); \
+         else rb_ary_push(ary, rb_ary_new3(3, (bval), (oval), (lval))); } while (0)
 
     if (lsb_first) {
-        ssize_t pos = 0;
-        while (pos < total_bits) {
+        while (offset < total_bits) {
             const unsigned char *src = (const unsigned char *)RSTRING_PTR(self);
-            int bit  = (src[pos >> 3] >> (pos & 7)) & 1;
-            ssize_t run = count_run_lsb(src, src_len, pos, bit);
-            rb_yield_values(2, bit ? Qtrue : Qfalse, SSIZET2NUM(run));
-            pos += run;
+            int bit = (src[offset >> 3] >> (offset & 7)) & 1;
+            ssize_t run = count_run_lsb(src, src_len, offset, bit);
+            SB_EMIT_TRIPLE(bit ? Qtrue : Qfalse, SSIZET2NUM(offset), SSIZET2NUM(run));
+            offset += run;
         }
     }
     else {
-        ssize_t pos = 0;
-        while (pos < total_bits) {
+        while (offset < total_bits) {
             const unsigned char *src = (const unsigned char *)RSTRING_PTR(self);
-            int bit = logical_get_bit(src, pos, 0);
+            int bit = logical_get_bit(src, offset, 0);
             ssize_t run = 1;
-            while (pos + run < total_bits && logical_get_bit(src, pos + run, 0) == bit) {
+            while (offset + run < total_bits && logical_get_bit(src, offset + run, 0) == bit) {
                 run++;
             }
-            rb_yield_values(2, bit ? Qtrue : Qfalse, SSIZET2NUM(run));
-            pos += run;
+            SB_EMIT_TRIPLE(bit ? Qtrue : Qfalse, SSIZET2NUM(offset), SSIZET2NUM(run));
+            offset += run;
         }
     }
 
-    return self;
+#undef SB_EMIT_TRIPLE
 }
 
-/* String#bit_runs(lsb_first: true) -> Array
- * String#bit_runs(lsb_first: true) { |bit, len| } -> self
- *
- * Non-iterator complement of each_bit_run. Without a block, collects all
- * (bit, run_length) pairs into an Array and returns it. With a block,
- * yields each pair and returns self.
- *
- * Follows the same pattern as String#bytes vs String#each_byte.
- *
- * Porting to Ruby Core:
- *   1. Move to string.c alongside each_bit_run; register in Init_String().
- */
 static VALUE
-rb_str_bit_runs(int argc, VALUE *argv, VALUE self)
+rb_str_each_bit_run(int argc, VALUE *argv, VALUE self)
 {
-    int lsb_first = parse_lsb_first(argc, argv);
-    ssize_t src_len   = RSTRING_LEN(self);
-    int have_block = rb_block_given_p();
+    RETURN_ENUMERATOR(self, argc, argv);
 
-    if (src_len == 0) return have_block ? self : rb_ary_new();
+    VALUE start_offset_v = Qnil, opts = Qnil;
+    rb_scan_args(argc, argv, "01:", &start_offset_v, &opts);
+    validate_option_hash(opts, SB_KW_LSB_FIRST);
+    int lsb_first = parse_lsb_first_opt(opts);
+    ssize_t start_offset = parse_start_offset(start_offset_v);
 
-    ssize_t total_bits = src_len * 8;
-    VALUE result    = have_block ? Qnil : rb_ary_new();
+    emit_bit_runs(self, lsb_first, start_offset, Qnil);
+    return self;
+}
 
-    if (lsb_first) {
-        ssize_t pos = 0;
-        while (pos < total_bits) {
-            const unsigned char *src = (const unsigned char *)RSTRING_PTR(self);
-            int bit  = (src[pos >> 3] >> (pos & 7)) & 1;
-            ssize_t run = count_run_lsb(src, src_len, pos, bit);
-            VALUE bval = bit ? Qtrue : Qfalse;
-            VALUE lval = SSIZET2NUM(run);
-            have_block ? rb_yield_values(2, bval, lval)
-                       : rb_ary_push(result, rb_assoc_new(bval, lval));
-            pos += run;
-        }
-    } else {
-        ssize_t pos = 0;
-        while (pos < total_bits) {
-            const unsigned char *src = (const unsigned char *)RSTRING_PTR(self);
-            int bit = logical_get_bit(src, pos, 0);
-            ssize_t run = 1;
-            while (pos + run < total_bits && logical_get_bit(src, pos + run, 0) == bit) {
-                run++;
-            }
-            VALUE bval = bit ? Qtrue : Qfalse;
-            VALUE lval = SSIZET2NUM(run);
-            have_block ? rb_yield_values(2, bval, lval)
-                       : rb_ary_push(result, rb_assoc_new(bval, lval));
-            pos += run;
-        }
+/* Non-iterator form of each_bit_run; collect run triples into an Array. */
+static VALUE
+rb_str_bit_runs(int argc, VALUE *argv, VALUE self)
+{
+    VALUE start_offset_v = Qnil, opts = Qnil;
+    rb_scan_args(argc, argv, "01:", &start_offset_v, &opts);
+    validate_option_hash(opts, SB_KW_LSB_FIRST);
+    int lsb_first = parse_lsb_first_opt(opts);
+    ssize_t start_offset = parse_start_offset(start_offset_v);
+
+    if (rb_block_given_p()) {
+        emit_bit_runs(self, lsb_first, start_offset, Qnil);
+        return self;
     }
 
-    return have_block ? self : result;
+    VALUE ary = rb_ary_new();
+    emit_bit_runs(self, lsb_first, start_offset, ary);
+    return ary;
 }
 
-/* String#bit_splice(bit_index, bit_length, str) -> self
- * String#bit_splice(bit_index, bit_length, str, str_bit_index, str_bit_length) -> self
- * String#bit_splice(range, str) -> self
- * String#bit_splice(range, str, str_range) -> self
- *
- * Writes bits from str into self at bit-level granularity.  The inverse of
- * bit_slice: where bit_slice reads a sub-sequence of bits, bit_splice writes one.
- *
- * The destination and source bit lengths must be equal; bit_splice does not
- * resize self (sub-byte resize is undefined).  This mirrors the constraint that
- * bytesplice imposes when the replacement has the same byte length.
- *
- * Negative indices count backward from the end, exactly as in bytesplice.
- * Returns self.
- *
- * Porting to Ruby Core:
- *   1. Move to string.c; register in Init_String().
- *   2. Use rb_str_modify_expand if resize support is ever added.
- *   3. bit_copy_core moves with it; share ebs_extract with bit_slice.
- */
+/* Write bits from str into self at bit-level granularity (inverse of bit_slice). */
 static VALUE
 rb_str_bit_splice(int argc, VALUE *argv, VALUE self)
 {
     ssize_t dst_bit_off, dst_bit_len;
     ssize_t src_bit_off, src_bit_len;
     VALUE str;
-    ssize_t dst_total = RSTRING_LEN(self) * 8;
-    VALUE v0, v1, v2, v3, v4, opts;
+    int64_t dst_total = SB_BIT_LEN(RSTRING_LEN(self));
+    VALUE v0, v1, v2, v3, opts;
 
-    int n_pos = rb_scan_args(argc, argv, "23:", &v0, &v1, &v2, &v3, &v4, &opts);
+    int n_pos = rb_scan_args(argc, argv, "22:", &v0, &v1, &v2, &v3, &opts);
     validate_option_hash(opts, SB_KW_LSB_FIRST);
     int lsb_first = parse_lsb_first_opt(opts);
 
     if (n_pos == 2 && rb_obj_is_kind_of(v0, rb_cRange)) {
         /* bit_splice(range, str) */
+        sb_range_validate_endpoints(v0);
         ssize_t beg, len;
         sb_range_beg_len(v0, &beg, &len, dst_total, 1);
         dst_bit_off = beg;
@@ -1487,20 +1671,21 @@ rb_str_bit_splice(int argc, VALUE *argv, VALUE self)
         src_bit_len = dst_bit_len;
     }
     else if (n_pos == 3 && rb_obj_is_kind_of(v0, rb_cRange)) {
-        /* bit_splice(range, str, str_range) */
+        /* bit_splice(range, str, str_bit_index) */
+        sb_range_validate_endpoints(v0);
         ssize_t beg, len;
         sb_range_beg_len(v0, &beg, &len, dst_total, 1);
         dst_bit_off = beg;
         dst_bit_len = len;
         str = v1;
         Check_Type(str, T_STRING);
-        if (!rb_obj_is_kind_of(v2, rb_cRange)) {
-            rb_raise(rb_eTypeError, "third argument must be a Range");
+        if (!rb_integer_type_p(v2)) {
+            rb_raise(rb_eTypeError, "third argument must be an Integer");
         }
-        ssize_t src_total = RSTRING_LEN(str) * 8;
-        sb_range_beg_len(v2, &beg, &len, src_total, 1);
-        src_bit_off = beg;
-        src_bit_len = len;
+        int64_t src_total = SB_BIT_LEN(RSTRING_LEN(str));
+        src_bit_off = integer_to_bit_idx(v2);
+        if (src_bit_off < 0) src_bit_off += src_total;
+        src_bit_len = dst_bit_len;
     }
     else if (n_pos == 3) {
         /* bit_splice(bit_index, bit_length, str) */
@@ -1526,10 +1711,9 @@ rb_str_bit_splice(int argc, VALUE *argv, VALUE self)
         src_bit_off = 0;
         src_bit_len = dst_bit_len;
     }
-    else if (n_pos == 5) {
-        /* bit_splice(bit_index, bit_length, str, str_bit_index, str_bit_length) */
-        if (!rb_integer_type_p(v0) || !rb_integer_type_p(v1) ||
-            !rb_integer_type_p(v3) || !rb_integer_type_p(v4)) {
+    else if (n_pos == 4) {
+        /* bit_splice(bit_index, bit_length, str, str_bit_index) */
+        if (!rb_integer_type_p(v0) || !rb_integer_type_p(v1) || !rb_integer_type_p(v3)) {
             rb_raise(rb_eTypeError, "bit indices and lengths must be integers");
         }
         dst_bit_off = integer_to_bit_idx(v0);
@@ -1537,33 +1721,29 @@ rb_str_bit_splice(int argc, VALUE *argv, VALUE self)
         if (dst_bit_off < 0) dst_bit_off += dst_total;
         str = v2;
         Check_Type(str, T_STRING);
-        ssize_t src_total = RSTRING_LEN(str) * 8;
+        int64_t src_total = SB_BIT_LEN(RSTRING_LEN(str));
         src_bit_off = integer_to_bit_idx(v3);
-        src_bit_len = integer_to_bit_idx(v4);
         if (src_bit_off < 0) src_bit_off += src_total;
+        src_bit_len = dst_bit_len;
     }
     else {
         rb_raise(rb_eArgError,
-                 "wrong number of arguments (given %d, expected 2, 3, or 5)", n_pos);
+                 "wrong number of arguments (given %d, expected 2, 3, or 4)", n_pos);
     }
 
     if (dst_bit_off < 0 || dst_bit_len < 0 || dst_bit_off + dst_bit_len > dst_total) {
         rb_raise(rb_eIndexError,
-                 "bit_splice: destination range [%ld, %ld] out of bounds (total %ld bits)",
-                 dst_bit_off, dst_bit_len, dst_total);
+                 "bit_splice: destination range [%" PRIdPTR ", %" PRIdPTR
+                 "] out of bounds (total %" PRId64 " bits)",
+                 (intptr_t)dst_bit_off, (intptr_t)dst_bit_len, (int64_t)dst_total);
     }
 
-    ssize_t src_total_bits = RSTRING_LEN(str) * 8;
+    int64_t src_total_bits = SB_BIT_LEN(RSTRING_LEN(str));
     if (src_bit_off < 0 || src_bit_len < 0 || src_bit_off + src_bit_len > src_total_bits) {
         rb_raise(rb_eIndexError,
-                 "bit_splice: source range [%ld, %ld] out of bounds (total %ld bits)",
-                 src_bit_off, src_bit_len, src_total_bits);
-    }
-
-    if (dst_bit_len != src_bit_len) {
-        rb_raise(rb_eArgError,
-                 "bit_splice: destination length (%ld) must equal source length (%ld)",
-                 dst_bit_len, src_bit_len);
+                 "bit_splice: source range [%" PRIdPTR ", %" PRIdPTR
+                 "] out of bounds (total %" PRId64 " bits)",
+                 (intptr_t)src_bit_off, (intptr_t)src_bit_len, (int64_t)src_total_bits);
     }
 
     if (dst_bit_len == 0) return self;
@@ -1693,8 +1873,9 @@ rb_ary_mask(int argc, VALUE *argv, VALUE self)
         ssize_t needed     = (ary_len + 7) >> 3;
         if (needed > bmp_len)
             rb_raise(rb_eArgError,
-                     "bitmap too short: need %ld bytes for %ld elements, got %ld",
-                     needed, ary_len, bmp_len);
+                     "bitmap too short: need %" PRIdPTR " bytes for %" PRIdPTR
+                     " elements, got %" PRIdPTR,
+                     (intptr_t)needed, (intptr_t)ary_len, (intptr_t)bmp_len);
 
         if (!lsb_first) {
             for (ssize_t i = 0; i < ary_len; i++) {
@@ -1738,8 +1919,9 @@ rb_ary_mask_bang(int argc, VALUE *argv, VALUE self)
         ssize_t needed     = (ary_len + 7) >> 3;
         if (needed > bmp_len)
             rb_raise(rb_eArgError,
-                     "bitmap too short: need %ld bytes for %ld elements, got %ld",
-                     needed, ary_len, bmp_len);
+                     "bitmap too short: need %" PRIdPTR " bytes for %" PRIdPTR
+                     " elements, got %" PRIdPTR,
+                     (intptr_t)needed, (intptr_t)ary_len, (intptr_t)bmp_len);
 
         if (!lsb_first) {
             for (ssize_t i = 0; i < ary_len; i++) {
@@ -1765,38 +1947,36 @@ rb_ary_mask_bang(int argc, VALUE *argv, VALUE self)
 void
 Init_string_bits(void)
 {
-    id_bracket = rb_intern("[]");
-    sym_lsb_first   = ID2SYM(rb_intern("lsb_first"));
-    sym_lsb         = ID2SYM(rb_intern("lsb"));
-    sym_msb         = ID2SYM(rb_intern("msb"));
-    sym_invert      = ID2SYM(rb_intern("invert"));
-
-    rb_define_method(rb_cString, "bit_at",            rb_str_bit_at,           -1);
-    rb_define_method(rb_cString, "bit_count",         rb_str_bit_count,         0);
-    rb_define_method(rb_cString, "each_bit",          rb_str_each_bit,         -1);
-    rb_define_method(rb_cString, "bits",              rb_str_bits,             -1);
-    rb_define_method(rb_cString, "each_set_bit_offset", rb_str_each_set_bit_offset, -1);
-    rb_define_method(rb_cString, "set_bit_offsets",   rb_str_set_bit_offsets,  -1);
-    rb_define_method(rb_cString, "bit_slice",         rb_str_bit_slice,        -1);
-    rb_define_method(rb_cString, "bit_splice",        rb_str_bit_splice,       -1);
-    rb_define_method(rb_cString, "bit_run_count",     rb_str_bit_run_count,    -1);
-    rb_define_method(rb_cString, "each_bit_run",      rb_str_each_bit_run,     -1);
-    rb_define_method(rb_cString, "bit_runs",          rb_str_bit_runs,         -1);
-    rb_define_method(rb_cString, "set_bit",           rb_str_set_bit,          -1);
-    rb_define_method(rb_cString, "clear_bit",         rb_str_clear_bit,        -1);
-    rb_define_method(rb_cString, "flip_bit",          rb_str_flip_bit,         -1);
-    rb_define_method(rb_cString, "bit_not",           rb_str_bit_not,           0);
-    rb_define_method(rb_cString, "bit_not!",          rb_str_bit_not_bang,      0);
-    rb_define_method(rb_cString, "bit_and",           rb_str_bit_and,           1);
-    rb_define_method(rb_cString, "bit_and!",          rb_str_bit_and_bang,      1);
-    rb_define_method(rb_cString, "bit_or",            rb_str_bit_or,            1);
-    rb_define_method(rb_cString, "bit_or!",           rb_str_bit_or_bang,       1);
-    rb_define_method(rb_cString, "bit_xor",           rb_str_bit_xor,           1);
-    rb_define_method(rb_cString, "bit_xor!",          rb_str_bit_xor_bang,      1);
+    id_bracket    = rb_intern("[]");
+    sym_lsb_first = ID2SYM(rb_intern("lsb_first"));
+    sym_invert    = ID2SYM(rb_intern("invert"));
+
+    rb_define_method(rb_cString, "bit_at",          rb_str_bit_at,           -1);
+    rb_define_method(rb_cString, "bit_count",       rb_str_bit_count,        -1);
+    rb_define_method(rb_cString, "each_bit",        rb_str_each_bit,         -1);
+    rb_define_method(rb_cString, "bits",            rb_str_bits,             -1);
+    rb_define_method(rb_cString, "each_bit_offset", rb_str_each_bit_offset,  -1);
+    rb_define_method(rb_cString, "bit_offsets",     rb_str_bit_offsets,      -1);
+    rb_define_method(rb_cString, "bit_slice",       rb_str_bit_slice,        -1);
+    rb_define_method(rb_cString, "bit_splice",      rb_str_bit_splice,       -1);
+    rb_define_method(rb_cString, "bit_run_count",   rb_str_bit_run_count,    -1);
+    rb_define_method(rb_cString, "each_bit_run",    rb_str_each_bit_run,     -1);
+    rb_define_method(rb_cString, "bit_runs",        rb_str_bit_runs,         -1);
+    rb_define_method(rb_cString, "bit_set",         rb_str_bit_set,          -1);
+    rb_define_method(rb_cString, "bit_clear",       rb_str_bit_clear,        -1);
+    rb_define_method(rb_cString, "bit_flip",        rb_str_bit_flip,         -1);
+    rb_define_method(rb_cString, "bitwise_not",     rb_str_bitwise_not,       0);
+    rb_define_method(rb_cString, "bitwise_not!",    rb_str_bitwise_not_bang,  0);
+    rb_define_method(rb_cString, "bitwise_and",     rb_str_bitwise_and,       1);
+    rb_define_method(rb_cString, "bitwise_and!",    rb_str_bitwise_and_bang,  1);
+    rb_define_method(rb_cString, "bitwise_or",      rb_str_bitwise_or,        1);
+    rb_define_method(rb_cString, "bitwise_or!",     rb_str_bitwise_or_bang,   1);
+    rb_define_method(rb_cString, "bitwise_xor",     rb_str_bitwise_xor,       1);
+    rb_define_method(rb_cString, "bitwise_xor!",    rb_str_bitwise_xor_bang,  1);
 
     // These methods are defined here to avoid cluttering this file, but they are not part of the current core proposal (see FUTURE_PROPOSAL_PLAN.md).
-    rb_define_method(rb_cString, "each_bit_field",    rb_str_each_bit_field,   -1);
-    rb_define_method(rb_cString, "bit_fields",        rb_str_bit_fields,       -1);
-    rb_define_method(rb_cArray,  "mask",              rb_ary_mask,             -1);
-    rb_define_method(rb_cArray,  "mask!",             rb_ary_mask_bang,        -1);
+    rb_define_method(rb_cString, "each_bit_field",  rb_str_each_bit_field,   -1);
+    rb_define_method(rb_cString, "bit_fields",      rb_str_bit_fields,       -1);
+    rb_define_method(rb_cArray,  "mask",            rb_ary_mask,             -1);
+    rb_define_method(rb_cArray,  "mask!",           rb_ary_mask_bang,        -1);
 }