ingraph 0.1.0

A declaration-driven indexing framework: records and nodes are written as Rust types, and the storage rows, the dataflow between them and the GraphQL query surface are emitted from the declaration.
Documentation
//! [`Held`] — what a by-key read of a SET election hands back: an entity's whole set, with the
//! ordinal each member is asked and attributed under.

/// One entity's SET in one column — the `m` values it holds there, each wearing the ordinal that
/// identifies it in every answer downstream.
///
/// # It is [`Folded`](super::Folded)'s family and not [`Ranked`](super::Ranked)'s
///
/// Nothing here is ranked, scored or compared: a by-key read is a READ. What it shares with
/// [`Folded`] — and the reason it is the carrier the set door's `get_` answers in — is the
/// ORDINAL LAW. A set retrieve runs the engine once per query vector, `Folded::streams[j]` is what
/// query vector `j`'s own stream said about an entity, and `j` is a position in the set the caller
/// asked with. This type is where that set comes from when the caller asks with an entity's own, so
/// its ordinal and `Folded`'s subscript are the SAME NUMBER — which is what makes the by-example set
/// road's answer attributable at all.
///
/// # Why the ordinal is carried rather than left to the index
///
/// `members()[j]` would give the same value, and a caller reading it would be inferring the law
/// rather than being handed it. [`enumerate`](Self::enumerate) is the one place the correspondence
/// is written down, so a reader who has a `Folded` and wants to know what `streams[2]` was about has
/// somewhere to go. The list is never reordered by anything here, which is the invariant that makes
/// the index meaningful in the first place.
///
/// # The arity that a single election refuses is this type's ordinary state
///
/// `get_<field>` on a UNIT election refuses when the engine holds several — the declaration said
/// one, and picking one of several is a choice nobody made. On a SET election several is the whole
/// point, so the same door answers the WHOLE SET instead. One door, two answer shapes, split by the
/// election's label at EMISSION: nothing here judges at run time.
///
/// EMPTY is not representable through the door — a column holding nothing for a key is `Unindexed`,
/// which is a fact about the caller's own argument rather than a set of zero. The type itself does
/// not forbid it, for the reason the framework forbids nothing it does not have to: a third party
/// building one has its own reasons.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Held<T> {
  members: Box<[T]>,
}

impl<T> Held<T> {
  /// The set, in the order the engine answered with — which is the order every ordinal below is
  /// counted in.
  #[inline]
  #[must_use]
  pub const fn new(members: Box<[T]>) -> Self {
    Self { members }
  }

  /// How many values this entity holds in the column — the `m` of a set query asked with it.
  #[inline]
  #[must_use]
  pub const fn len(&self) -> usize {
    self.members.len()
  }

  /// Whether the held holds nothing.
  ///
  /// Beside [`len`](Self::len) because a length is compared to zero by whoever reads it, and one
  /// spelling of that comparison is better than every caller's own.
  #[inline]
  #[must_use]
  pub const fn is_empty(&self) -> bool {
    self.members.is_empty()
  }

  /// The values, BORROWED, in ordinal order.
  #[inline]
  #[must_use]
  pub const fn members(&self) -> &[T] {
    &self.members
  }

  /// The value at one ordinal, or [`None`] where the held is shorter than that.
  #[inline]
  #[must_use]
  pub fn at(&self, ordinal: usize) -> Option<&T> {
    self.members.get(ordinal)
  }

  /// The values WITH their ordinals — the correspondence written down once.
  ///
  /// `(j, value)` where `j` is what [`Folded::streams`](super::Folded::streams) is subscripted by
  /// for a query asked with this held.
  #[inline]
  pub fn enumerate(&self) -> impl ExactSizeIterator<Item = (usize, &T)> {
    self.members.iter().enumerate()
  }

  /// The values, taken — for the caller that has read the ordinals and wants the set.
  #[inline]
  #[must_use]
  pub fn into_members(self) -> Box<[T]> {
    self.members
  }
}

impl<T> AsRef<[T]> for Held<T> {
  #[inline]
  fn as_ref(&self) -> &[T] {
    &self.members
  }
}

impl<T> IntoIterator for Held<T> {
  type IntoIter = ::std::vec::IntoIter<T>;
  type Item = T;

  #[inline]
  fn into_iter(self) -> Self::IntoIter {
    Vec::from(self.members).into_iter()
  }
}

impl<'a, T> IntoIterator for &'a Held<T> {
  type IntoIter = core::slice::Iter<'a, T>;
  type Item = &'a T;

  #[inline]
  fn into_iter(self) -> Self::IntoIter {
    self.members.iter()
  }
}

#[cfg(test)]
mod tests;