Merge pull request #8 from savi-lang/add/reserve-bytes-ahead

Add `ByteStream.Reader.reserve_bytes_ahead`.

Author: jemc

spec/ByteStream.Reader.Spec.savi

@@ -207,6 +207,27 @@
     assert: stream.token_byte_size == 0
     assert: stream.token_as_string == ""
 
+  :it "reserves at least a specified amount of space in front of the cursor"
+    stream = ByteStream.Reader.new
+    write_stream = ByteStream.Writer.to_reader(stream)
+
+    assert: stream.space_ahead == 0x4000
+    assert: stream.reserve_bytes_ahead(0x8000).space_ahead == 0x8000
+    assert: stream.reserve_bytes_ahead(0x8000).space_ahead == 0x8000
+
+    write_stream << b"hello"
+    assert no_error: write_stream.flush!
+
+    assert: stream.space_ahead == 0x8000
+    assert: stream.reserve_bytes_ahead(0x8000).space_ahead == 0x8000
+    assert: stream.reserve_bytes_ahead(0x8000).space_ahead == 0x8000
+
+    assert no_error: stream.advance!(3)
+
+    assert: stream.space_ahead == 0x7FFD
+    assert: stream.reserve_bytes_ahead(0x8000).space_ahead == 0xFFFD
+    assert: stream.reserve_bytes_ahead(0x8000).space_ahead == 0xFFFD
+
   :it "extracts an isolated token destructively from the stream"
     stream = ByteStream.Reader.new
     write_stream = ByteStream.Writer.to_reader(stream)

src/ByteStream.Reader.savi

@@ -112,13 +112,26 @@
   :: very start of the byte stream, including bytes no longer held in buffer.
   :fun bytes_behind_marker: @_mark_offset + @_lost_offset
 
+  :: Ensure that the underlying byte buffer is ready to handle the given amount
+  :: of bytes ahead of the current cursor position, without copying on receive.
+  :: This includes both bytes already in the buffer and space for future bytes.
+  ::
+  :: Note that this may trigger a copy of the current content of the buffer
+  :: if a reallocation is needed to ensure that number of bytes are available,
+  :: but that copy can be avoided if the full buffer is extracted first.
+  :fun ref reserve_bytes_ahead(amount USize)
+    actual_amount = try (amount +! @_offset | USize.max_value)
+    @_data.reserve(actual_amount)
+    @
+
   :: Reserve additional space in the underlying byte buffer, which forces a
   :: reallocation now, but sets a minimum number of bytes that the buffer
   :: can receive beyond the current size without forcing a reallocation.
   ::
   :: See `Bytes.reserve_additional` for more information.
   :fun ref reserve_additional(additional_space)
     @_data.reserve_additional(additional_space)
+    @
 
   :: Get the number of bytes in the currently marked token.
   :: That is, the number of bytes between the marker and the cursor.