armv7a/usr/lib/rustlib/src/rust/library/std/src/io/readbuf.rs - manifest_repos/toolchain - Git at Google

 #![unstable(feature = "read_buf", issue = "78485")]

 #[cfg(test)]
 mod tests;

 use crate::fmt::{self, Debug, Formatter};
 use crate::io::{Result, Write};
 use crate::mem::{self, MaybeUninit};
 use crate::{cmp, ptr};

 /// A borrowed byte buffer which is incrementally filled and initialized.
 ///
 /// This type is a sort of "double cursor". It tracks three regions in the buffer: a region at the beginning of the
 /// buffer that has been logically filled with data, a region that has been initialized at some point but not yet
 /// logically filled, and a region at the end that is fully uninitialized. The filled region is guaranteed to be a
 /// subset of the initialized region.
 ///
 /// In summary, the contents of the buffer can be visualized as:
 /// ```not_rust
 /// [             capacity              ]
 /// [ filled |         unfilled         ]
 /// [    initialized    | uninitialized ]
 /// ```
 ///
 /// A `BorrowedBuf` is created around some existing data (or capacity for data) via a unique reference
 /// (`&mut`). The `BorrowedBuf` can be configured (e.g., using `clear` or `set_init`), but cannot be
 /// directly written. To write into the buffer, use `unfilled` to create a `BorrowedCursor`. The cursor
 /// has write-only access to the unfilled portion of the buffer (you can think of it as a
 /// write-only iterator).
 ///
 /// The lifetime `'data` is a bound on the lifetime of the underlying data.
 pub struct BorrowedBuf<'data> {
     /// The buffer's underlying data.
     buf: &'data mut [MaybeUninit<u8>],
     /// The length of `self.buf` which is known to be filled.
     filled: usize,
     /// The length of `self.buf` which is known to be initialized.
     init: usize,
 }

 impl Debug for BorrowedBuf<'_> {
     fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
         f.debug_struct("BorrowedBuf")
             .field("init", &self.init)
             .field("filled", &self.filled)
             .field("capacity", &self.capacity())
             .finish()
     }
 }

 /// Create a new `BorrowedBuf` from a fully initialized slice.
 impl<'data> From<&'data mut [u8]> for BorrowedBuf<'data> {
     #[inline]
     fn from(slice: &'data mut [u8]) -> BorrowedBuf<'data> {
         let len = slice.len();

         BorrowedBuf {
             // SAFETY: initialized data never becoming uninitialized is an invariant of BorrowedBuf
             buf: unsafe { (slice as *mut [u8]).as_uninit_slice_mut().unwrap() },
             filled: 0,
             init: len,
         }
     }
 }

 /// Create a new `BorrowedBuf` from an uninitialized buffer.
 ///
 /// Use `set_init` if part of the buffer is known to be already initialized.
 impl<'data> From<&'data mut [MaybeUninit<u8>]> for BorrowedBuf<'data> {
     #[inline]
     fn from(buf: &'data mut [MaybeUninit<u8>]) -> BorrowedBuf<'data> {
         BorrowedBuf { buf, filled: 0, init: 0 }
     }
 }

 impl<'data> BorrowedBuf<'data> {
     /// Returns the total capacity of the buffer.
     #[inline]
     pub fn capacity(&self) -> usize {
         self.buf.len()
     }

     /// Returns the length of the filled part of the buffer.
     #[inline]
     pub fn len(&self) -> usize {
         self.filled
     }

     /// Returns the length of the initialized part of the buffer.
     #[inline]
     pub fn init_len(&self) -> usize {
         self.init
     }

     /// Returns a shared reference to the filled portion of the buffer.
     #[inline]
     pub fn filled(&self) -> &[u8] {
         // SAFETY: We only slice the filled part of the buffer, which is always valid
         unsafe { MaybeUninit::slice_assume_init_ref(&self.buf[0..self.filled]) }
     }

     /// Returns a cursor over the unfilled part of the buffer.
     #[inline]
     pub fn unfilled<'this>(&'this mut self) -> BorrowedCursor<'this> {
         BorrowedCursor {
             start: self.filled,
             // SAFETY: we never assign into `BorrowedCursor::buf`, so treating its
             // lifetime covariantly is safe.
             buf: unsafe {
                 mem::transmute::<&'this mut BorrowedBuf<'data>, &'this mut BorrowedBuf<'this>>(self)
             },
         }
     }

     /// Clears the buffer, resetting the filled region to empty.
     ///
     /// The number of initialized bytes is not changed, and the contents of the buffer are not modified.
     #[inline]
     pub fn clear(&mut self) -> &mut Self {
         self.filled = 0;
         self
     }

     /// Asserts that the first `n` bytes of the buffer are initialized.
     ///
     /// `BorrowedBuf` assumes that bytes are never de-initialized, so this method does nothing when called with fewer
     /// bytes than are already known to be initialized.
     ///
     /// # Safety
     ///
     /// The caller must ensure that the first `n` unfilled bytes of the buffer have already been initialized.
     #[inline]
     pub unsafe fn set_init(&mut self, n: usize) -> &mut Self {
         self.init = cmp::max(self.init, n);
         self
     }
 }

 /// A writeable view of the unfilled portion of a [`BorrowedBuf`](BorrowedBuf).
 ///
 /// Provides access to the initialized and uninitialized parts of the underlying `BorrowedBuf`.
 /// Data can be written directly to the cursor by using [`append`](BorrowedCursor::append) or
 /// indirectly by getting a slice of part or all of the cursor and writing into the slice. In the
 /// indirect case, the caller must call [`advance`](BorrowedCursor::advance) after writing to inform
 /// the cursor how many bytes have been written.
 ///
 /// Once data is written to the cursor, it becomes part of the filled portion of the underlying
 /// `BorrowedBuf` and can no longer be accessed or re-written by the cursor. I.e., the cursor tracks
 /// the unfilled part of the underlying `BorrowedBuf`.
 ///
 /// The lifetime `'a` is a bound on the lifetime of the underlying buffer (which means it is a bound
 /// on the data in that buffer by transitivity).
 #[derive(Debug)]
 pub struct BorrowedCursor<'a> {
     /// The underlying buffer.
     // Safety invariant: we treat the type of buf as covariant in the lifetime of `BorrowedBuf` when
     // we create a `BorrowedCursor`. This is only safe if we never replace `buf` by assigning into
     // it, so don't do that!
     buf: &'a mut BorrowedBuf<'a>,
     /// The length of the filled portion of the underlying buffer at the time of the cursor's
     /// creation.
     start: usize,
 }

 impl<'a> BorrowedCursor<'a> {
     /// Reborrow this cursor by cloning it with a smaller lifetime.
     ///
     /// Since a cursor maintains unique access to its underlying buffer, the borrowed cursor is
     /// not accessible while the new cursor exists.
     #[inline]
     pub fn reborrow<'this>(&'this mut self) -> BorrowedCursor<'this> {
         BorrowedCursor {
             // SAFETY: we never assign into `BorrowedCursor::buf`, so treating its
             // lifetime covariantly is safe.
             buf: unsafe {
                 mem::transmute::<&'this mut BorrowedBuf<'a>, &'this mut BorrowedBuf<'this>>(
                     self.buf,
                 )
             },
             start: self.start,
         }
     }

     /// Returns the available space in the cursor.
     #[inline]
     pub fn capacity(&self) -> usize {
         self.buf.capacity() - self.buf.filled
     }

     /// Returns the number of bytes written to this cursor since it was created from a `BorrowedBuf`.
     ///
     /// Note that if this cursor is a reborrowed clone of another, then the count returned is the
     /// count written via either cursor, not the count since the cursor was reborrowed.
     #[inline]
     pub fn written(&self) -> usize {
         self.buf.filled - self.start
     }

     /// Returns a shared reference to the initialized portion of the cursor.
     #[inline]
     pub fn init_ref(&self) -> &[u8] {
         // SAFETY: We only slice the initialized part of the buffer, which is always valid
         unsafe { MaybeUninit::slice_assume_init_ref(&self.buf.buf[self.buf.filled..self.buf.init]) }
     }

     /// Returns a mutable reference to the initialized portion of the cursor.
     #[inline]
     pub fn init_mut(&mut self) -> &mut [u8] {
         // SAFETY: We only slice the initialized part of the buffer, which is always valid
         unsafe {
             MaybeUninit::slice_assume_init_mut(&mut self.buf.buf[self.buf.filled..self.buf.init])
         }
     }

     /// Returns a mutable reference to the uninitialized part of the cursor.
     ///
     /// It is safe to uninitialize any of these bytes.
     #[inline]
     pub fn uninit_mut(&mut self) -> &mut [MaybeUninit<u8>] {
         &mut self.buf.buf[self.buf.init..]
     }

     /// Returns a mutable reference to the whole cursor.
     ///
     /// # Safety
     ///
     /// The caller must not uninitialize any bytes in the initialized portion of the cursor.
     #[inline]
     pub unsafe fn as_mut(&mut self) -> &mut [MaybeUninit<u8>] {
         &mut self.buf.buf[self.buf.filled..]
     }

     /// Advance the cursor by asserting that `n` bytes have been filled.
     ///
     /// After advancing, the `n` bytes are no longer accessible via the cursor and can only be
     /// accessed via the underlying buffer. I.e., the buffer's filled portion grows by `n` elements
     /// and its unfilled portion (and the capacity of this cursor) shrinks by `n` elements.
     ///
     /// # Safety
     ///
     /// The caller must ensure that the first `n` bytes of the cursor have been properly
     /// initialised.
     #[inline]
     pub unsafe fn advance(&mut self, n: usize) -> &mut Self {
         self.buf.filled += n;
         self.buf.init = cmp::max(self.buf.init, self.buf.filled);
         self
     }

     /// Initializes all bytes in the cursor.
     #[inline]
     pub fn ensure_init(&mut self) -> &mut Self {
         let uninit = self.uninit_mut();
         // SAFETY: 0 is a valid value for MaybeUninit<u8> and the length matches the allocation
         // since it is comes from a slice reference.
         unsafe {
             ptr::write_bytes(uninit.as_mut_ptr(), 0, uninit.len());
         }
         self.buf.init = self.buf.capacity();

         self
     }

     /// Asserts that the first `n` unfilled bytes of the cursor are initialized.
     ///
     /// `BorrowedBuf` assumes that bytes are never de-initialized, so this method does nothing when
     /// called with fewer bytes than are already known to be initialized.
     ///
     /// # Safety
     ///
     /// The caller must ensure that the first `n` bytes of the buffer have already been initialized.
     #[inline]
     pub unsafe fn set_init(&mut self, n: usize) -> &mut Self {
         self.buf.init = cmp::max(self.buf.init, self.buf.filled + n);
         self
     }

     /// Appends data to the cursor, advancing position within its buffer.
     ///
     /// # Panics
     ///
     /// Panics if `self.capacity()` is less than `buf.len()`.
     #[inline]
     pub fn append(&mut self, buf: &[u8]) {
         assert!(self.capacity() >= buf.len());

         // SAFETY: we do not de-initialize any of the elements of the slice
         unsafe {
             MaybeUninit::write_slice(&mut self.as_mut()[..buf.len()], buf);
         }

         // SAFETY: We just added the entire contents of buf to the filled section.
         unsafe {
             self.set_init(buf.len());
         }
         self.buf.filled += buf.len();
     }
 }

 impl<'a> Write for BorrowedCursor<'a> {
     fn write(&mut self, buf: &[u8]) -> Result<usize> {
         self.append(buf);
         Ok(buf.len())
     }

     fn flush(&mut self) -> Result<()> {
         Ok(())
     }
 }
	#![unstable(feature = "read_buf", issue = "78485")]

	#[cfg(test)]
	mod tests;

	use crate::fmt::{self, Debug, Formatter};
	use crate::io::{Result, Write};
	use crate::mem::{self, MaybeUninit};
	use crate::{cmp, ptr};

	/// A borrowed byte buffer which is incrementally filled and initialized.
	///
	/// This type is a sort of "double cursor". It tracks three regions in the buffer: a region at the beginning of the
	/// buffer that has been logically filled with data, a region that has been initialized at some point but not yet
	/// logically filled, and a region at the end that is fully uninitialized. The filled region is guaranteed to be a
	/// subset of the initialized region.
	///
	/// In summary, the contents of the buffer can be visualized as:
	/// ```not_rust
	/// [ capacity ]
	/// [ filled \| unfilled ]
	/// [ initialized \| uninitialized ]
	/// ```
	///
	/// A `BorrowedBuf` is created around some existing data (or capacity for data) via a unique reference
	/// (`&mut`). The `BorrowedBuf` can be configured (e.g., using `clear` or `set_init`), but cannot be
	/// directly written. To write into the buffer, use `unfilled` to create a `BorrowedCursor`. The cursor
	/// has write-only access to the unfilled portion of the buffer (you can think of it as a
	/// write-only iterator).
	///
	/// The lifetime `'data` is a bound on the lifetime of the underlying data.
	pub struct BorrowedBuf<'data> {
	/// The buffer's underlying data.
	buf: &'data mut [MaybeUninit<u8>],
	/// The length of `self.buf` which is known to be filled.
	filled: usize,
	/// The length of `self.buf` which is known to be initialized.
	init: usize,
	}

	impl Debug for BorrowedBuf<'_> {
	fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
	f.debug_struct("BorrowedBuf")
	.field("init", &self.init)
	.field("filled", &self.filled)
	.field("capacity", &self.capacity())
	.finish()
	}
	}

	/// Create a new `BorrowedBuf` from a fully initialized slice.
	impl<'data> From<&'data mut [u8]> for BorrowedBuf<'data> {
	#[inline]
	fn from(slice: &'data mut [u8]) -> BorrowedBuf<'data> {
	let len = slice.len();

	BorrowedBuf {
	// SAFETY: initialized data never becoming uninitialized is an invariant of BorrowedBuf
	buf: unsafe { (slice as *mut [u8]).as_uninit_slice_mut().unwrap() },
	filled: 0,
	init: len,
	}
	}
	}

	/// Create a new `BorrowedBuf` from an uninitialized buffer.
	///
	/// Use `set_init` if part of the buffer is known to be already initialized.
	impl<'data> From<&'data mut [MaybeUninit<u8>]> for BorrowedBuf<'data> {
	#[inline]
	fn from(buf: &'data mut [MaybeUninit<u8>]) -> BorrowedBuf<'data> {
	BorrowedBuf { buf, filled: 0, init: 0 }
	}
	}

	impl<'data> BorrowedBuf<'data> {
	/// Returns the total capacity of the buffer.
	#[inline]
	pub fn capacity(&self) -> usize {
	self.buf.len()
	}

	/// Returns the length of the filled part of the buffer.
	#[inline]
	pub fn len(&self) -> usize {
	self.filled
	}

	/// Returns the length of the initialized part of the buffer.
	#[inline]
	pub fn init_len(&self) -> usize {
	self.init
	}

	/// Returns a shared reference to the filled portion of the buffer.
	#[inline]
	pub fn filled(&self) -> &[u8] {
	// SAFETY: We only slice the filled part of the buffer, which is always valid
	unsafe { MaybeUninit::slice_assume_init_ref(&self.buf[0..self.filled]) }
	}

	/// Returns a cursor over the unfilled part of the buffer.
	#[inline]
	pub fn unfilled<'this>(&'this mut self) -> BorrowedCursor<'this> {
	BorrowedCursor {
	start: self.filled,
	// SAFETY: we never assign into `BorrowedCursor::buf`, so treating its
	// lifetime covariantly is safe.
	buf: unsafe {
	mem::transmute::<&'this mut BorrowedBuf<'data>, &'this mut BorrowedBuf<'this>>(self)
	},
	}
	}

	/// Clears the buffer, resetting the filled region to empty.
	///
	/// The number of initialized bytes is not changed, and the contents of the buffer are not modified.
	#[inline]
	pub fn clear(&mut self) -> &mut Self {
	self.filled = 0;
	self
	}

	/// Asserts that the first `n` bytes of the buffer are initialized.
	///
	/// `BorrowedBuf` assumes that bytes are never de-initialized, so this method does nothing when called with fewer
	/// bytes than are already known to be initialized.
	///
	/// # Safety
	///
	/// The caller must ensure that the first `n` unfilled bytes of the buffer have already been initialized.
	#[inline]
	pub unsafe fn set_init(&mut self, n: usize) -> &mut Self {
	self.init = cmp::max(self.init, n);
	self
	}
	}

	/// A writeable view of the unfilled portion of a [`BorrowedBuf`](BorrowedBuf).
	///
	/// Provides access to the initialized and uninitialized parts of the underlying `BorrowedBuf`.
	/// Data can be written directly to the cursor by using [`append`](BorrowedCursor::append) or
	/// indirectly by getting a slice of part or all of the cursor and writing into the slice. In the
	/// indirect case, the caller must call [`advance`](BorrowedCursor::advance) after writing to inform
	/// the cursor how many bytes have been written.
	///
	/// Once data is written to the cursor, it becomes part of the filled portion of the underlying
	/// `BorrowedBuf` and can no longer be accessed or re-written by the cursor. I.e., the cursor tracks
	/// the unfilled part of the underlying `BorrowedBuf`.
	///
	/// The lifetime `'a` is a bound on the lifetime of the underlying buffer (which means it is a bound
	/// on the data in that buffer by transitivity).
	#[derive(Debug)]
	pub struct BorrowedCursor<'a> {
	/// The underlying buffer.
	// Safety invariant: we treat the type of buf as covariant in the lifetime of `BorrowedBuf` when
	// we create a `BorrowedCursor`. This is only safe if we never replace `buf` by assigning into
	// it, so don't do that!
	buf: &'a mut BorrowedBuf<'a>,
	/// The length of the filled portion of the underlying buffer at the time of the cursor's
	/// creation.
	start: usize,
	}

	impl<'a> BorrowedCursor<'a> {
	/// Reborrow this cursor by cloning it with a smaller lifetime.
	///
	/// Since a cursor maintains unique access to its underlying buffer, the borrowed cursor is
	/// not accessible while the new cursor exists.
	#[inline]
	pub fn reborrow<'this>(&'this mut self) -> BorrowedCursor<'this> {
	BorrowedCursor {
	// SAFETY: we never assign into `BorrowedCursor::buf`, so treating its
	// lifetime covariantly is safe.
	buf: unsafe {
	mem::transmute::<&'this mut BorrowedBuf<'a>, &'this mut BorrowedBuf<'this>>(
	self.buf,
	)
	},
	start: self.start,
	}
	}

	/// Returns the available space in the cursor.
	#[inline]
	pub fn capacity(&self) -> usize {
	self.buf.capacity() - self.buf.filled
	}

	/// Returns the number of bytes written to this cursor since it was created from a `BorrowedBuf`.
	///
	/// Note that if this cursor is a reborrowed clone of another, then the count returned is the
	/// count written via either cursor, not the count since the cursor was reborrowed.
	#[inline]
	pub fn written(&self) -> usize {
	self.buf.filled - self.start
	}

	/// Returns a shared reference to the initialized portion of the cursor.
	#[inline]
	pub fn init_ref(&self) -> &[u8] {
	// SAFETY: We only slice the initialized part of the buffer, which is always valid
	unsafe { MaybeUninit::slice_assume_init_ref(&self.buf.buf[self.buf.filled..self.buf.init]) }
	}

	/// Returns a mutable reference to the initialized portion of the cursor.
	#[inline]
	pub fn init_mut(&mut self) -> &mut [u8] {
	// SAFETY: We only slice the initialized part of the buffer, which is always valid
	unsafe {
	MaybeUninit::slice_assume_init_mut(&mut self.buf.buf[self.buf.filled..self.buf.init])
	}
	}

	/// Returns a mutable reference to the uninitialized part of the cursor.
	///
	/// It is safe to uninitialize any of these bytes.
	#[inline]
	pub fn uninit_mut(&mut self) -> &mut [MaybeUninit<u8>] {
	&mut self.buf.buf[self.buf.init..]
	}

	/// Returns a mutable reference to the whole cursor.
	///
	/// # Safety
	///
	/// The caller must not uninitialize any bytes in the initialized portion of the cursor.
	#[inline]
	pub unsafe fn as_mut(&mut self) -> &mut [MaybeUninit<u8>] {
	&mut self.buf.buf[self.buf.filled..]
	}

	/// Advance the cursor by asserting that `n` bytes have been filled.
	///
	/// After advancing, the `n` bytes are no longer accessible via the cursor and can only be
	/// accessed via the underlying buffer. I.e., the buffer's filled portion grows by `n` elements
	/// and its unfilled portion (and the capacity of this cursor) shrinks by `n` elements.
	///
	/// # Safety
	///
	/// The caller must ensure that the first `n` bytes of the cursor have been properly
	/// initialised.
	#[inline]
	pub unsafe fn advance(&mut self, n: usize) -> &mut Self {
	self.buf.filled += n;
	self.buf.init = cmp::max(self.buf.init, self.buf.filled);
	self
	}

	/// Initializes all bytes in the cursor.
	#[inline]
	pub fn ensure_init(&mut self) -> &mut Self {
	let uninit = self.uninit_mut();
	// SAFETY: 0 is a valid value for MaybeUninit<u8> and the length matches the allocation
	// since it is comes from a slice reference.
	unsafe {
	ptr::write_bytes(uninit.as_mut_ptr(), 0, uninit.len());
	}
	self.buf.init = self.buf.capacity();

	self
	}

	/// Asserts that the first `n` unfilled bytes of the cursor are initialized.
	///
	/// `BorrowedBuf` assumes that bytes are never de-initialized, so this method does nothing when
	/// called with fewer bytes than are already known to be initialized.
	///
	/// # Safety
	///
	/// The caller must ensure that the first `n` bytes of the buffer have already been initialized.
	#[inline]
	pub unsafe fn set_init(&mut self, n: usize) -> &mut Self {
	self.buf.init = cmp::max(self.buf.init, self.buf.filled + n);
	self
	}

	/// Appends data to the cursor, advancing position within its buffer.
	///
	/// # Panics
	///
	/// Panics if `self.capacity()` is less than `buf.len()`.
	#[inline]
	pub fn append(&mut self, buf: &[u8]) {
	assert!(self.capacity() >= buf.len());

	// SAFETY: we do not de-initialize any of the elements of the slice
	unsafe {
	MaybeUninit::write_slice(&mut self.as_mut()[..buf.len()], buf);
	}

	// SAFETY: We just added the entire contents of buf to the filled section.
	unsafe {
	self.set_init(buf.len());
	}
	self.buf.filled += buf.len();
	}
	}

	impl<'a> Write for BorrowedCursor<'a> {
	fn write(&mut self, buf: &[u8]) -> Result<usize> {
	self.append(buf);
	Ok(buf.len())
	}

	fn flush(&mut self) -> Result<()> {
	Ok(())
	}
	}