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
use super::Score;

/// The four values the constructor refuses, one per reason: `NaN` (which is what the total order
/// below is bought by excluding), an infinity, and a value off each end of the interval.
#[test]
fn rejects_what_is_not_a_score() {
  assert!(Score::new(f32::NAN).is_none());
  assert!(Score::new(f32::INFINITY).is_none());
  assert!(Score::new(-0.1).is_none());
  assert!(Score::new(1.0000001).is_none());
}

/// The interval is CLOSED, so a detection that is certain and one that is not are both scores.
#[test]
fn accepts_both_endpoints() {
  assert_eq!(Score::new(0.0).unwrap().get(), 0.0);
  assert_eq!(Score::new(1.0).unwrap().get(), 1.0);
}

/// `-0.0` passes the range check — `-0.0 >= 0.0` is TRUE — but its bits differ from `+0.0` while
/// comparing equal. Left alone it breaks the `Hash`/`Eq` contract: two values that are `==` hash
/// differently. The constructor normalises it, and this test is the only thing that says so.
///
/// The second assertion is therefore over BITS rather than over equality. An equality assertion
/// passes with the normalisation deleted, because `-0.0 == 0.0` is exactly the problem.
#[test]
fn negative_zero_is_normalised() {
  let neg = Score::new(-0.0).unwrap();
  assert_eq!(neg, Score::ZERO);
  assert_eq!(neg.get().to_bits(), 0.0f32.to_bits());
}

/// The sort IS the assertion: `[T]::sort` asks for [`Ord`], which an `f32` newtype can only have
/// once `NaN` is out of the domain. The interior values sit either side of the two endpoints in the
/// input so that a comparison inverted anywhere lands somewhere visible.
#[test]
fn orders_totally() {
  let mut v = [
    Score::new(0.7).unwrap(),
    Score::ZERO,
    Score::ONE,
    Score::new(0.3).unwrap(),
  ];
  v.sort();
  assert_eq!(
    v,
    [
      Score::ZERO,
      Score::new(0.3).unwrap(),
      Score::new(0.7).unwrap(),
      Score::ONE
    ]
  );
}

/// The `Hash`/`Eq` contract, over the one pair that could ever break it here: hashing the bits is
/// sound only because `-0.0` never reaches a `Score` field. This is the far end of the constructor's
/// normalisation, and the two tests fail together if it goes.
#[test]
fn equal_scores_hash_equally() {
  use std::{
    collections::hash_map::DefaultHasher,
    hash::{Hash, Hasher},
  };

  let h = |s: Score| {
    let mut d = DefaultHasher::new();
    s.hash(&mut d);
    d.finish()
  };

  assert_eq!(h(Score::new(-0.0).unwrap()), h(Score::ZERO));
}

/// The ALIAS is an alias, and this is the row that says so.
///
/// `Score` and `Confidence<f32>` being ONE type is what makes every row this crate wrote for the
/// first a row the second has — the fourteen citizenship sites, the storage carriers, the column
/// membership — without one of them being touched. A wrapper would have needed all fourteen
/// rewritten; this assertion is the difference, and it fails at COMPILE time if `Score` ever stops
/// being the `f32` instantiation.
///
/// The alias no longer carries a WIRE name of its own, and that is a later ruling rather than a
/// weakening of this one: the four `Score*` scalars and their four filters are retired, so what
/// `Score` reaches at the wire is `f32`'s roster scalar and the one `ConfidenceFilter`. The row
/// below is untouched by that — it is about the two spellings naming one Rust type, which is what
/// let the reshape move the wire without moving a single call site.
#[test]
fn score_is_the_f32_confidence() {
  fn same<T>(_: core::marker::PhantomData<T>, _: core::marker::PhantomData<T>) {}

  same(
    core::marker::PhantomData::<Score>,
    core::marker::PhantomData::<super::Confidence<f32>>,
  );
}

/// [`rejects_what_is_not_a_score`] at the second IEEE width, and the same four reasons: the interval
/// and the values that are not numbers are the carrier's business, not the wrapper's, so every
/// clause has to be shown spent at each width rather than at one.
#[test]
fn rejects_what_is_not_a_confidence_at_f64() {
  type C = super::Confidence<f64>;

  assert!(C::new(f64::NAN).is_none());
  assert!(C::new(f64::INFINITY).is_none());
  assert!(C::new(-0.1).is_none());
  assert!(C::new(1.0000001).is_none());

  assert_eq!(C::new(0.0).unwrap().get(), 0.0);
  assert_eq!(C::new(1.0).unwrap().get(), 1.0);
}

/// [`negative_zero_is_normalised`] at `f64`, and the same assertion over BITS for the same reason:
/// an equality assertion passes with the normalisation deleted, because `-0.0 == 0.0` is exactly the
/// problem.
#[test]
fn negative_zero_is_normalised_at_f64() {
  type C = super::Confidence<f64>;

  let neg = C::new(-0.0).unwrap();
  assert_eq!(neg, C::ZERO);
  assert_eq!(neg.get().to_bits(), 0.0f64.to_bits());
  assert_eq!(hash(neg), hash(C::ZERO));
}

/// The `f64` order, sorted the way [`orders_totally`] sorts the `f32` one — `[T]::sort` asks for
/// [`Ord`], which a float wrapper can only have once `NaN` is out of the domain.
#[test]
fn orders_totally_at_f64() {
  type C = super::Confidence<f64>;

  let mut v = [C::new(0.7).unwrap(), C::ZERO, C::ONE, C::new(0.3).unwrap()];
  v.sort();
  assert_eq!(
    v,
    [C::ZERO, C::new(0.3).unwrap(), C::new(0.7).unwrap(), C::ONE]
  );
}

/// `half::f16`'s clauses, which are `f32`'s written against the carrier's own comparisons.
///
/// The endpoints matter more here than at the wide widths: `1.0` is exactly representable in
/// binary16 and the range check is against [`ConfidenceCarrier::ONE`] rather than against a `f64`
/// literal, so a row that reached for the literal instead would fail HERE and nowhere else.
///
/// [`ConfidenceCarrier::ONE`]: super::ConfidenceCarrier::ONE
#[cfg(feature = "half")]
#[test]
fn refuses_and_normalises_at_f16() {
  use half::f16;
  type C = super::Confidence<f16>;

  assert!(C::new(f16::NAN).is_none());
  assert!(C::new(f16::INFINITY).is_none());
  assert!(C::new(f16::from_f32(-0.1)).is_none());
  assert!(C::new(f16::from_f32(1.5)).is_none());

  assert_eq!(C::new(f16::ZERO).unwrap().get(), f16::ZERO);
  assert_eq!(C::new(f16::ONE).unwrap().get(), f16::ONE);

  // The normalisation, over BITS — `half` has a `NEG_ZERO` const, so the value that breaks the
  // contract can be named rather than computed.
  let neg = C::new(f16::NEG_ZERO).unwrap();
  assert_eq!(neg, C::ZERO);
  assert_eq!(neg.get().to_bits(), f16::ZERO.to_bits());
  assert_eq!(hash(neg), hash(C::ZERO));
}

/// The decimal's TWO equal-but-differently-carried pairs, which is one more than any float has.
///
/// `-0` versus `0` is the float pair at a third width. `0.50` versus `0.5` is the pair only a scaled
/// type has, and it is why this carrier could not simply hash its bytes: the two are `==` and their
/// representations differ in the scale byte. `Decimal`'s own `Hash` normalises both away, and this
/// test is what holds the dependency to that — if it ever stopped, a `HashMap` keyed on a decimal
/// confidence would lose lookups silently.
#[cfg(feature = "rust_decimal")]
#[test]
fn equal_decimals_hash_equally() {
  use core::str::FromStr;

  use rust_decimal::Decimal;
  type C = super::Confidence<Decimal>;

  let neg_zero = C::new(Decimal::from_str("-0").unwrap()).unwrap();
  assert_eq!(neg_zero, C::ZERO);
  assert_eq!(hash(neg_zero), hash(C::ZERO));

  let scaled = C::new(Decimal::from_str("0.50").unwrap()).unwrap();
  let plain = C::new(Decimal::from_str("0.5").unwrap()).unwrap();
  assert_eq!(scaled, plain);
  assert_eq!(hash(scaled), hash(plain));
}

/// The decimal's refusal, which is the INTERVAL and nothing else.
///
/// There is no `NaN` case to write and no infinity case either — `Decimal` has neither value — so
/// this test is deliberately two assertions where the float tests are four. That absence is the
/// per-carrier half of the argument: the constructor's clauses are the carrier's, and a width that
/// needs fewer spends fewer.
#[cfg(feature = "rust_decimal")]
#[test]
fn refuses_only_the_interval_at_decimal() {
  use core::str::FromStr;

  use rust_decimal::Decimal;
  type C = super::Confidence<Decimal>;

  assert!(C::new(Decimal::from_str("-0.1").unwrap()).is_none());
  assert!(C::new(Decimal::from_str("1.0000001").unwrap()).is_none());

  assert_eq!(C::new(Decimal::ZERO).unwrap().get(), Decimal::ZERO);
  assert_eq!(C::new(Decimal::ONE).unwrap().get(), Decimal::ONE);

  // The order the floats have to BUY is one this carrier arrived with, and `sort` is where that is
  // visible: `Decimal` is `Ord`, so `admitted_cmp` delegates rather than asserting.
  let mut v = [
    C::ONE,
    C::ZERO,
    C::new(Decimal::from_str("0.5").unwrap()).unwrap(),
  ];
  v.sort();
  assert_eq!(
    v,
    [
      C::ZERO,
      C::new(Decimal::from_str("0.5").unwrap()).unwrap(),
      C::ONE
    ]
  );
}

/// One hash, so the `Hash`/`Eq` rows above read as the one assertion they are.
fn hash<T: core::hash::Hash>(value: T) -> u64 {
  use std::{collections::hash_map::DefaultHasher, hash::Hasher};

  let mut state = DefaultHasher::new();
  value.hash(&mut state);
  state.finish()
}