Repository navigation
Breaking changes for v0.3.0 - #29
Merged
Merged
Conversation
jakobnissen
force-pushed
the
v030
branch
2 times, most recently
from
June 18, 2026 14:12
d36f5e9 to
4d2e942
Compare
|
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## master #29 +/- ##
==========================================
+ Coverage 94.25% 97.02% +2.77%
==========================================
Files 11 11
Lines 1079 1077 -2
==========================================
+ Hits 1017 1045 +28
+ Misses 62 32 -30
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
This breaking change for v0.3.0 makes more semantic sense.
Reading and writing multi-byte structs add a lot of complications which this package isn't equipped to handle, and quickly spirals into a ser/de package. For example, it requires handling: * Endianness * How to handle partial reads/write with multi-byte data * How to handle serde of types which need validation on construction * Custom serialization for certain primitives like Char ... and more. Addressing this requires a completely new and distinct API. I will spin this off to a separate package.
This reaches into Base internals, but I believe it might be worth it.
This means e.g. `print(::AbstractBufWriter, x)` does not print first the writer, then x.
* Remove unused kinds * Revert IOError to being immutable, for performance * Have writer fail return either BufferTooShort or WriterFull, not EOF
This matches `write` and it was weird that it didn't throw, and the user had to check the returned value.
BufferIO's own APIs uses concrete types where possible, whereas Base overloads use abstract types to match Base, and to avoid erroneous dispatch to the Base methods.
* Rename `chomp` kwarg to `keep` * Optimize `readline` and have `EachLine` use it * Have `line_views` use `expandable` to remove edge case of buffer limit
This mostly reverts e68de22, which defined `filesize(::AbstractBufWriter)` to count only flushed bytes. That definition allowed `position` to exceed `filesize`, and the rest of the API had to work around it: `seek` had to promise a full flush and check its bounds after that flush, and `seekend` needed a writer-specific method. The problem that motivated e68de22 was that `VecWriter`'s `seek` truncated the vector, so `position == filesize` always, and seeking back lost data. The fix for that is the rule that seeking never truncates, not excluding buffered data from `filesize`. `filesize` is now the size the file will have once flushed, which for `BufWriter` is `max(filesize(inner), position(inner) + consumed)`. This is correct because writes overwrite, and never truncate. Examples, with `w = BufWriter(IOBuffer()); write(w, "hello")`: * `position` and `filesize` are consistent: (position(w), filesize(w)) # before: (5, 0), now: (5, 5) Generic code computing e.g. `filesize(io) - position(io)` got -5. * You can check an offset before seeking: 3 in 0:filesize(w) # before: false, now: true Before, this returned false, yet `seek(w, 3)` succeeded, because the valid range was only known after `seek`'s flush. * Generic `seek(io, filesize(io))` silently corrupted data: seek(w, filesize(w)); write(w, "!"); flush(w) Before, this seeked to 0 and the IOBuffer contained "!ello". Now it contains "hello!". This is also why `seekend` no longer needs a writer-specific method. * The size of a file being written is observable without flushing: write(w, "payload"); filesize(w) # before: 0, now: 12 * A failing `seek` has no side effects: seek(w, 6) # throws BadSeek Before, it first flushed "hello" to the inner IO. Now the data stays buffered and the writer is unchanged. * `seek` no longer flushes the wrapped IO, only writes its buffer to it. 100 calls to `seek(w, 0); write(w, "H")` called `flush` on the wrapped IO 100 times before, and 0 times now. Also: * Document the requirements on the IO wrapped by `BufWriter` for seeking: writes overwrite, seeking never truncates, `filesize` includes data beyond `position`, and no append mode. * `seek(::BufReader)` skips the `filesize` call when seeking backwards, and documents that seeking requires `seek`, `filesize` and `position` of the wrapped IO. * Fix typos in the `drop_own` docstring.
Before, BufferIO strived for interoperability with Base's IO, allowing some
code to be generic over Union{IO, AbstractBufReader} (and similar for
writers). However, semantics differed for some functions.
This turned into a hot mess since generic code would be filled with land mines
where semantics differed, and it created a constant pull towards making
BufferIO Base compatible, which goes agains the whole idea of this package,
namely improving on Base's IO semantics.
In this commit:
* Implement Base overloads where they do not conflict with documented
Base semantics. They may conflict with any concrete implementation in Base.
* Rename Base methods which violated Base's semantics to new BufferIO-owned
functions
* As part of this, make the new BufferIO functions take concrete types
jakobnissen
marked this pull request as ready for review
October 23, 2026 19:54
unsafe_read_all! is BufferIO's own function, so it takes concrete types, and BufferIO only reads bytes. The untyped method also accepted e.g. a String, which it would silently mutate.
BufferIO only reads and writes bytes, so unsafe_write no longer accepts a Ref or anything else that converts to a pointer. Overloads of Base functions may support fewer argument types than Base, since a MethodError does not violate Base's semantics. AGENTS.md is reworded accordingly. The write_integer docs example now writes its slow path byte by byte, in little-endian order like its fast path.
A reader whose fill_buffer adds exactly one given chunk of data at a time to its unbounded buffer, to test that generic code handles data arriving in pieces.
Re-add these removed methods, but with Base semantics. Also, align the `discard` function names to the read function's semantics, where the _all and _exact suffixes have a certain meaning.
It was already mentioned to be not generically implemented in its docstring. Truth is: It doesn't make sense for AbstractBufWriter in general. It's specific for writers that wrap an underlying IO, such as BufWriter. I think I believed it was generic because BufWriter was the first writer I implemented.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.