mruby · matz · Aug 20, 2026 · Aug 18, 2026 · Aug 18, 2026 · Aug 18, 2026
@@ -229,21 +229,26 @@ end
 - The regexp POSIX brackets classify by Unicode above ASCII: `[[:alpha:]]`
   holds a letter of any script and `[[:^alpha:]]` rejects it, as in CRuby.
   Without this macro a bracket holds its ASCII and no character above it.
-- `MRB_USE_ASCII_CTYPE` narrows the case and the brackets back to ASCII,
-  taking the refusal with them and leaving the indexing.
+- `String#succ` steps a letter or a digit above ASCII within its own run of
+  them and wraps at the end of it, as in CRuby (`"ת".succ` is `"אא"`).
+  Without this macro nothing above ASCII is a letter or a digit, and the last
+  character steps as a character.
+- `MRB_USE_ASCII_CTYPE` narrows the case, the brackets and `String#succ` back
+  to ASCII, taking the refusal with them and leaving the indexing.
 - If it isn't defined, they only support the US-ASCII encoding.
 
 `MRB_USE_ASCII_CTYPE`
 
 - Narrows the character classification of `MRB_UTF8_STRING` back to ASCII
   while keeping its indexing: `String#downcase`, `#upcase`, `#capitalize`,
   `#swapcase` and `#casecmp?` answer for `'A'` to `'Z'` and hand every other
-  character back as it stands, and a regexp POSIX bracket holds its ASCII and
-  no character above it.
-- Drops the Unicode tables the build would otherwise carry, core's case table
-  and mruby-regexp's type table. That is what the option is for: a target
-  counting its bytes buys the UTF-8 indexing of `MRB_UTF8_STRING` without the
-  tables beside it.
+  character back as it stands, a regexp POSIX bracket holds its ASCII and no
+  character above it, and `String#succ` finds no letter and no digit above
+  ASCII to step.
+- Drops the Unicode tables the build would otherwise carry, core's case table,
+  mruby-regexp's type table and mruby-string-ext's table of the letters and
+  the digits. That is what the option is for: a target counting its bytes buys
+  the UTF-8 indexing of `MRB_UTF8_STRING` without the tables beside it.
 - Bytes that spell no character are handed back as they stand rather than
   refused with `ArgumentError`. That refusal belongs to the walk over
   characters, which is the walk this narrows away: what converts instead reads

@@ -661,7 +661,7 @@ Example:
 
 ### `String#succ` (alias `String#next`)
 
-Returns the successor to `str`. Increments the rightmost alphanumeric characters.
+Returns the successor to `str`. Increments the rightmost alphanumeric character, carrying into the alphanumeric before it when it wraps. The carry crosses characters that are not alphanumeric, but not from a letter into a digit or from a digit into a letter; a new character goes in instead. A string with no alphanumeric increments its last character instead: a byte in a binary string (or in a build without `MRB_UTF8_STRING`), a code point in a UTF-8 string.
 
 ```ruby
 str.succ    #=> new_str
@@ -670,14 +670,30 @@ str.succ    #=> new_str
 Example:
 
 ```ruby
-"a".succ     #=> "b"
-"z".succ     #=> "aa"
-"9".succ     #=> "10"
-"a9".succ    #=> "b0"
-"Az".succ    #=> "Ba"
-"zz".succ    #=> "aaa"
+"a".succ         #=> "b"
+"z".succ         #=> "aa"
+"9".succ         #=> "10"
+"a9".succ        #=> "b0"
+"Az".succ        #=> "Ba"
+"zz".succ        #=> "aaa"
+"1.9".succ       #=> "2.0"
+"1-z".succ       #=> "1-aa"
+"a-9".succ       #=> "a-10"
+"-".succ         #=> "."
+"\xff".b.succ    #=> "\x01\x00"
 ```
 
+Which characters above ASCII are letters and which are digits is the Unicode character database's answer, the same properties `[[:alpha:]]` and `[[:digit:]]` hold. A letter increments within its own run of letters and wraps at the end of it, and what the wrap carries in is a character of that run rather than an ASCII letter:
+
+```ruby
+"ÿ".succ     #=> "Ā"
+"ת".succ    #=> "אא"
+"aｚ".succ    #=> "bａ"
+"٩".succ     #=> "١٠"
+```
+
+A build that reads its strings as bytes, and one narrowed by `MRB_USE_ASCII_CTYPE`, carries no such table: nothing above ASCII is a letter or a digit there, so `"aÿ".succ` is `"bÿ"` and a string with no ASCII alphanumeric increments its last character. That is the trade `MRB_USE_ASCII_CTYPE` already makes for case.
+
 ### `String#succ!` (alias `String#next!`)
 
 Equivalent to `String#succ`, but modifies the receiver in place.