From 413930ea2a0700e56d1e2dbd2530296baa4c837d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sosth=C3=A8ne=20Gu=C3=A9don?= Date: Wed, 19 Jun 2024 16:12:34 +0200 Subject: [PATCH] Add documentation --- src/lib.rs | 122 ++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 121 insertions(+), 1 deletion(-) diff --git a/src/lib.rs b/src/lib.rs index 9222ad1..88d62a3 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -60,102 +60,222 @@ impl Bytes { self.bytes.as_ptr() } + /// Returns a raw pointer to the vector’s buffer, which may be mutated through pub fn as_mut_ptr(&mut self) -> *mut u8 { self.bytes.as_mut_ptr() } + /// Extracts a slice containing the entire buffer. pub fn as_slice(&self) -> &[u8] { self.bytes.as_slice() } + + /// Extracts a mutable slice containing the entire buffer. pub fn as_mut_slice(&mut self) -> &mut [u8] { self.bytes.as_mut_slice() } + /// Get the capacity of the buffer. + /// + /// Always equal to the `N` const generic. pub const fn capacity(&self) -> usize { self.bytes.capacity() } + /// Clear the buffer, making it empty pub fn clear(&mut self) { self.bytes.clear() } - #[deprecated(note = "Panics when out of capacity")] + /// Extends the buffer from an iterator. + /// + /// # Panic + /// + /// Panics if the buffer cannot hold all elements of the iterator. + #[deprecated( + since = "0.4.0", + note = "Panics when out of capacity, use try_extend instead" + )] pub fn extend>(&mut self, iter: I) { self.bytes.extend(iter) } + /// Extends the buffer from an iterator. + /// + /// Returns [`Err`] if out of capacity + pub fn try_extend>(&mut self, iter: I) -> Result<(), ()> { + for b in iter { + self.push(b)?; + } + Ok(()) + } + + /// Extend the buffer with the contents of a slice pub fn extend_from_slice(&mut self, other: &[u8]) -> Result<(), ()> { self.bytes.extend_from_slice(other) } + /// Removes the last byte from the buffer and returns it, or `None` if it's empty pub fn pop(&mut self) -> Option { self.bytes.pop() } + /// Appends a byte to the back of the collection pub fn push(&mut self, byte: u8) -> Result<(), ()> { self.bytes.push(byte).map_err(drop) } + /// Removes the last byte from the buffer and returns it + /// + /// # Safety + /// + /// This assumes the buffer to have at least one element. pub unsafe fn pop_unchecked(&mut self) -> u8 { unsafe { self.bytes.pop_unchecked() } } + /// Appends a byte to the back of the buffer + /// + /// # Safety + /// + /// This assumes the buffer is not full. pub unsafe fn push_unchecked(&mut self, byte: u8) { unsafe { self.bytes.push_unchecked(byte); } } + /// Shortens the buffer, keeping the first `len` elements and dropping the rest. pub fn truncate(&mut self, len: usize) { self.bytes.truncate(len) } + /// Resizes the buffer in-place so that len is equal to new_len. + /// + /// If new_len is greater than len, the buffer is extended by the + /// difference, with each additional slot filled with `value`. If + /// `new_len` is less than `len`, the buffer is simply truncated. + /// + /// See also [`resize_zero`](Self::resize_zero). pub fn resize(&mut self, new_len: usize, value: u8) -> Result<(), ()> { self.bytes.resize(new_len, value) } + /// Resizes the buffer in-place so that len is equal to new_len. + /// + /// If new_len is greater than len, the buffer is extended by the + /// difference, with each additional slot filled with `0`. If + /// `new_len` is less than `len`, the buffer is simply truncated. pub fn resize_zero(&mut self, new_len: usize) -> Result<(), ()> { self.bytes.resize_default(new_len) } + /// Forces the length of the buffer to `new_len`. + /// + /// This is a low-level operation that maintains none of the normal + /// invariants of the type. Normally changing the length of a buffer + /// is done using one of the safe operations instead, such as + /// [`truncate`], [`resize`], [`extend`], or [`clear`]. + /// + /// [`truncate`]: Self::truncate + /// [`resize`]: Self::resize + /// [`extend`]: core::iter::Extend + /// [`clear`]: Self::clear + /// + /// # Safety + /// + /// - `new_len` must be less than or equal to [`capacity()`]. + /// - The elements at `old_len..new_len` must be initialized. + /// + /// [`capacity()`]: Self::capacity + /// pub unsafe fn set_len(&mut self, new_len: usize) { self.bytes.set_len(new_len) } + /// Removes a byte from the buffer and returns it. + /// + /// The removed byte is replaced by the last byte of the vector. + /// + /// This does not preserve ordering, but is *O*(1). + /// + /// # Panics + /// + /// Panics if `index` is out of bounds. pub fn swap_remove(&mut self, index: usize) -> u8 { self.bytes.swap_remove(index) } + /// Removes a byte from the buffer and returns it. + /// + /// The removed byte is replaced by the last byte of the vector. + /// + /// This does not preserve ordering, but is *O*(1). + /// + /// # Safety + /// + /// `index` must not be out of bounds. pub unsafe fn swap_remove_unchecked(&mut self, index: usize) -> u8 { unsafe { self.bytes.swap_remove_unchecked(index) } } + /// Returns true if the buffer is full pub fn is_full(&self) -> bool { self.bytes.is_full() } + /// Returns true if the buffer is empty pub fn is_empty(&self) -> bool { self.bytes.is_empty() } + /// Returns `true` if `needle` is a prefix of the buffer. + /// + /// Always returns `true` if `needle` is an empty slice. pub fn starts_with(&self, needle: &[u8]) -> bool { self.bytes.starts_with(needle) } + + /// Returns `true` if `needle` is a suffix of the buffer. + /// + /// Always returns `true` if `needle` is an empty slice. pub fn ends_with(&self, needle: &[u8]) -> bool { self.bytes.ends_with(needle) } + /// Inserts a byte at position `index` within the buffer, shifting all + /// bytes after it to the right. + /// + /// # Panics + /// + /// Panics if `index > len`. pub fn insert(&mut self, index: usize, value: u8) -> Result<(), ()> { self.bytes.insert(index, value).map_err(drop) } + /// Removes and return the byte at position `index` within the buffer, shifting all + /// bytes after it to the left. + /// + /// # Panics + /// + /// Panics if `index > len`. pub fn remove(&mut self, index: usize) -> u8 { self.bytes.remove(index) } + /// Retains only the bytes specified by the predicate. + /// + /// In other words, remove all bytes `b` for which `f(&b)` returns `false`. + /// This method operates in place, visiting each element exactly once in the + /// original order, and preserves the order of the retained elements. pub fn retain(&mut self, f: impl FnMut(&u8) -> bool) { self.bytes.retain(f) } + /// Retains only the bytes specified by the predicate, passing a mutable reference to it. + /// + /// In other words, remove all bytes `b` for which `f(&mut b)` returns `false`. + /// This method operates in place, visiting each element exactly once in the + /// original order, and preserves the order of the retained elements. pub fn retain_mut(&mut self, f: impl FnMut(&mut u8) -> bool) { self.bytes.retain_mut(f) }