Struct Matrix 

pub struct Matrix<T> { /* private fields */ }

An owned matrix: a layout, the length of each dimension, and the elements in that order.

use structio::{Matrix, MatrixLayout};

let m = Matrix::new(MatrixLayout::RowMajor, vec![2, 2], vec![1.0f64, 2.0, 3.0, 4.0]).unwrap();
assert_eq!(m.extents(), &[2, 2]);

let bytes = structio::to_beve(&m);
assert_eq!(structio::from_beve::<Matrix<f64>>(&bytes).unwrap(), m);
assert_eq!(
    structio::beve_to_json(&bytes).unwrap(),
    r#"{"layout":"layout_right","extents":[2,2],"value":[1,2,3,4]}"#
);

The elements are one flat run, since that is what the format stores and what makes storing it cheap. Indexing into them is arithmetic this type deliberately does not do: which of the two layouts is in force changes the answer, and a program that computes with matrices already has a type that knows. Use Matrix::into_parts to hand the pieces to it.

Implementations

impl<T> Matrix<T>

pub fn new( layout: MatrixLayout, extents: Vec<usize>, data: Vec<T>, ) -> Result<Self, ErrorCode>

Build a matrix, checking that the extents describe the data.

The only failure is InvalidMatrixShape, and it is checked here so that it can never be checked again: nothing downstream of this, writing included, has to consider a matrix whose halves disagree.

Examples found in repository

examples/beve.rs (line 267)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let value = run();

    // -- The same value, either way ------------------------------------------
    let text = structio::to_string(&value);
    let binary = structio::to_beve(&value);

    assert_eq!(structio::from_str::<Run>(&text)?, value);
    assert_eq!(structio::from_beve::<Run>(&binary)?, value);

    println!("json  {:>6} bytes", text.len());
    println!(
        "beve  {:>6} bytes  ({:.0}% of the text)",
        binary.len(),
        100.0 * binary.len() as f64 / text.len() as f64
    );
    // The thousand samples are 8 bytes each and nothing more; the thousand
    // booleans are one bit each.
    println!(
        "      {} of those bytes are the sample payload, {} the flags",
        value.samples.len() * 8,
        value.valid.len().div_ceil(8)
    );

    // -- Reading into a value you already have -------------------------------
    // The destination keeps its buffers, so a loop over many documents of the
    // same shape settles into doing no allocation at all.
    let mut into = Run::default();
    structio::read_beve_into(&mut into, &binary)?;
    let at = into.samples.as_ptr();
    structio::read_beve_into(&mut into, &binary)?;
    assert_eq!(into.samples.as_ptr(), at, "the allocation was reused");

    // -- Borrowing straight out of the buffer --------------------------------
    let frame = Frame {
        id: 9,
        payload: &[0xDE, 0xAD, 0xBE, 0xEF],
        note: "no copies here",
    };
    let bytes = structio::to_beve(&frame);
    let back: Frame = structio::from_beve(&bytes)?;
    assert_eq!(back, frame);
    let inside = (back.note.as_ptr() as usize) - (bytes.as_ptr() as usize) < bytes.len();
    println!("borrowed fields point into the input: {inside}");

    // -- Arrays a reader can point at ----------------------------------------
    // BEVE's aligned form pads each numeric payload onto its own element
    // width, so a reader with an aligned buffer can borrow the block where it
    // lies instead of copying it out. The same document otherwise: this one
    // still reads back into the same value.
    assert_eq!(
        structio::from_beve::<Run>(&structio::to_beve_aligned(&value))?,
        value
    );
    let padded = structio::to_beve_aligned(&value.samples);
    let payload = padded.len() - value.samples.len() * 8;
    assert_eq!(payload % 8, 0);
    println!(
        "the aligned form puts {} samples at byte {payload}",
        value.samples.len()
    );

    // And a reader takes that offer up: `try_slice` hands the block back as a
    // `&[f64]` pointing into the document itself. Whether it can is partly the
    // allocator's decision, the document having to sit on an address an `f64`
    // could live at, so the answer is an `Option` rather than a promise, and
    // `Cow<[f64]>` is the field type that copies when it has to.
    let mut reader = structio::beve::Reader::new(&padded);
    match reader.try_slice::<f64>() {
        Some(block) => println!("borrowed {} samples with no copy at all", block.len()),
        None => println!("this buffer is not one a &[f64] can point into"),
    }

    // -- Writing to a sink ---------------------------------------------------
    // Drained as it is produced, so peak memory is the buffer rather than the
    // size of the output.
    let mut file = Vec::new();
    structio::to_beve_writer(&value, &mut file)?;
    assert_eq!(file, binary);

    // -- Length-prefixed frames ----------------------------------------------
    let runs = [run(), run()];
    let mut sink = Vec::new();
    send_frames(&runs, &mut sink)?;

    // The unbuffered form is the same stream, byte for byte, which is the
    // whole claim `beve_size` makes.
    let mut streamed = Vec::new();
    stream_frames(&runs, &mut streamed)?;
    assert_eq!(streamed, sink);

    let mut rest = &sink[..];
    for want in &runs {
        let (len, tail) = rest.split_at(4);
        let len = u32::from_le_bytes(len.try_into()?) as usize;
        let (frame, tail) = tail.split_at(len);
        assert_eq!(&structio::from_beve::<Run>(frame)?, want);
        rest = tail;
    }
    assert!(rest.is_empty());
    println!("read back {} length-prefixed frames", runs.len());

    // A body behind a header, in the aligned form. The payload lands on its
    // element width counted from the start of the frame, whatever the query in
    // front of it is, and the stated length is the body's own.
    for query in ["", "/sensor", "/a/rather/longer/route"] {
        let frame = frame_aligned(query, &value.samples);
        let base = 8 + query.len();
        let stated = u64::from_le_bytes(frame[..8].try_into()?) as usize;
        assert_eq!(frame.len() - base, stated);
        assert_eq!((frame.len() - value.samples.len() * 8) % 8, 0);
        assert_eq!(
            structio::from_beve::<Vec<f64>>(&frame[base..])?,
            value.samples
        );
    }
    println!("aligned bodies stay aligned behind a header of any length");

    // -- Looking at a document you have no type for --------------------------
    // No schema involved: the binary states every value's kind and extent, so
    // the walk that reads it drives the JSON writer directly. What comes out is
    // the same bytes the typed path above produced.
    assert_eq!(structio::beve_to_json(&binary)?, text);
    let unknown = structio::beve_to_json(&structio::to_beve(&frame))?;
    println!("a document with no declared type: {unknown}");

    // -- A file too large to hold --------------------------------------------
    // `from_beve` wants the whole document. `Documents` wants one value of it,
    // so the cost of a million records is one record, not a million. A typed
    // array streams too: the elements carry no headers, and the one the array
    // implied is supplied to the reader with each span.
    let archive = structio::to_beve(&vec![run(), run(), run()]);
    let mut docs = structio::beve::Documents::array(&archive[..]).read_size(16);
    // Into an existing value, so the loop stops allocating after the first
    // record as well as holding only one at a time.
    let mut record = Run::default();
    let mut count = 0;
    while let Some(result) = docs.next_value_into(&mut record) {
        result?;
        count += 1;
    }
    println!(
        "read {count} records out of {} bytes without ever holding the file",
        archive.len()
    );

    // -- What BEVE carries that JSON cannot ----------------------------------
    let odd = vec![f64::NAN, f64::INFINITY, -0.0];
    let back: Vec<f64> = structio::from_beve(&structio::to_beve(&odd))?;
    assert!(back[0].is_nan() && back[1].is_infinite() && back[2].is_sign_negative());
    println!("NaN, infinity, and negative zero survive the round trip");

    // -- Complex numbers and matrices ----------------------------------------
    // BEVE's two data-carrying extensions have types, and both work in JSON as
    // well, so a struct holding one still declares its schema once.
    let signal = vec![
        structio::Complex::new(1.0f64, 2.0),
        structio::Complex::new(3.0, -4.0),
    ];
    let bytes = structio::to_beve(&signal);
    println!(
        "{} complex samples in {} bytes: one header, one count, and the components",
        signal.len(),
        bytes.len()
    );
    assert_eq!(
        structio::from_beve::<Vec<structio::Complex<f64>>>(&bytes)?,
        signal
    );

    // A matrix stores its data as an ordinary value, so a matrix of complex
    // numbers is the run above with a shape in front of it.
    let grid = structio::Matrix::new(structio::MatrixLayout::RowMajor, vec![1, 2], signal.clone())?;
    let bytes = structio::to_beve(&grid);
    assert_eq!(
        structio::from_beve::<structio::Matrix<structio::Complex<f64>>>(&bytes)?,
        grid
    );
    println!("as a matrix: {}", structio::beve_to_json(&bytes)?);

    // -- Fields you do not know about ----------------------------------------
    // A key no field claims is refused by default, which is what catches a
    // typo or the wrong document. `SkipUnknown` asks for the other behaviour:
    // take the members you recognize and step over the rest, so a producer can
    // add fields without breaking you.
    #[derive(Default, Debug, PartialEq)]
    struct JustTheLabel {
        label: String,
    }
    structio::object!(JustTheLabel { label });

    let partial = structio::from_beve_with::<structio::SkipUnknown, JustTheLabel>(&binary)?;
    assert_eq!(partial.label, value.label);
    println!("unknown members are stepped over: {:?}", partial.label);

    Ok(())
}

pub fn layout(&self) -> MatrixLayout

pub fn set_layout(&mut self, layout: MatrixLayout)

Reinterpret the same elements in the other storage order.

Nothing moves: the layout says how the elements the matrix already holds are to be read, so changing it changes what they mean.

pub fn extents(&self) -> &[usize]

The length of each dimension, outermost first.

pub fn rank(&self) -> usize

How many dimensions the matrix has.

pub fn data(&self) -> &[T]

pub fn data_mut(&mut self) -> &mut [T]

The elements, mutably.

A slice rather than the Vec, which is what keeps the shape true: the values may change and their number may not.

pub fn len(&self) -> usize

pub fn is_empty(&self) -> bool

pub fn into_parts(self) -> (MatrixLayout, Vec<usize>, Vec<T>)

Take the three pieces apart, which is where a matrix stops being this crate’s problem and starts being your linear algebra library’s.

Trait Implementations

impl<T: Clone> Clone for Matrix<T>

fn clone(&self) -> Matrix<T>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: Debug> Debug for Matrix<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T: Default> Default for Matrix<T>

fn default() -> Matrix<T>

Returns the “default value” for a type.

impl<T: Eq> Eq for Matrix<T>

impl<T: Hash> Hash for Matrix<T>

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<T: PartialEq> PartialEq for Matrix<T>

fn eq(&self, other: &Matrix<T>) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl<'de, T> Read<'de> for Matrix<T>

where T: Read<'de> + Default,

fn read<O: Options>(&mut self, r: &mut Reader<'de, O>) -> Result<(), ErrorCode>

Read into self, from the reader’s current position.

fn read_bulk<O: Options>( _out: &mut Vec<Self>, _n: usize, _elem: u8, _r: &mut Reader<'de, O>, ) -> Result<bool, ErrorCode>

Fill out from the payload of a typed array of n elements whose element header is elem, or return false to decline.

impl<'de, T> Read<'de> for Matrix<T>

where T: Read<'de> + Default,

fn read<O: Options>(&mut self, p: &mut Parser<'de, O>) -> Result<(), ErrorCode>

Parse into self, from the cursor’s current position.

impl<T: PartialEq> StructuralPartialEq for Matrix<T>

impl<T: Write> Write for Matrix<T>

fn write<O: Options>(&self, w: &mut Writer<'_, O>)

fn is_null(&self) -> bool

Whether this value is absent, and so is left out of an object under Options::SKIP_NULL.

const ARRAY: Option<&'static [u8]> = None

The header bytes a contiguous run of this type is stored under, or None if it has no array form of its own and belongs in a generic one.

fn write_payload<O: Options>(items: &[Self], w: &mut Writer<'_, O>)

where Self: Sized,

Append items as the payload of a typed array whose header and count the caller has already written.

impl<T: Write> Write for Matrix<T>

fn write<O: Options>(&self, w: &mut Writer<'_, O>)

fn is_null(&self) -> bool

Whether this value is absent, and so is left out of an object under Options::SKIP_NULL.