diff --git a/src/bytes.rs b/src/bytes.rs index 89e2d826..0234ba9d 100644 --- a/src/bytes.rs +++ b/src/bytes.rs @@ -227,16 +227,38 @@ pub trait Bytes { /// Returns the number of bytes written. The number of bytes written can /// be less than the length of the slice if there isn't enough room in the /// container. + /// + /// If the given slice is empty (e.g. has length 0), always returns `Ok(0)`, even if `addr` + /// is otherwise out of bounds. However, if the container is empty, it will + /// return an error (unless the slice is also empty, in which case the above takes precedence). + /// + /// ```rust + /// # use vm_memory::{Bytes, VolatileMemoryError, VolatileSlice}; + /// let mut arr = [1, 2, 3, 4, 5]; + /// let slice = VolatileSlice::from(arr.as_mut_slice()); + /// + /// assert_eq!(slice.write(&[1, 2, 3], 0).unwrap(), 3); + /// assert_eq!(slice.write(&[1, 2, 3], 3).unwrap(), 2); + /// assert!(matches!(slice.write(&[1, 2, 3], 5).unwrap_err(), VolatileMemoryError::OutOfBounds {addr: 5})); + /// assert_eq!(slice.write(&[], 5).unwrap(), 0); + /// ``` fn write(&self, buf: &[u8], addr: A) -> Result; /// Reads data from the container at `addr` into a slice. /// /// Returns the number of bytes read. The number of bytes read can be less than the length /// of the slice if there isn't enough data within the container. + /// + /// If the given slice is empty (e.g. has length 0), always returns `Ok(0)`, even if `addr` + /// is otherwise out of bounds. However, if the container is empty, it will + /// return an error (unless the slice is also empty, in which case the above takes precedence). fn read(&self, buf: &mut [u8], addr: A) -> Result; /// Writes the entire content of a slice into the container at `addr`. /// + /// If the given slice is empty (e.g. has length 0), always returns `Ok(0)`, even if `addr` + /// is otherwise out of bounds. + /// /// # Errors /// /// Returns an error if there isn't enough space within the container to write the entire slice. @@ -245,6 +267,9 @@ pub trait Bytes { /// Reads data from the container at `addr` to fill an entire slice. /// + /// If the given slice is empty (e.g. has length 0), always returns `Ok(0)`, even if `addr` + /// is otherwise out of bounds. + /// /// # Errors /// /// Returns an error if there isn't enough data within the container to fill the entire slice.