Implement Cursor::amend

README.md

@@ -67,3 +67,23 @@ var_dump($items); // [x, y]
 $cursor->reset(); // by resetting it.
 $cursor->seek(Seek::start(0)); // or seeking.
 ```
+
+### Amend
+
+Useful for operations such as compression to avoid creating a new buffer.
+
+```php
+<?php
+
+declare(strict_types=1);
+
+require_once __DIR__.'/vendor/autoload.php';
+
+use Thesis\ByteCursor\Cursor;
+use Thesis\ByteCursor\Seek;
+
+$cursor = Cursor::empty();
+$cursor->write('secret');
+$cursor->seek(Seek::start(0));
+$cursor->amend(snappy_compress(...)); // no need to seek, amend automatically moves the cursor to the end
+```

src/Cursor.php

@@ -212,6 +212,28 @@ public function __toString(): string
         return $this->buffer;
     }
 
+    /**
+     * @param callable(non-empty-string): non-empty-string $fix
+     * @param ?positive-int $len
+     */
+    public function amend(callable $fix, ?int $len = null): void
+    {
+        $len ??= \strlen($this->buffer);
+        if ($len > \strlen($this->buffer)) {
+            throw new \UnexpectedValueException(\sprintf('Len of amend "%d" is longer than available buffer.', $len));
+        }
+
+        $v = substr($this->buffer, $this->position, $len);
+        if ($v !== '') {
+            $v = $fix($v);
+
+            $this->buffer = substr($this->buffer, 0, $this->position);
+            $this->buffer .= $v;
+            $this->buffer .= substr($this->buffer, $this->position + \strlen($v), \strlen($this->buffer));
+            $this->position = \strlen($this->buffer);
+        }
+    }
+
     /**
      * @return non-negative-int
      */

tests/CursorTest.php

@@ -59,4 +59,15 @@ public function testReset(): void
         self::assertCount(0, $cursor);
         self::assertSame(0, $cursor->position());
     }
+
+    public function testAmend(): void
+    {
+        $cursor = Cursor::empty();
+        $cursor->write('before compression');
+        $cursor->seek(Seek::start(0));
+        $cursor->amend(static fn(string $v): string => 'aftrcompr');
+        $cursor->write('xyz');
+        self::assertSame(\count($cursor), $cursor->position());
+        self::assertSame('aftrcomprxyz', $cursor->reset());
+    }
 }