Add explanator comments

kamil-tekiela · kamil-tekiela · commit eb248b35d553 · 2023-09-07T23:53:57.000+01:00
Signed-off-by: Kamil Tekiela &lt;tekiela246@gmail.com&gt;
diff --git a/src/UtfString.php b/src/UtfString.php
@@ -102,6 +102,12 @@ public function offsetExists($offset): bool
      */
     public function offsetGet($offset): string|null
     {
+        // This function moves the internal byte and character pointer to the requested offset.
+        // This function is part of hot code so the aim is to do the following
+        // operations as efficiently as possible.
+        // UTF-8 character encoding is a variable length encoding that encodes Unicode
+        // characters in 1-4 bytes. Thus we fetch 4 bytes from the current offset and then use mb_substr
+        // to get the first UTF-8 character in it. We then use strlen to get the character's size in bytes.
         if (($offset < 0) || ($offset >= $this->charLen)) {
             return null;
         }
@@ -117,14 +123,17 @@ public function offsetGet($offset): string|null
         } elseif ($delta < 0) {
             // Rewinding.
             while ($delta++ < 0) {
+                // We rewind byte by byte and only count characters that are not continuation bytes,
+                // i.e. ASCII characters and first octets of multibyte characters
                 do {
                     $byte = ord($this->str[--$this->byteIdx]);
                 } while (($byte >= 128) && ($byte < 192));
 
                 --$this->charIdx;
             }
         }
-
+        
+        // Fetch the first Unicode character within the next 4 bytes in the string.
         return mb_substr(substr($this->str, $this->byteIdx, 4), 0, 1);
     }
 

Original file line number	Diff line number	Diff line change
`@@ -102,6 +102,12 @@ public function offsetExists($offset): bool`
`102`	`102`	`*/`
`103`	`103`	`public function offsetGet($offset): string\|null`
`104`	`104`	`{`
	`105`	`+ // This function moves the internal byte and character pointer to the requested offset.`
	`106`	`+ // This function is part of hot code so the aim is to do the following`
	`107`	`+ // operations as efficiently as possible.`
	`108`	`+ // UTF-8 character encoding is a variable length encoding that encodes Unicode`
	`109`	`+ // characters in 1-4 bytes. Thus we fetch 4 bytes from the current offset and then use mb_substr`
	`110`	`+ // to get the first UTF-8 character in it. We then use strlen to get the character's size in bytes.`
`105`	`111`	`if (($offset < 0) \|\| ($offset >= $this->charLen)) {`
`106`	`112`	`return null;`
`107`	`113`	`}`
`@@ -117,14 +123,17 @@ public function offsetGet($offset): string\|null`
`117`	`123`	`} elseif ($delta < 0) {`
`118`	`124`	`// Rewinding.`
`119`	`125`	`while ($delta++ < 0) {`
	`126`	`+ // We rewind byte by byte and only count characters that are not continuation bytes,`
	`127`	`+ // i.e. ASCII characters and first octets of multibyte characters`
`120`	`128`	`do {`
`121`	`129`	`$byte = ord($this->str[--$this->byteIdx]);`
`122`	`130`	`} while (($byte >= 128) && ($byte < 192));`
`123`	`131`
`124`	`132`	`--$this->charIdx;`
`125`	`133`	`}`
`126`	`134`	`}`
`127`		`-`
	`135`	`+`
	`136`	`+ // Fetch the first Unicode character within the next 4 bytes in the string.`
`128`	`137`	`return mb_substr(substr($this->str, $this->byteIdx, 4), 0, 1);`
`129`	`138`	`}`
`130`	`139`