fast_mb_chars 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 35532c3219891f1ff4d3a7fe168abb9213bafa430d7c33051eb2ac58f24ab0a5
+  data.tar.gz: 64672d7dd534037d5bda31bd52e606246f527583bd5880ca33100f4b0d435bf4
+SHA512:
+  metadata.gz: 21021182d78d1ba4d51d518546161f95a412709dfa998f2a20068c542cd874932a6ea3de8cc981b9e6d7f77f6651a9eabef480ffdc4f6add5de179354cfb6ba1
+  data.tar.gz: e8c45c5e5aa21babbbe604151228ddd39bea12882d1dee684761ab71fdd166da801e7159e7f1ffd6161aef816a15f2d2d0e1f3d002d568ab02ea9760ed690d2e

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 0.1.0
+
+`String#mb_chars` with the usual case, split, and Unicode helpers, plus `limit(bytes)`.
+
+The gem prepends `String#mb_chars`. ASCII and UTF-8 are supported. Other encodings need `encode('UTF-8')` first.
+
+The byte cut stays on a character boundary. A character that crosses the limit is kept when it finishes within 128 bytes. A longer combining sequence is dropped. Invalid bytes do not raise.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SYNORYXEL
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,180 @@
+# ⚡ fast_mb_chars
+
+Faster `String#mb_chars` for Ruby. Same calls as `ActiveSupport::Multibyte::Chars` — `limit`, `downcase`, `upcase`, `titleize`, `reverse`, `split`, `tidy_bytes`. The byte cut does not split a character and does not raise on a broken byte.
+
+Works on **ASCII** and **UTF-8** (Київ, café, 日本語, emoji). Other encodings need a convert first.
+
+<p align="center">
+  <img src="docs/limit-cut.svg" alt="Byte limit lands inside я; the gem keeps the whole letter" width="880">
+</p>
+
+`mb_chars.limit` in Rails reads every character from the start of the string. This gem looks at the cut. On a 1 MB string that is **205 ms** vs **0.08 ms**.
+
+| | 1 MB | 7 MB |
+| --- | ---: | ---: |
+| ActiveSupport-style scan | 205 ms | 1,410 ms |
+| **fast_mb_chars** | **0.08 ms** | **0.47 ms** |
+| | **~2,500×** | **~3,000×** |
+
+ASCII, Ruby 4.0.5, one call. The string is longer than the limit, so both sides actually cut. Full tables are [below](#-benchmarks).
+
+[![test](https://github.com/SYNORYXEL/fast_mb_chars/actions/workflows/ci.yml/badge.svg)](https://github.com/SYNORYXEL/fast_mb_chars/actions)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%202.7-cc342d?logo=ruby&logoColor=white)](https://www.ruby-lang.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![UTF-8](https://img.shields.io/badge/encoding-UTF--8%20%2B%20ASCII-1a7f37)](#-encodings)
+
+Source: [github.com/SYNORYXEL/fast_mb_chars](https://github.com/SYNORYXEL/fast_mb_chars)
+
+## 🌍 Encodings
+
+The gem treats the string as **UTF-8 bytes**. ASCII is UTF-8. It is not a transcoding library.
+
+| Input | What happens |
+| --- | --- |
+| ASCII `hello` | Fast path. Both bytes on the boundary are `< 0x80`, so the cut is exact. |
+| UTF-8 `Київ`, `café`, `日本語`, `👨‍👩‍👧‍👦` | Yes. A letter or emoji that crosses the limit stays whole. |
+| Broken / binary bytes | No `ArgumentError`. Invalid sequences are skipped or scrubbed. |
+| Windows-1252 mixed into UTF-8 (`caf\xE9`) | `tidy_bytes` repairs it to `café`. |
+| Windows-1251, KOI8-R, ISO-8859-1, Shift_JIS, UTF-16 | **No.** Bytes are relabeled as UTF-8, not converted. Encode first. |
+
+```ruby
+# already UTF-8 or ASCII — just call it
+'Київ'.mb_chars.downcase.to_s
+'hello'.mb_chars.limit(4).to_s
+
+# other encodings: convert, then cut
+cp1251.encode('UTF-8').mb_chars.limit(1_048_576).to_s
+```
+
+`force_encoding('UTF-8')` only changes the label. `encode('UTF-8')` changes the bytes. Use the second one when the source is not UTF-8.
+
+## 📦 Install
+
+Ruby 2.7 or newer. Tests run on 4.0.5. CI runs 2.7, 3.2, 3.3, 3.4, and 4.0.
+
+```ruby
+gem 'fast_mb_chars', github: 'SYNORYXEL/fast_mb_chars'
+```
+
+```ruby
+require 'fast_mb_chars'
+```
+
+The gem prepends `String#mb_chars`, so existing `'text'.mb_chars.downcase` calls in a Rails app keep working. It does not patch `String#downcase`. If another library prepends `mb_chars` later, call `FastMbChars.install!` again. No runtime dependencies. Not on RubyGems yet — install from GitHub.
+
+From a checkout: `gem build fast_mb_chars.gemspec` then `gem install ./fast_mb_chars-0.1.0.gem`. Next to an app, `gem 'fast_mb_chars', path: '../fast_mb_chars'` works too.
+
+## ✨ Usage
+
+```ruby
+'ГОТІВКА'.mb_chars.downcase.to_s
+# => "готівка"
+
+'  Київ  '.mb_chars.downcase.strip.to_s
+# => "київ"
+
+'ÉL QUE SE ENTERÓ'.mb_chars.titleize.to_s
+# => "Él Que Se Enteró"
+
+'Café périferôl'.mb_chars.split(/é/).map { |part| part.upcase.to_s }
+# => ["CAF", " P", "RIFERÔL"]
+
+data.mb_chars.limit(1_048_576).to_s
+data.mb_chars.limit(7_340_032).to_s
+```
+
+Methods on the proxy itself: `limit`, `reverse`, `reverse!`, `titleize`, `titlecase`, `compose`, `decompose`, `grapheme_length`, `tidy_bytes`, `tidy_bytes!`, `split`, `slice!`, `<=>`, `=~`, `match?`, `acts_like_string?`, `as_json`, `to_s`, `to_str`.
+
+`downcase`, `upcase`, `capitalize`, `swapcase`, `strip`, `gsub`, `length`, and the rest of `String` go through `method_missing`. A string result comes back as `mb_chars`, so the chain does not break. A bang method that changes the string returns the same proxy; if Ruby returns `nil` (no change), this does too.
+
+`titleize` is a Unicode-aware regex, not ActiveSupport inflections.
+
+## 🚀 Why it is faster
+
+Rails does this:
+
+```ruby
+def limit(limit)
+  chars(@wrapped_string.truncate_bytes(limit, omission: nil))
+end
+```
+
+`truncate_bytes` walks graphemes from byte 0 until it hits the limit. That is fine for a button label. It is not fine for a 1 MB or 7 MB log line.
+
+`fast_mb_chars` reads the two bytes on the boundary.
+
+- Both ASCII, and not a CR+LF pair: one `byteslice`. Exact.
+- A character crosses the limit and ends within 128 bytes: keep it whole. The result can be a few bytes over the limit.
+- A long run of combining marks that does not fit in those 128 bytes: drop it. The result stays within the limit.
+- Empty string, or a limit of 0 or less: `""`.
+- Shorter than the limit: returned as-is, trailing spaces and punctuation included.
+- A broken byte never reaches a regexp, so there is no `ArgumentError`.
+
+Rails never goes past the limit, so it drops the character on the boundary. This gem keeps a short character. That is the one behavioral difference, and it is why a cut like `('a' * (limit - 1)) + 'я'` comes back one byte longer, with `я` intact.
+
+```mermaid
+flowchart LR
+  A[1 MB string] --> B{bytes at the limit}
+  B -->|both ASCII| C[byteslice exact]
+  B -->|UTF-8 letter or emoji| D[keep the cluster if it ends within 128 bytes]
+  B -->|broken byte| E[safe prefix no raise]
+```
+
+## 📊 Benchmarks
+
+"scan" walks graphemes from the start, which is what `mb_chars.limit` does. "fast" is `FastMbChars::Limiter.limit`. Milliseconds per call, Ruby 4.0.5.
+
+### ASCII
+
+The cut lands on a byte. Both results are exactly the limit.
+
+| size | scan | fast | times |
+| --- | ---: | ---: | ---: |
+| 1 KB | 0.198 | 0.000 | 499× |
+| 8 KB | 1.566 | 0.001 | 1,284× |
+| 64 KB | 12.671 | 0.010 | 1,233× |
+| 256 KB | 50.936 | 0.028 | 1,841× |
+| 1 MB | 205.382 | 0.083 | 2,467× |
+| 7 MB | 1,409.907 | 0.466 | 3,028× |
+
+### Cyrillic
+
+The cut lands between letters. Both results are exactly the limit.
+
+| size | scan | fast | times |
+| --- | ---: | ---: | ---: |
+| 1 KB | 0.145 | 0.020 | 7× |
+| 8 KB | 1.145 | 0.022 | 52× |
+| 64 KB | 9.282 | 0.023 | 407× |
+| 256 KB | 36.863 | 0.040 | 931× |
+| 1 MB | 147.932 | 0.068 | 2,164× |
+| 7 MB | 1,032.553 | 0.194 | 5,322× |
+
+### Character on the boundary
+
+`я` crosses the limit. The scan stops on the limit and drops the letter. The fast cut keeps it, so the result is one byte over.
+
+| size | scan | fast | times | fast bytes / limit |
+| --- | ---: | ---: | ---: | ---: |
+| 1 KB | 0.196 | 0.027 | 7× | 1025 / 1024 |
+| 8 KB | 1.545 | 0.029 | 54× | 8193 / 8192 |
+| 64 KB | 12.377 | 0.028 | 443× | 65537 / 65536 |
+| 256 KB | 49.862 | 0.026 | 1,893× | 262145 / 262144 |
+| 1 MB | 199.377 | 0.036 | 5,597× | 1048577 / 1048576 |
+| 7 MB | 1,479.463 | 0.030 | 49,870× | 7340033 / 7340032 |
+
+On a short string you pay for the wrapper, not for the cut. `'ГОТІВКА'.mb_chars.downcase.to_s` was 0.0006 ms. `String#downcase` was 0.0002 ms.
+
+```bash
+ruby benchmark/compare.rb
+```
+
+## ✅ Tests
+
+```bash
+bundle exec rake
+```
+
+## 📄 License
+
+MIT. See [LICENSE](LICENSE).

data/benchmark/compare.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+# ruby benchmark/compare.rb
+# rake benchmark
+
+$LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
+
+require 'fast_mb_chars'
+
+# What ActiveSupport::Multibyte::Chars#limit does: walk every grapheme from
+# the start and never go past the byte budget.
+def walk_limit(text, max_bytes)
+  text = text.to_s
+  return +'' if max_bytes <= 0 || text.empty?
+  return text.dup if text.bytesize <= max_bytes
+
+  taken = 0
+  text.each_grapheme_cluster do |cluster|
+    size = cluster.bytesize
+    break if taken + size > max_bytes
+
+    taken += size
+  end
+  text.byteslice(0, taken)
+end
+
+SIZES = [
+  ['1 KB', 1_024, 300],
+  ['8 KB', 8_192, 150],
+  ['64 KB', 65_536, 40],
+  ['256 KB', 262_144, 15],
+  ['1 MB', 1_048_576, 8],
+  ['7 MB', 7_340_032, 3]
+].freeze
+
+# The string is longer than the limit, so both sides actually cut.
+# split puts one 2-byte letter across the boundary.
+def payload(kind, bytes)
+  case kind
+  when :ascii
+    ['a' * (bytes + 64), bytes]
+  when :cyrillic
+    ['я' * ((bytes / 2) + 16), bytes]
+  when :split
+    [(('a' * (bytes - 1)) + 'я'), bytes]
+  end
+end
+
+def time_ms(iterations)
+  started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  iterations.times { yield }
+  ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) / iterations) * 1000.0
+end
+
+rows = []
+
+puts "ruby #{RUBY_VERSION}  fast_mb_chars #{FastMbChars::VERSION}"
+puts "limit vs full grapheme walk (ms per call, one process)"
+puts
+
+%i[ascii cyrillic split].each do |kind|
+  puts kind
+  puts format('%-8s %10s %10s %8s  %s', 'size', 'walk', 'fast', 'times', 'result')
+  SIZES.each do |label, bytes, iterations|
+    text, limit = payload(kind, bytes)
+    2.times { walk_limit(text, limit) }
+    2.times { FastMbChars::Limiter.limit(text, limit) }
+    slow = time_ms(iterations) { walk_limit(text, limit) }
+    fast = time_ms(iterations) { FastMbChars::Limiter.limit(text, limit) }
+    ratio = fast.positive? ? slow / fast : 0
+    cut = FastMbChars::Limiter.limit(text, limit)
+    rows << [kind, label, slow, fast, ratio, cut.bytesize, limit]
+    puts format('%-8s %10.3f %10.3f %7.0fx  %d/%d bytes', label, slow, fast, ratio, cut.bytesize, limit)
+  end
+  puts
+end
+
+small = 'ГОТІВКА'
+time_ms(1000) { small.mb_chars.downcase.to_s }
+down = time_ms(20_000) { small.mb_chars.downcase.to_s }
+plain = time_ms(20_000) { small.downcase }
+puts format('downcase %s  mb_chars %.4f ms   String#downcase %.4f ms', small, down, plain)

data/docs/limit-cut.svg

@@ -0,0 +1,66 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="880" height="300" viewBox="0 0 880 300" role="img" aria-labelledby="title desc">
+  <title id="title">fast_mb_chars cuts on a character boundary</title>
+  <desc id="desc">The byte limit lands inside a UTF-8 letter. The gem keeps the whole character instead of splitting it.</desc>
+  <defs>
+    <style>
+      .bg { fill: #f6f8fa; }
+      .card { fill: #ffffff; stroke: #d0d7de; }
+      .ink { fill: #1f2328; }
+      .muted { fill: #656d76; }
+      .line { stroke: #d0d7de; }
+      .keep { fill: #1a7f37; }
+      .drop { fill: #cf222e; }
+      .accent { fill: #cf222e; }
+      .chip { fill: #fff8f8; stroke: #ffcecb; }
+      .cell { fill: #ffffff; stroke: #d0d7de; }
+      .cell-keep { fill: #dafbe1; stroke: #4ac26b; }
+      .cell-cut { fill: #fff8c5; stroke: #d4a72c; }
+      @media (prefers-color-scheme: dark) {
+        .bg { fill: #0d1117; }
+        .card { fill: #161b22; stroke: #30363d; }
+        .ink { fill: #e6edf3; }
+        .muted { fill: #8b949e; }
+        .line { stroke: #30363d; }
+        .keep { fill: #3fb950; }
+        .drop { fill: #f85149; }
+        .accent { fill: #f85149; }
+        .chip { fill: #3d1619; stroke: #6e2b2f; }
+        .cell { fill: #0d1117; stroke: #30363d; }
+        .cell-keep { fill: #12261e; stroke: #238636; }
+        .cell-cut { fill: #2a2111; stroke: #9e6a03; }
+      }
+    </style>
+  </defs>
+  <rect class="bg" width="880" height="300" rx="16"/>
+  <rect class="card" x="16" y="16" width="848" height="268" rx="12"/>
+
+  <text class="ink" x="40" y="52" font-family="ui-sans-serif, system-ui, sans-serif" font-size="18" font-weight="700">limit looks at the cut, not the whole string</text>
+  <text class="muted" x="40" y="76" font-family="ui-sans-serif, system-ui, sans-serif" font-size="13">ASCII and UTF-8 &#x2014; characters stay whole</text>
+
+  <g font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="14">
+    <rect class="cell" x="40" y="104" width="44" height="44" rx="8"/>
+    <text class="ink" x="62" y="131" text-anchor="middle">a</text>
+    <rect class="cell" x="90" y="104" width="44" height="44" rx="8"/>
+    <text class="ink" x="112" y="131" text-anchor="middle">a</text>
+    <rect class="cell" x="140" y="104" width="44" height="44" rx="8"/>
+    <text class="ink" x="162" y="131" text-anchor="middle">a</text>
+    <rect class="cell-cut" x="190" y="104" width="44" height="44" rx="8"/>
+    <text class="ink" x="212" y="131" text-anchor="middle">a</text>
+    <rect class="cell-keep" x="240" y="104" width="92" height="44" rx="8"/>
+    <text class="keep" x="286" y="131" text-anchor="middle" font-weight="700">&#x44F;</text>
+    <rect class="cell" x="338" y="104" width="44" height="44" rx="8"/>
+    <text class="muted" x="360" y="131" text-anchor="middle">&#x2026;</text>
+  </g>
+
+  <path class="line" d="M234 156 v18" fill="none" stroke-width="2"/>
+  <text class="accent" x="234" y="196" text-anchor="middle" font-family="ui-sans-serif, system-ui, sans-serif" font-size="12" font-weight="700">byte limit</text>
+  <text class="muted" x="234" y="214" text-anchor="middle" font-family="ui-sans-serif, system-ui, sans-serif" font-size="11">inside the letter</text>
+
+  <rect class="chip" x="430" y="104" width="400" height="108" rx="10"/>
+  <text class="drop" x="450" y="132" font-family="ui-sans-serif, system-ui, sans-serif" font-size="13" font-weight="700">Rails scan</text>
+  <text class="muted" x="450" y="152" font-family="ui-sans-serif, system-ui, sans-serif" font-size="12">walks graphemes from byte 0 &#x2192; drops &#x44F;</text>
+  <text class="keep" x="450" y="180" font-family="ui-sans-serif, system-ui, sans-serif" font-size="13" font-weight="700">fast_mb_chars</text>
+  <text class="muted" x="450" y="200" font-family="ui-sans-serif, system-ui, sans-serif" font-size="12">reads the two bytes on the boundary &#x2192; keeps &#x44F;</text>
+
+  <text class="muted" x="40" y="256" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="12">('a' * (limit - 1)) + '&#x44F;'   &#x2192;   1 extra byte, letter intact</text>
+</svg>

data/lib/fast_mb_chars/chars.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module FastMbChars
+  # Proxy with the same methods as ActiveSupport::Multibyte::Chars.
+  # limit is the fast path. Everything else follows the string.
+  class Chars
+    include Comparable
+
+    attr_reader :wrapped_string
+    alias to_s wrapped_string
+    alias to_str wrapped_string
+
+    def initialize(text)
+      @wrapped_string = Limiter.utf8(text)
+      @wrapped_string = @wrapped_string.dup if @wrapped_string.frozen?
+    end
+
+    def limit(max_bytes)
+      chars(Limiter.limit(@wrapped_string, Integer(max_bytes)))
+    end
+
+    def reverse
+      chars(readable.grapheme_clusters.reverse.join)
+    end
+
+    def titleize
+      chars(readable.downcase.gsub(/\b('?\S)/u) { Regexp.last_match(1).upcase })
+    end
+    alias titlecase titleize
+
+    def decompose
+      chars(readable.unicode_normalize(:nfd))
+    end
+
+    def compose
+      chars(readable.unicode_normalize(:nfc))
+    end
+
+    def grapheme_length
+      readable.grapheme_clusters.length
+    end
+
+    def tidy_bytes(force = false)
+      chars(self.class.tidy_bytes(@wrapped_string, force))
+    end
+
+    def split(*args)
+      readable.split(*args).map { |part| self.class.new(part) }
+    end
+
+    def slice!(*args)
+      sliced = @wrapped_string.slice!(*args)
+      chars(sliced) if sliced
+    end
+
+    def reverse!
+      @wrapped_string = reverse.to_s
+      self
+    end
+
+    def tidy_bytes!(*args)
+      @wrapped_string = tidy_bytes(*args).to_s
+      self
+    end
+
+    def <=>(other)
+      to_s <=> other.to_s
+    end
+
+    def =~(other)
+      @wrapped_string =~ other
+    end
+
+    def match?(*args)
+      @wrapped_string.match?(*args)
+    end
+
+    def acts_like_string?
+      true
+    end
+
+    def as_json(options = nil)
+      to_s.respond_to?(:as_json) ? to_s.as_json(options) : to_s
+    end
+
+    def method_missing(method, ...)
+      retried = false
+      begin
+        result = @wrapped_string.__send__(method, ...)
+        if method.end_with?('!')
+          self if result
+        else
+          result.is_a?(String) ? chars(result) : result
+        end
+      rescue ArgumentError
+        raise if retried || @wrapped_string.valid_encoding?
+
+        retried = true
+        @wrapped_string = @wrapped_string.scrub
+        retry
+      end
+    end
+
+    def respond_to_missing?(method, include_private = false)
+      @wrapped_string.respond_to?(method, include_private) || super
+    end
+
+    def self.tidy_bytes(string, force = false)
+      return string if string.empty? || (string.valid_encoding? && string.ascii_only?)
+      return recode_windows1252(string) if force
+
+      string.scrub { |bad| recode_windows1252(bad) }
+    end
+
+    def self.recode_windows1252(string)
+      string.encode(Encoding::UTF_8, Encoding::Windows_1252, invalid: :replace, undef: :replace)
+    end
+    private_class_method :recode_windows1252
+
+    private
+
+    def readable
+      @wrapped_string.valid_encoding? ? @wrapped_string : @wrapped_string.scrub
+    end
+
+    def chars(string)
+      self.class.new(string)
+    end
+  end
+end

data/lib/fast_mb_chars/limiter.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module FastMbChars
+  # Cut to max_bytes without splitting a character and without reading
+  # the whole string. A character that crosses the limit is kept if it ends
+  # within SLACK bytes. A longer one is dropped. Invalid bytes do not raise.
+  module Limiter
+    SLACK = 128
+
+    module_function
+
+    def limit(text, max_bytes)
+      text = utf8(text)
+      return +'' if max_bytes <= 0 || text.empty?
+      return text.dup if text.bytesize <= max_bytes
+
+      prev = text.getbyte(max_bytes - 1)
+      nxt = text.getbyte(max_bytes)
+      if ascii_boundary?(prev, nxt)
+        cut = text.byteslice(0, max_bytes)
+        return cut if cut.valid_encoding?
+      end
+
+      cut_at_grapheme(text, max_bytes)
+    rescue ArgumentError
+      safe_prefix(text, max_bytes)
+    end
+
+    def utf8(text)
+      text = text.to_s
+      return text if text.encoding == Encoding::UTF_8
+
+      text.dup.force_encoding(Encoding::UTF_8)
+    end
+
+    def ascii_boundary?(prev, nxt)
+      prev && nxt && prev < 0x80 && nxt < 0x80 && !(prev == 0x0D && nxt == 0x0A)
+    end
+
+    def cut_at_grapheme(text, max_bytes)
+      start = align_start(text, [max_bytes - SLACK, 0].max)
+      hard_end = [text.bytesize, max_bytes + SLACK].min
+      finish = align_end(text, hard_end, max_bytes + SLACK)
+      finish = start if finish < start
+
+      window = text.byteslice(start, finish - start)
+      return safe_prefix(text, max_bytes) unless window.valid_encoding?
+
+      rel = max_bytes - start
+      taken = 0
+      keep = 0
+      window.each_grapheme_cluster do |cluster|
+        size = cluster.bytesize
+        break if taken >= rel
+
+        if taken + size <= rel
+          taken += size
+          keep = taken
+          next
+        end
+
+        cluster_end = start + taken + size
+        if cluster_end <= max_bytes + SLACK && grapheme_closed?(text, start + taken, cluster_end)
+          keep = taken + size
+        elsif taken.positive?
+          keep = taken
+        else
+          return safe_prefix(text, max_bytes)
+        end
+        break
+      end
+
+      text.byteslice(0, start + keep)
+    end
+
+    def grapheme_closed?(text, cluster_start, cluster_end)
+      return true if cluster_end >= text.bytesize
+
+      probe_end = next_char_end(text, cluster_end)
+      return true if probe_end <= cluster_end
+
+      sample = text.byteslice(cluster_start, probe_end - cluster_start)
+      return false unless sample&.valid_encoding?
+
+      matched = sample[/\A\X/]
+      matched&.bytesize == cluster_end - cluster_start
+    rescue ArgumentError
+      false
+    end
+
+    def align_start(text, index)
+      index = 0 if index.negative?
+      return text.bytesize if index >= text.bytesize
+
+      steps = 0
+      while index.positive? && steps < 3 && continuation?(text.getbyte(index))
+        index -= 1
+        steps += 1
+      end
+      index
+    end
+
+    def align_end(text, index, hard_end)
+      return 0 if index <= 0
+      return text.bytesize if index >= text.bytesize
+      return index unless continuation?(text.getbyte(index))
+
+      lead = align_start(text, index)
+      length = seq_length(text.getbyte(lead))
+      char_end = length ? lead + length : lead
+      char_end <= hard_end && char_end <= text.bytesize ? char_end : lead
+    end
+
+    def next_char_end(text, index)
+      return index if index >= text.bytesize
+
+      length = seq_length(text.getbyte(index)) || 1
+      [index + length, text.bytesize].min
+    end
+
+    def seq_length(lead)
+      return 1 if lead < 0x80
+      return 2 if (lead & 0xE0) == 0xC0
+      return 3 if (lead & 0xF0) == 0xE0
+      return 4 if (lead & 0xF8) == 0xF0
+
+      nil
+    end
+
+    def continuation?(byte)
+      byte && (byte & 0xC0) == 0x80
+    end
+
+    def safe_prefix(text, max_bytes)
+      limit = [max_bytes, text.bytesize].min
+      if limit.positive? && limit < text.bytesize && continuation?(text.getbyte(limit))
+        limit = align_start(text, limit)
+      end
+      cut = text.byteslice(0, limit)
+      return cut if cut.valid_encoding?
+
+      3.times do
+        break if cut.empty?
+
+        cut = cut.byteslice(0, cut.bytesize - 1)
+        return cut if cut.valid_encoding?
+      end
+
+      text.byteslice(0, [max_bytes, text.bytesize].min).scrub('?')
+    end
+  end
+end

data/lib/fast_mb_chars/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module FastMbChars
+  VERSION = '0.1.0'
+end

data/lib/fast_mb_chars.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'fast_mb_chars/version'
+require 'fast_mb_chars/limiter'
+require 'fast_mb_chars/chars'
+
+module FastMbChars
+  # Prepends a fresh module each time the method was taken over by someone
+  # else. Prepending the same module twice does not move it back to the front.
+  def self.install!
+    if String.method_defined?(:mb_chars) && String.instance_method(:mb_chars).owner == @installed
+      return
+    end
+
+    @installed = Module.new do
+      def mb_chars
+        FastMbChars::Chars.new(self)
+      end
+    end
+    String.prepend(@installed)
+  end
+
+  install!
+end

metadata

@@ -0,0 +1,66 @@
+--- !ruby/object:Gem::Specification
+name: fast_mb_chars
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- SYNORYXEL
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-10-07 00:00:00.000000000 Z
+dependencies: []
+description: |
+  Faster String#mb_chars. limit(bytes) cuts on a character boundary without
+  walking the whole string and without raising on a broken byte. A 1 MB cut
+  is about 2,000 times faster than the ActiveSupport grapheme scan, and a
+  7 MB cut is about 3,000 times faster.
+
+  downcase, upcase, titleize, reverse, split, slice!, compose, decompose,
+  tidy_bytes, and the other string methods are forwarded through method_missing.
+  They still return mb_chars, so existing chains keep working.
+email:
+- mike.pvlv@icloud.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- benchmark/compare.rb
+- docs/limit-cut.svg
+- lib/fast_mb_chars.rb
+- lib/fast_mb_chars/chars.rb
+- lib/fast_mb_chars/limiter.rb
+- lib/fast_mb_chars/version.rb
+homepage: https://github.com/SYNORYXEL/fast_mb_chars
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/SYNORYXEL/fast_mb_chars
+  source_code_uri: https://github.com/SYNORYXEL/fast_mb_chars
+  changelog_uri: https://github.com/SYNORYXEL/fast_mb_chars/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/SYNORYXEL/fast_mb_chars/issues
+  allowed_push_host: https://rubygems.org
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Faster Ruby String#mb_chars. Byte limit that keeps UTF-8 characters whole
+test_files: []