Struct ndarray_npz::NpzViewMut
source · pub struct NpzViewMut<'a> { /* private fields */ }Expand description
Mutable view for memory-mapped .npz files.
The primary use-case for this is modifying .npy files within a
memory-mapped .npz archive. Modifying the elements in the view will modify
the file. Modifying the shape/strides of the view will not modify the
shape/strides of the array in the file.
Notes
- For types for which not all bit patterns are valid, such as
bool, the implementation iterates over all of the elements when creating the view to ensure they have a valid bit pattern. - The data in the buffer containing an
.npzarchive must be properly aligned for its.npyfile with the maximum alignment requirement for its element type. Typically, this should not be a concern for memory-mapped files (unless an option likeMAP_FIXEDis used), since memory mappings are usually aligned to a page boundary. - The
.npyfiles within the.npzarchive must be properly aligned for their element type. Archives not created by this crate can be aligned with the help of the CLI toolrezipas inrezip in.npz -o out.npz.
Example
This is an example of opening a mutably memory-mapped .npz archive as an
NpzViewMut providing an NpyViewMut for each non-compressed and
non-encrypted .npy file within the archive which can be accessed via
NpyViewMut::view as immutable ArrayView or via
NpyViewMut::view_mut as mutable ArrayViewMut. Changes to the data in
the view will modify the underlying file within the archive.
This example uses the memmap2 crate
because that appears to be the best-maintained memory-mapping crate at the
moment, but Self::new takes a &mut [u8] instead of a file so that you
can use the memory-mapping crate you’re most comfortable with.
Example
use std::fs::OpenOptions;
use memmap2::MmapOptions;
use ndarray::Ix1;
use ndarray_npz::{NpzViewMut, ViewNpzError};
// Open `.npz` archive of non-compressed and non-encrypted `.npy` files in
// native endian.
#[cfg(target_endian = "little")]
let mut file = OpenOptions::new()
.read(true)
.write(true)
.open("tests/examples_little_endian_64_byte_aligned.npz")
.unwrap();
#[cfg(target_endian = "big")]
let mut file = OpenOptions::new()
.read(true)
.write(true)
.open("tests/examples_big_endian_64_byte_aligned.npz")
.unwrap();
// Memory-map `.npz` archive of 64-byte aligned `.npy` files.
let mut mmap = unsafe { MmapOptions::new().map_mut(&file).unwrap() };
let mut npz = NpzViewMut::new(&mut mmap)?;
// List non-compressed and non-encrypted files only.
for npy in npz.names() {
println!("{}", npy);
}
// Get mutable `.npy` views of both arrays at the same time.
let mut x_npy_view_mut = npz.by_name("i64.npy")?;
let mut y_npy_view_mut = npz.by_name("f64.npy")?;
// Optionally verify CRC-32 checksums.
x_npy_view_mut.verify()?;
y_npy_view_mut.verify()?;
// Get and print mutable `ArrayViewMut`s.
let x_array_view_mut = x_npy_view_mut.view_mut::<i64, Ix1>()?;
let y_array_view_mut = y_npy_view_mut.view_mut::<f64, Ix1>()?;
println!("{}", x_array_view_mut);
println!("{}", y_array_view_mut);
// Update CRC-32 checksums after changes. Automatically updated on `drop()`
// if outdated.
x_npy_view_mut.update();
y_npy_view_mut.update();Implementations§
source§impl<'a> NpzViewMut<'a>
impl<'a> NpzViewMut<'a>
sourcepub fn new(bytes: &'a mut [u8]) -> Result<Self, ViewNpzError>
pub fn new(bytes: &'a mut [u8]) -> Result<Self, ViewNpzError>
sourcepub fn is_empty(&self) -> bool
pub fn is_empty(&self) -> bool
Returns true iff the .npz file doesn’t contain any viewable arrays.
Viewable arrays are neither directories, nor compressed, nor encrypted.
sourcepub fn len(&self) -> usize
pub fn len(&self) -> usize
Returns the number of viewable arrays in the .npz file.
Viewable arrays are neither directories, nor compressed, nor encrypted.
sourcepub fn names(&self) -> impl Iterator<Item = &str>
pub fn names(&self) -> impl Iterator<Item = &str>
Returns the names of all of the viewable arrays in the .npz file.
Viewable arrays are neither directories, nor compressed, nor encrypted.
sourcepub fn directory_names(&self) -> impl Iterator<Item = &str>
pub fn directory_names(&self) -> impl Iterator<Item = &str>
Returns the names of all of the directories in the .npz file.
sourcepub fn compressed_names(&self) -> impl Iterator<Item = &str>
pub fn compressed_names(&self) -> impl Iterator<Item = &str>
Returns the names of all of the compressed files in the .npz file.
sourcepub fn encrypted_names(&self) -> impl Iterator<Item = &str>
pub fn encrypted_names(&self) -> impl Iterator<Item = &str>
Returns the names of all of the encrypted files in the .npz file.
sourcepub fn by_name(&mut self, name: &str) -> Result<NpyViewMut<'a>, ViewNpzError>
pub fn by_name(&mut self, name: &str) -> Result<NpyViewMut<'a>, ViewNpzError>
Moves a mutable .npy file view by name out of the .npz file view.
Errors
Viewing an .npy file can fail with ViewNpyError. Trying to view a directory,
compressed file, or encrypted file, fails with ViewNpzError::Directory,
ViewNpzError::CompressedFile, or ViewNpzError::CompressedFile. Fails with
ZipError::FileNotFound if the name is not found.
sourcepub fn by_index(&mut self, index: usize) -> Result<NpyViewMut<'a>, ViewNpzError>
pub fn by_index(&mut self, index: usize) -> Result<NpyViewMut<'a>, ViewNpzError>
Moves a mutable .npy file view by index in 0..len() out of the .npz file view.
The index does not necessarily correspond to the index of the zip archive as directories, compressed files, and encrypted files are skipped.
Errors
Viewing an .npy file can fail with ViewNpyError. Fails with ZipError::FileNotFound
if the index is not found. Fails with ViewNpzError::MovedNpyViewMut if the mutable
.npy file view has already been moved out of the .npz file view.