Crate approx_derive

source ·
Expand description

This crate provides derive macros for the AbsDiffEq and RelativeEq traits of the approx crate.

These derive macros only implement both traits with ...<Rhs = Self>. The macros infer the EPSILON type of the AbsDiffEq trait by looking at the type of the first struct field or any type specified by the user.

The following example explains a possible use-case.

use approx_derive::AbsDiffEq;

// Define a new type and derive the AbsDiffEq trait
#[derive(AbsDiffEq, PartialEq, Debug)]
struct Position {
    x: f64,
    y: f64
}

// Compare if two given positions match
// with respect to geiven epsilon.
let p1 = Position { x: 1.01, y: 2.36 };
let p2 = Position { x: 0.99, y: 2.38 };
approx::assert_abs_diff_eq!(p1, p2, epsilon = 0.021);

In this case, the generated code looks something like this:

ⓘ
const _ : () =
{
    #[automatically_derived] impl approx :: AbsDiffEq for Position
    {
        type Epsilon = f64; fn default_epsilon() -> Self :: Epsilon
        { f64 :: EPSILON } fn
        abs_diff_eq(& self, other : & Self, epsilon : Self :: Epsilon) -> bool
        {
            < f64 as approx :: AbsDiffEq > ::
            abs_diff_eq(& self.x, & other.x, epsilon) && < f64 as approx ::
            AbsDiffEq > :: abs_diff_eq(& self.y, & other.y, epsilon) && true
        }
    }
};

The AbsDiffEq derive macro calls the abs_diff_eq method repeatedly on all fields to determine if all are matching.

§Field Attributes

§Skipping Fields

Sometimes, we only want to compare certain fields and omit others completely.

#[derive(AbsDiffEq, PartialEq, Debug)]
struct Player {
    hit_points: f32,
    pos_x: f32,
    pos_y: f32,
    #[approx(skip)]
    id: (usize, usize),
}

let player1 = Player {
    hit_points: 100.0,
    pos_x: 2.0,
    pos_y: -650.345,
    id: (0, 1),
};

let player2 = Player {
    hit_points: 99.9,
    pos_x: 2.001,
    pos_y: -649.898,
    id: (22, 0),
};

approx::assert_abs_diff_eq!(player1, player2, epsilon = 0.5);

§Casting Fields

Structs which consist of multiple fields with different numeric types, can not be derived without additional hints. After all, we should specify how this type mismatch will be handled.

ⓘ
#[derive(AbsDiffEq, PartialEq, Debug)]
struct MyStruct {
    v1: f32,
    v2: f64,
}

We can use the #[approx(cast_field)] and #[approx(cast_value)] attributes to achieve this goal.

#[derive(AbsDiffEq, PartialEq, Debug)]
struct MyStruct {
    v1: f32,
    #[approx(cast_field)]
    v2: f64,
}

Now the second field will be casted to the type of the inferred epsilon value (f32). We can check this by testing if a change in the size of f64::MIN_POSITIVE would get lost by this procedure.

let ms1 = MyStruct {
    v1: 1.0,
    v2: 3.0,
};
let ms2 = MyStruct {
    v1: 1.0,
    v2: 3.0 + f64::MIN_POSITIVE,
};
approx::assert_relative_eq!(ms1, ms2);

§Static Values

We can force a static EPSILON or max_relative value for individual fields.

#[derive(AbsDiffEq, PartialEq, Debug)]
struct Rectangle {
    #[approx(static_epsilon = 5e-2)]
    a: f64,
    b: f64,
    #[approx(static_epsilon = 7e-2)]
    c: f64,
}

let r1 = Rectangle {
    a: 100.01,
    b: 40.0001,
    c: 30.055,
};
let r2 = Rectangle {
    a: 99.97,
    b: 40.0005,
    c: 30.049,
};

// This is always true although the epsilon is smaller than the
// difference between fields a and b respectively.
approx::assert_abs_diff_eq!(r1, r2, epsilon = 1e-1);
approx::assert_abs_diff_eq!(r1, r2, epsilon = 1e-2);
approx::assert_abs_diff_eq!(r1, r2, epsilon = 1e-3);

// Here, the epsilon value has become larger than the difference between the
// b field values.
approx::assert_abs_diff_ne!(r1, r2, epsilon = 1e-4);

§Struct Attributes

§Default Epsilon

The AbsDiffEq trait allows to specify a default value for its EPSILON associated type. We can control this value by specifying it on a struct level.

#[derive(AbsDiffEq, PartialEq, Debug)]
#[approx(default_epsilon = 10)]
struct Benchmark {
    cycles: u64,
    warm_up: u64,
}

let benchmark1 = Benchmark {
    cycles: 248,
    warm_up: 36,
};
let benchmark2 = Benchmark {
    cycles: 239,
    warm_up: 28,
};

// When testing with not additional arguments, the results match
approx::assert_abs_diff_eq!(benchmark1, benchmark2);
// Once we specify a lower epsilon, the values do not agree anymore.
approx::assert_abs_diff_ne!(benchmark1, benchmark2, epsilon = 5);

§Default Max Relative

Similarly to [Default Epsilon], we can also choose a default max_relative devaition.

#[derive(RelativeEq, PartialEq, Debug)]
#[approx(default_max_relative = 0.1)]
struct Benchmark {
    time: f32,
    warm_up: f32,
}

let bench1 = Benchmark {
    time: 3.502785781,
    warm_up: 0.58039458,
};
let bench2 = Benchmark {
    time: 3.7023458,
    warm_up: 0.59015897,
};

approx::assert_relative_eq!(bench1, bench2);
approx::assert_relative_ne!(bench1, bench2, max_relative = 0.05);

§Epsilon Type

When specifying nothing, the macros will infer the EPSILON type from the type of the first struct field. This can be problematic in certain scenarios which is why we can also manually specify this type.

#[derive(RelativeEq, PartialEq, Debug)]
#[approx(epsilon_type = f32)]
struct Car {
    #[approx(cast_field)]
    produced_year: u32,
    horse_power: f32,
}

let car1 = Car {
    produced_year: 1992,
    horse_power: 122.87,
};
let car2 = Car {
    produced_year: 2000,
    horse_power: 117.45,
};

approx::assert_relative_eq!(car1, car2, max_relative = 0.05);
approx::assert_relative_ne!(car1, car2, max_relative = 0.01);

Derive Macros§