Closed a1phyr closed 2 months ago
The approach of turning a BorrowedCursor into a new BorrowedBuf seems like a good one. We discussed this in this week's libs-api meeting and agreed that we want to approve this.
I also think with_unfilled_buf
is a good helper method that will be less error-prone. The documentation for unfilled_buf
should point to that as the preferred alternative.
Proposal
Problem statement
Quoting documentation of
BorrowedCursor
:However, doing so may be really useful, for example in
Read
wrappers that read back the data read in the inner reader. With the current API,read_buf
can only be implemented by initializing the whole buffer and forwarding toread
or using unsafe code to craft a newBorrowedCursor
.Motivating examples or use cases
A crc32 checker example simplified from
zip
crate (original source):In this code, a specialized
read_buf
implementation that forward toself.inner.read_buf()
is desirable, but not really possible without unsafe code.Solution sketch
Add new method to
BorrowedCursor
that creates aBorrowedBuf
from it, which would allow reading back the written data (not tested):With this,
read_buf
function from the previous example could be written as:Alternatives
From<&'data mut BorrowCursor<'_>> for BorrowedBuf<'data>
to make it consistent with other ways to create aBorrowedBuf
As is, using
unfilled_buf
andadvance
make it compulsory to have a panic branch (inadvance
) and the risk to forget advancing (especially in error branches). There could be a method that takes a closure and does everything right:Links and related work
What happens now?
This issue contains an API change proposal (or ACP) and is part of the libs-api team feature lifecycle. Once this issue is filed, the libs-api team will review open proposals as capability becomes available. Current response times do not have a clear estimate, but may be up to several months.
Possible responses
The libs team may respond in various different ways. First, the team will consider the problem (this doesn't require any concrete solution or alternatives to have been proposed):
Second, if there's a concrete solution: