Add read_to method for zero-allocation reads 🙋

Cargo.toml

@@ -6,7 +6,7 @@ license = "MIT OR Apache-2.0"
 name = "random-access-disk"
 readme = "README.md"
 repository = "https://github.com/datrs/random-access-disk"
-version = "3.0.1"
+version = "3.1.0"
 edition = "2021"
 
 [dependencies]

src/lib.rs

@@ -197,6 +197,30 @@ impl RandomAccessDisk {
   pub fn builder(filename: impl AsRef<path::Path>) -> Builder {
     Builder::new(filename)
   }
+
+  /// Read bytes at `offset` into the provided `buf`.
+  ///
+  /// Returns the number of bytes read. This avoids allocating a new buffer
+  /// on each read, unlike [`RandomAccess::read`].
+  pub async fn read_to(
+    &mut self,
+    offset: u64,
+    buf: &mut [u8],
+  ) -> Result<usize, RandomAccessError> {
+    let length = buf.len() as u64;
+    if offset + length > self.length {
+      return Err(RandomAccessError::OutOfBounds {
+        offset,
+        end: Some(offset + length),
+        length: self.length,
+      });
+    }
+
+    let file = self.file.as_mut().expect("self.file was None.");
+    file.seek(SeekFrom::Start(offset)).await?;
+    let bytes_read = file.read(buf).await?;
+    Ok(bytes_read)
+  }
 }
 
 #[async_trait::async_trait]
@@ -235,18 +259,8 @@ impl RandomAccess for RandomAccessDisk {
     offset: u64,
     length: u64,
   ) -> Result<Vec<u8>, RandomAccessError> {
-    if offset + length > self.length {
-      return Err(RandomAccessError::OutOfBounds {
-        offset,
-        end: Some(offset + length),
-        length: self.length,
-      });
-    }
-
-    let file = self.file.as_mut().expect("self.file was None.");
     let mut buffer = vec![0; length as usize];
-    file.seek(SeekFrom::Start(offset)).await?;
-    let _bytes_read = file.read(&mut buffer[..]).await?;
+    self.read_to(offset, &mut buffer).await?;
     Ok(buffer)
   }
 

tests/test.rs

@@ -371,3 +371,50 @@ async fn can_del_long_more_than_block() {
     .unwrap();
   assert_eq!(5, file.len().await.unwrap());
 }
+
+#[async_test]
+async fn can_read_to() {
+  let dir = Builder::new()
+    .prefix("random-access-disk")
+    .tempdir()
+    .unwrap();
+  let mut file = rad::RandomAccessDisk::open(dir.path().join("17.db"))
+    .await
+    .unwrap();
+  file.write(0, b"hello").await.unwrap();
+  file.write(5, b" world").await.unwrap();
+  let mut buf = [0u8; 11];
+  let bytes_read = file.read_to(0, &mut buf).await.unwrap();
+  assert_eq!(bytes_read, 11);
+  assert_eq!(&buf, b"hello world");
+}
+
+#[async_test]
+async fn can_read_to_partial() {
+  let dir = Builder::new()
+    .prefix("random-access-disk")
+    .tempdir()
+    .unwrap();
+  let mut file = rad::RandomAccessDisk::open(dir.path().join("18.db"))
+    .await
+    .unwrap();
+  file.write(0, b"hello world").await.unwrap();
+  let mut buf = [0u8; 5];
+  let bytes_read = file.read_to(6, &mut buf).await.unwrap();
+  assert_eq!(bytes_read, 5);
+  assert_eq!(&buf, b"world");
+}
+
+#[async_test]
+async fn read_to_out_of_bounds() {
+  let dir = Builder::new()
+    .prefix("random-access-disk")
+    .tempdir()
+    .unwrap();
+  let mut file = rad::RandomAccessDisk::open(dir.path().join("19.db"))
+    .await
+    .unwrap();
+  file.write(0, b"hello").await.unwrap();
+  let mut buf = [0u8; 10];
+  assert!(file.read_to(0, &mut buf).await.is_err());
+}