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