//! Every value the engine has for a group of adjoining margins when it calls the
//! `margin_combine` generated function, under the one name and type each value has, and the
//! fixed field of the function's answer.
//!
//! The function's types file (`margin_combine_types.rs`) is written by a model, and the
//! engine fills its inputs struct without knowing in advance which values it holds: the
//! call sites (`fragment.rs` `stack_children`, through `combine_margins`) build a
//! [`MarginCombineEngineValues`], and `margin_combine::inputs_from`, which `build.rs` writes
//! from the types file in place, copies each field the inputs struct declares from the field
//! of the same name here. So a types file's inputs struct may only take fields of
//! [`MarginCombineEngineValues`], under the same names and types, and its outputs struct has
//! exactly the field of [`MarginCombineEngineAnswer`]. `job-check types --engine` checks both
//! on the file alone (`jobs/src/types_file.rs` `check_names`).
//!
//! The one value is a list, so the inputs struct and the engine's struct both borrow it for
//! a lifetime, named `'a` in both: the engine hands the function the group it collected
//! without copying it.
//!
//! A value whose doc has a paragraph opening `Needed:` is one the specification's rules
//! read whenever the specification text says one of the quoted phrases in it: a types
//! file written from that text takes the value. `job-check types --engine <file>
//! --specification <folder>` refuses a types file that does not while the text says the
//! phrase (`jobs/src/types_file.rs` `check_needs`).

/// Every value the engine has worked out for the group at the call, and nothing else.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct MarginCombineEngineValues<'a> {
    /// The signed widths, in px, of every margin of one adjoining group, in the order the
    /// engine met them: a negative margin is a negative number, a margin that is zero is
    /// zero. The group is the whole list at once, never a partial result of an earlier call.
    ///
    /// Needed: the specification text says "adjoining margins".
    pub margins: &'a [f64],
}

/// The field of the function's answer, which the engine reads by this name: a types file's
/// outputs struct declares exactly this.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct MarginCombineEngineAnswer {
    /// The one margin, in px, the whole group collapses to: the distance the engine puts
    /// between the two boxes' (or the box and its parent's) edges.
    pub margin: f64,
}