A wrapper for Span that implements the Hash, Eq and PartialEq traits.

A SpanFieldwise is meant to make it easy to compare two spans in a "dumb" way based purely on its unit values, while still providing a speed bump to avoid accidentally doing this comparison on Span directly. This is distinct from something like Span::compare that performs a comparison on the actual elapsed time of two spans.

It is generally discouraged to use SpanFieldwise since spans that represent an equivalent elapsed amount of time may compare unequal. However, in some cases, it is useful to be able to assert precise field values. For example, Jiff itself makes heavy use of fieldwise comparisons for tests.

Construction

While callers may use SpanFieldwise(span) (where span has type Span) to construct a value of this type, callers may find Span::fieldwise more convenient. Namely, Span::fieldwise may avoid the need to explicitly import SpanFieldwise.

Trait implementations

In addition to implementing the Hash, Eq and PartialEq traits, this type also provides PartialEq impls for comparing a Span with a SpanFieldwise. This simplifies comparisons somewhat while still requiring that at least one of the values has an explicit fieldwise comparison type.

Safety

This type is guaranteed to have the same layout in memory as Span.

Example: the difference between SpanFieldwise and Span::compare

In short, SpanFieldwise considers 2 hours and 120 minutes to be distinct values, but Span::compare considers them to be equivalent:

use std::cmp::Ordering;
use jiff::ToSpan;

assert_ne!(120.minutes().fieldwise(), 2.hours().fieldwise());
assert_eq!(120.minutes().compare(2.hours())?, Ordering::Equal);

// These comparisons are allowed between a `Span` and a `SpanFieldwise`.
// Namely, as long as one value is "fieldwise," then the comparison is OK.
assert_ne!(120.minutes().fieldwise(), 2.hours());
assert_ne!(120.minutes(), 2.hours().fieldwise());

# Ok::<(), Box<dyn std::error::Error>>(())