Crate npy [−] [src]
Serialize and deserialize the NumPy's *.npy binary format.
Overview
NPY is a simple binary data format. It stores the type, shape and endianness information in a header, which is followed by a flat binary data field. This crate offers a simple, mostly type-safe way to read and write *.npy files. Files are handled using iterators, so they don't need to fit in memory.
Only one-dimensional structured arrays are supported at the moment as they map well to Rust structs.
To successfully import an array from NPY using the #[derive(NpyData)]
mechanism, the target struct
must contain:
- corresponding number of fields in the same order,
- corresponding names of fields,
- compatible field types.
Currently, all the primitive numeric types and arrays of up to 16 elements are supported, though
they work only with little-endian. To deserialize other types or big-endian values, one must
manually implement Serializable
. A very common object that (right now)
requires a manual impl
is a vector, as illustrated in
an example.
Examples
More examples can be found in the examples directory.
Let's create a simple *.npy file in Python:
import numpy as np
a = np.array([(1,2.5,4), (2,3.1,5)], dtype=[('a', 'i4'),('b', 'f4'),('c', 'i8')])
np.save('examples/simple.npy', a)
Now, we can load it in Rust:
#[macro_use] extern crate npy_derive; extern crate npy; use std::io::Read; #[derive(NpyData, Debug)] struct Array { a: i32, b: f32, c: i64, } fn main() { let mut buf = vec![]; std::fs::File::open("examples/simple.npy").unwrap() .read_to_end(&mut buf).unwrap(); for arr in npy::from_bytes::<Array>(&buf).unwrap() { println!("{:?}", arr); } }
The output is:
Array { a: 1, b: 2.5, c: 4 }
Array { a: 2, b: 3.1, c: 5 }
Structs
DType |
Representation of a Numpy type |
NpyIterator |
A result of NPY file deserialization. |
OutFile |
Serialize into a file one row at a time. To serialize an iterator, use the
|
Traits
NpyData |
This trait is often automatically implemented by a |
Serializable |
This trait contains information on how to serialize and deserialize a type. |
Functions
from_bytes |
Deserialize a NPY file represented as bytes |
to_file |
Serialize an iterator over a struct to a NPY file |