feat: add raw byte access methods and \x escape to String class

Add `byteAt(index)`, `codePointAt(index)`, and `bytes` sequence to String,
enabling direct byte-level manipulation of UTF-8 encoded strings. Introduce
`\x` hex escape sequence in string literals for specifying raw byte values.
Refactor Unicode escape parsing into a generic `readHexEscape` function
supporting variable digit counts. Implement `wrenUtf8Decode` utility for
decoding UTF-8 sequences from byte buffers. Add comprehensive tests for
`byteAt` including boundary conditions and error cases.
This commit is contained in:
Bob Nystrom
2015-03-28 03:44:07 +00:00
parent b7904a89c9
commit c3d0b66630
36 changed files with 402 additions and 15 deletions
+42
View File
@@ -45,6 +45,48 @@ It is a runtime error if `codePoint` is not an integer between `0` and
## Methods
### **byteAt**(index)
Gets the value of the byte at byte offset `index` in the string.
:::dart
IO.print("hello".byteAt(1)) // 101, for "e".
If the index is negative, it counts backwards from the end of the string.
:::dart
IO.print("hello".byteAt(-4)) // 101, for "e".
It is a runtime error if `index` is not an integer or is out of bounds.
### **bytes**
Gets a [`Sequence`](sequence.html) that can be used to access the raw bytes of
the string and ignore any UTF-8 encoding. In addition to the normal sequence
methods, the returned object also has a subscript operator that can be used to
directly index bytes.
:::dart
IO.print("hello".bytes[1]) // 101, for "e".
### **codePointAt**(index)
Gets the value of the UTF-8 encoded code point starting at byte offset `index`
in the string. Unlike the subscript operator, this returns the code point as a
number.
:::dart
var string = "(ᵔᴥᵔ)"
IO.print(string.codePointAt(0)) // 40, for "(".
IO.print(string.codePointAt(4)) // 7461, for "ᴥ".
If the byte at `index` does not begin a valid UTF-8 sequence, or the end of the
string is reached before the sequence is complete, returns `-1`.
:::dart
var string = "(ᵔᴥᵔ)"
IO.print(string.codePointAt(2)) // -1, in the middle of "ᵔ".
### **contains**(other)
Checks if `other` is a substring of the string.