Struct SpanFieldwise

#[repr(transparent)]
pub struct SpanFieldwise(pub Span);

Available on crate features dep_jiff and alloc only.

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());

Tuple Fields

0: Span

Trait Implementations

impl Clone for SpanFieldwise

fn clone(&self) -> SpanFieldwise

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for SpanFieldwise

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

Formats the value using the given formatter.

impl Default for SpanFieldwise

fn default() -> SpanFieldwise

Returns the “default value” for a type.

impl From<Span> for SpanFieldwise

fn from(span: Span) -> SpanFieldwise

Converts to this type from the input type.

impl From<SpanFieldwise> for Span

fn from(span: SpanFieldwise) -> Span

Converts to this type from the input type.

impl Hash for SpanFieldwise

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

where H: Hasher,

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 Neg for SpanFieldwise

type Output = SpanFieldwise

The resulting type after applying the - operator.

fn neg(self) -> SpanFieldwise

Performs the unary - operation.

impl PartialEq<Span> for SpanFieldwise

fn eq(&self, rhs: &Span) -> bool

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a> PartialEq<SpanFieldwise> for &'a Span

fn eq(&self, rhs: &SpanFieldwise) -> bool

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a> PartialEq<SpanFieldwise> for &'a SpanFieldwise

fn eq(&self, rhs: &SpanFieldwise) -> bool

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<SpanFieldwise> for Span

fn eq(&self, rhs: &SpanFieldwise) -> bool

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq for SpanFieldwise

fn eq(&self, rhs: &SpanFieldwise) -> bool

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Copy for SpanFieldwise

impl Eq for SpanFieldwise