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:
@@ -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.
|
||||
|
||||
@@ -30,8 +30,12 @@ Numbers are instances of the [Num](core/num.html) class.
|
||||
|
||||
## Strings
|
||||
|
||||
Strings are chunks of text stored as UTF-8. Their class is
|
||||
[String](core/string.html). String literals are surrounded in double quotes:
|
||||
A string is an array of bytes. Typically, they store characters encoded in
|
||||
UTF-8, but you can put any byte values in there, even zero or invalid UTF-8
|
||||
sequences. (You might have some trouble *printing* the latter to your terminal,
|
||||
though.)
|
||||
|
||||
String literals are surrounded in double quotes:
|
||||
|
||||
:::dart
|
||||
"hi there"
|
||||
@@ -39,6 +43,7 @@ Strings are chunks of text stored as UTF-8. Their class is
|
||||
A handful of escape characters are supported:
|
||||
|
||||
:::dart
|
||||
"\0" // The NUL byte: 0.
|
||||
"\"" // A double quote character.
|
||||
"\\" // A backslash.
|
||||
"\a" // Alarm beep. (Who uses this?)
|
||||
@@ -49,7 +54,16 @@ A handful of escape characters are supported:
|
||||
"\t" // Tab.
|
||||
"\v" // Vertical tab.
|
||||
|
||||
A `\u` followed by four hex digits can be used to specify a Unicode code point.
|
||||
A `\u` followed by four hex digits can be used to specify a Unicode code point:
|
||||
|
||||
:::dart
|
||||
IO.print("\u0041\u0b83\u00DE") // "AஃÞ"
|
||||
|
||||
A `\x` followed by two hex digits specifies a single unencoded byte:
|
||||
|
||||
IO.print("\x48\x69\x2e") // "Hi."
|
||||
|
||||
Strings are objects of class [String](core/string.html).
|
||||
|
||||
## Ranges
|
||||
|
||||
|
||||
Reference in New Issue
Block a user