Merge pull request #41 from triblespace/codex/work-on-next-task-from-inventory

Add map_file_region helper

Author: somethingelseentirely

CHANGELOG.md

@@ -50,6 +50,7 @@
 - skip Python examples when the `pyo3` feature is disabled to fix `cargo test`
 - added `Bytes::map_file` helper for convenient file mapping
   (accepts any `memmap2::MmapAsRawDesc`, e.g. `&File` or `&NamedTempFile`)
+- added `Bytes::map_file_region` to map a specific region of a file
 - reverted automatic installation of Python development packages in the
   preflight script; rely on the system `python3-dev` package
 - set the preflight script to use Python 3.12 for building pyo3 code

INVENTORY.md

@@ -4,7 +4,6 @@
 - None at the moment.
 
 ## Desired Functionality
-- Helper `map_file_region` to map only part of a file.
 - Example demonstrating Python + winnow parsing.
 - Additional Kani proofs covering `try_unwrap_owner` and weak references.
 

README.md

@@ -98,6 +98,9 @@ fn read_header(file: &std::fs::File) -> std::io::Result<anybytes::view::View<Hea
 }
 ```
 
+To map only a portion of a file use the unsafe helper
+`Bytes::map_file_region(file, offset, len)`.
+
 ## Features
 
 By default the crate enables the `mmap` and `zerocopy` features.

src/bytes.rs

@@ -233,6 +233,31 @@ impl Bytes {
         Ok(Self::from_source(map))
     }
 
+    /// Memory-map a specific region of the given file descriptor and return the
+    /// bytes.
+    ///
+    /// # Safety
+    ///
+    /// The caller must ensure that the mapped file is not modified for the
+    /// lifetime of the returned [`Bytes`]. Changing the file contents while it
+    /// is mapped can lead to undefined behavior. The file handle does not need
+    /// to remain open after mapping. The `offset` must meet the underlying
+    /// platform's alignment requirements (typically page size).
+    ///
+    /// The argument may be any type that implements [`memmap2::MmapAsRawDesc`],
+    /// such as [`&std::fs::File`] or [`&tempfile::NamedTempFile`].
+    #[cfg(feature = "mmap")]
+    pub unsafe fn map_file_region<F>(file: F, offset: u64, len: usize) -> std::io::Result<Self>
+    where
+        F: memmap2::MmapAsRawDesc,
+    {
+        let map = memmap2::MmapOptions::new()
+            .offset(offset)
+            .len(len)
+            .map(file)?;
+        Ok(Self::from_source(map))
+    }
+
     #[inline]
     pub(crate) fn as_slice<'a>(&'a self) -> &'a [u8] {
         self.data

src/tests.rs

@@ -247,6 +247,17 @@ fn test_map_file() {
     assert_eq!(bytes.as_ref(), b"testfile");
 }
 
+#[cfg(feature = "mmap")]
+#[test]
+fn test_map_file_region() {
+    use std::io::Write;
+    let mut file = tempfile::NamedTempFile::new().expect("temp file");
+    file.write_all(b"abcdef").expect("write");
+    file.flush().unwrap();
+    let bytes = unsafe { Bytes::map_file_region(&file, 1, 3) }.expect("map file region");
+    assert_eq!(bytes.as_ref(), b"bcd");
+}
+
 #[test]
 fn test_cow_u8_owned_source() {
     use std::borrow::Cow;