Tracking Issue for io::Cursor::{split, split_mut}

Feature gate: #![feature(cursor_split)]

impl<T> Cursor<T>
where
    T: AsRef<[u8]>,
{
    pub fn split(&self) -> (&[u8], &[u8]);
}

impl<T> Cursor<T>
where
    T: AsMut<[u8]>,
{
    pub fn split_mut(&mut self) -> (&mut [u8], &mut [u8]);
}

Steps / History

Add io::Cursor::{remaining, remaining_slice, is_empty} #86037
Replace io::Cursor::{remaining_slice, is_empty} #109174
Final commenting period (FCP)
Stabilization PR

Unresolved Questions/Issues

~~name remaining Add io::Cursor::{remaining, remaining_slice, is_empty} #86037 (comment)~~
~~change signature of remaining to return usize. Tracking Issue for io::Cursor::{split, split_mut} #86369 (comment)~~
~~conflict with <Cursor as bytes::Buf>::remaining Tracking Issue for io::Cursor::{split, split_mut} #86369 (comment)~~

@mystor

One additional concern that @mystor pointed out is that stabilizing these APIs might prevent us from adding support to non-contiguous buffers/sets of buffers to Cursor in the future. The remaining method wouldn't translate, since it returns a single slice.

We should be absolutely certain that we don't intend to extend Cursor this way in the future or we may wish to just stick with the usize returning version for now, since that one would have solved the original motivating example and it can be extended to work for multiple non-contiguous buffers.

Wouldn't that still work though? Since those contiguous buffers won't implement AsRef<[u8]>.
To make it clear that this function only returns a slice we could rename it as suggested to remaining_slice and then the implementation for contiguous buffers could have a method named for example remaining_slices.

Wouldn't that still work though? Since those contiguous buffers won't implement AsRef<[u8]>.

Oh, I had forgotten that remaining also had the as_ref bound. Yea, that should work fine.

To make it clear that this function only returns a slice we could rename it as suggested to remaining_slice and then the implementation for contiguous buffers could have a method named for example remaining_slices.

Sounds like a plan!

I renamed remaining to remaining_slice and added:

fn remaining(&self) -> u64;

Is that ok or should i remove it again?

Is that ok or should i remove it again?

sounds great

Rollup merge of rust-lang#86037 - soerenmeier:cursor_remaining, r=yaahc

I'll just note that this change conflicts with bytes::Buf that is implemented for Cursor<impl AsRef<[u8]>>. The proposed remaining method here has a different signature, so shadowing won't work. While adding this method may be desired and ultimately the right decision (I haven't thought enough to say myself), it will have an impact on the ecosystem using bytes::Buf.

I've also noticed an inconvenience that won't affect stable: since the method is "unstable" on nightly, it triggers an error, even though the trait is in scope.

That seems unfortunate. I'd be okay with changing the signature to return a usize, I chose u64 since position is u64 but since the underlying slice cannot be bigger than usize it would be possible to change the signature. The only point to consider is if support for non-contiguous buffers is added the length could be bigger than usize, but that also could be a problem with u64.

About the error in nightly, I don't know how this is handled normally in std. But the impact should be rather small, since Cursor is only scarcely used, mostly in tests. Am I wrong?

I don't mean an error in libstd or it's test suite. But rather the greater ecosystem, anywhere using bytes::Buf and also running tests on nightly. For example, this PR for h2: hyperium/h2#547

I didn't either. I meant the use of Cursor in combination with bytes::Buf on nightly calling remaining. After your first comment i made a few short searches concluding with the statement above, interpreting your reaction, that was probably the wrong assessment. Imho failing nightly tests should be acceptable but addressed (if stable is the target).
Do you have a suggestion to solve this?

If we have an is_empty method, we probably should have a len method. (And it looks like that's what remaining was before it was removed. So I wonder whether that should be added back as len.)

Note that the length of the underlying buffer doesn't change when reading or writing or seeking through it. The only thing that changes is the position of the cursor, and the bytes in the buffer (when writing). (E.g. seeking to the beginning will 'unempty' it and produce the already read data again.)

I really like that, looking at the cursor symmetrically. You're talking about something like this?

pub struct Cursor<T> {
    pub fn remaining(&self) -> &[u8];
    pub fn remaining_mut(&mut self) -> &mut [u8];
    pub fn preceding(&self) -> &[u8];
    pub fn preceding_mut(&mut self) -> &mut [u8];
    pub fn split_at(&self) -> (&[u8], &[u8]);
    pub fn split_at_mut(&mut self) -> (&mut [u8], &mut [u8]);
}

@rfcbot

It doesn't look like this will go through in its current form, so I'm cancelling the proposed FCP.

@rfcbot cancel

@jkugelman Yeah, something like that. Or before_cursor, after_cursor and split_at_cursor or something in that direction. As long as it makes sense from both a Read and Write perspective (+Seek).

@m-ou-se

@m-ou-se proposal cancelled.

Stumbled upon these functions today. Considering the concerns, would it be worth removing the current implementation?

I once made a commit with possible alternatives but wasn't sure about if the implementation should not be generic over T: AsRef<[u8]>. That would allow to return different lifetimes for example for Cursor<&'a [u8]> so the function could look like fn split(&self) -> (&'a [u8], &'a [u8]);. That was one concern raised in #86369 (comment).

My Implementation was based on these functions:

fn split(&self) -> (&[u8], &[u8]);
fn before(&self) -> &[u8];
fn after(&self) -> &[u8];
fn split_mut(&mut self) -> (&mut [u8], &mut [u8]);
fn before_mut(&mut self) -> &mut [u8];
fn after_mut(&mut self) -> &mut [u8];

Commit: soerenmeier@eab83e3

Rollup merge of rust-lang#109174 - soerenmeier:cursor_fns, r=dtolnay

Unrolled build for rust-lang#109174

Rollup merge of rust-lang#86037 - soerenmeier:cursor_remaining, r=yaahc

Navigation Menu

Repository navigation

Tracking Issue for `io::Cursor::{split, split_mut}` #86369

Steps / History

Unresolved Questions/Issues

17 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Tracking Issue for io::Cursor::{split, split_mut} #86369

Description

Steps / History

Unresolved Questions/Issues

Activity

yaahc commented on Jun 16, 2021

soerenmeier commented on Jun 16, 2021

yaahc commented on Jun 16, 2021

soerenmeier commented on Jun 17, 2021

yaahc commented on Jun 17, 2021

seanmonstar commented on Jun 24, 2021

soerenmeier commented on Jun 24, 2021

seanmonstar commented on Jun 25, 2021

soerenmeier commented on Jun 25, 2021

17 remaining items

m-ou-se commented on Oct 27, 2021

jkugelman commented on Oct 28, 2021

m-ou-se commented on Jan 12, 2022

rfcbot commented on Jan 12, 2022

glandium commented on Jul 8, 2022

soerenmeier commented on Jul 8, 2022

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

Tracking Issue for `io::Cursor::{split, split_mut}` #86369