ndarray_npy/lib.rs
1//! This crate provides methods to read/write [`ndarray`]'s
2//! [`ArrayBase`](ndarray::ArrayBase) type from/to [`.npy`] and [`.npz`] files.
3//!
4//! See the [repository] for information about the default features and how to
5//! use this crate with Cargo.
6//!
7//! [repository]: https://github.com/jturner314/ndarray-npy
8//! [`ndarray`]: https://github.com/bluss/ndarray
9//! [`.npy`]: https://docs.scipy.org/doc/numpy/reference/generated/numpy.lib.format.html
10//! [`.npz`]: https://docs.scipy.org/doc/numpy/reference/generated/numpy.savez.html
11//!
12//! # .npy Files
13//!
14//! - Reading
15//! - [`ReadNpyExt`] extension trait
16//! - [`read_npy`] convenience function
17//! - Writing
18//! - [`WriteNpyExt`] extension trait
19//! - [`write_npy`] convenience function
20//! - [`write_zeroed_npy`] to write an `.npy` file (sparse if possible) of zeroed data
21//! - Readonly viewing (primarily for use with memory-mapped files)
22//! - [`ViewNpyExt`] extension trait
23//! - Mutable viewing (primarily for use with memory-mapped files)
24//! - [`ViewMutNpyExt`] extension trait
25//!
26//! It's possible to create `.npy` files larger than the available memory with
27//! [`write_zeroed_npy`] and then modify them by memory-mapping and using
28//! [`ViewMutNpyExt`].
29//!
30//! # .npz Files
31//!
32//! - Reading: [`NpzReader`]
33//! - Writing: [`NpzWriter`]
34//!
35//! # Limitations
36//!
37//! * Parsing of `.npy` files is currently limited to files where the `descr`
38//! field of the [header dictionary] is a Python string literal of the form
39//! `'string'`, `"string"`, `'''string'''`, or `"""string"""`.
40//!
41//! * The element traits ([`WritableElement`], [`ReadableElement`],
42//! [`ViewElement`], and [`ViewMutElement`]) are currently implemented only
43//! for fixed-size integers up to 64 bits, floating point numbers, complex
44//! floating point numbers (if enabled with the crate feature), and [`bool`].
45//!
46//! The plan is to add support for more element types (including custom
47//! user-defined structs) in the future.
48//!
49//! [header dictionary]: https://docs.scipy.org/doc/numpy/reference/generated/numpy.lib.format.html#format-version-1-0
50
51mod npy;
52#[cfg(feature = "npz")]
53mod npz;
54
55pub use crate::npy::{
56 read_npy, write_npy, write_zeroed_npy, ReadDataError, ReadNpyError, ReadNpyExt,
57 ReadableElement, ViewDataError, ViewElement, ViewMutElement, ViewMutNpyExt, ViewNpyError,
58 ViewNpyExt, WritableElement, WriteDataError, WriteNpyError, WriteNpyExt,
59};
60#[cfg(feature = "npz")]
61pub use crate::npz::{NpzReader, NpzWriter, ReadNpzError, WriteNpzError};