Crate compare [] [src]

Comparators.

A comparator is any type that implements the Compare trait, which imposes a total order. Its compare method accepts two values, which may be of the same type or different types, and returns an ordering on them.

Comparators are useful for parameterizing the behavior of sort methods and certain data structures.

The most basic comparator is Natural, which simply delegates to the type's implementation of Ord:

use compare::{Compare, natural};
use std::cmp::Ordering::{Less, Equal, Greater};

let a = &1;
let b = &2;

let cmp = natural();
assert_eq!(cmp.compare(a, b), Less);
assert_eq!(cmp.compare(b, a), Greater);
assert_eq!(cmp.compare(a, a), Equal);

There are convenience methods for checking each of the six relations:

use compare::{Compare, natural};

let a = &1;
let b = &2;

let cmp = natural();
assert!(cmp.compares_lt(a, b));
assert!(cmp.compares_le(a, b));
assert!(cmp.compares_ge(b, a));
assert!(cmp.compares_gt(b, a));
assert!(cmp.compares_eq(a, a));
assert!(cmp.compares_ne(a, b));

The Compare trait also provides default methods that consume a comparator to produce a new one with different behavior, similar to iterator adaptors. For example, all comparators can be reversed:

use compare::{Compare, natural};
use std::cmp::Ordering::Greater;

let cmp = natural().rev();
assert_eq!(cmp.compare(&1, &2), Greater);

It is possible to implement a comparator that is not based on the natural ordering of a type by using a closure of type Fn(&L, &R) -> Ordering. For example, slices can be compared by their length instead of their contents:

use compare::Compare;
use std::cmp::Ordering::{Less, Greater};

let a = [1, 2, 3];
let b = [4, 5];

let cmp = |l: &[i32], r: &[i32]| l.len().cmp(&r.len());
assert_eq!(cmp.compare(&a, &b), Greater);

let cmp = cmp.rev();
assert_eq!(cmp.compare(&a, &b), Less);

Comparators can be combined lexicographically in order to compare values first by one key, then, if the first keys were equal, by another:

use compare::Compare;
use std::cmp::Ordering::{Less, Equal, Greater};

struct Pet { name: &'static str, age: u8 }

let fido4 = &Pet { name: "Fido", age: 4 };
let ruff2 = &Pet { name: "Ruff", age: 2 };
let fido3 = &Pet { name: "Fido", age: 3 };

let name_cmp = |l: &Pet, r: &Pet| l.name.cmp(r.name);
assert_eq!(name_cmp.compare(fido4, ruff2), Less);
assert_eq!(name_cmp.compare(fido4, fido3), Equal);
assert_eq!(name_cmp.compare(ruff2, fido3), Greater);

let age_cmp = |l: &Pet, r: &Pet| l.age.cmp(&r.age);
assert_eq!(age_cmp.compare(fido4, ruff2), Greater);
assert_eq!(age_cmp.compare(fido4, fido3), Greater);
assert_eq!(age_cmp.compare(ruff2, fido3), Less);

let name_age_cmp = name_cmp.then(age_cmp);
assert_eq!(name_age_cmp.compare(fido4, ruff2), Less);
assert_eq!(name_age_cmp.compare(fido4, fido3), Greater);
assert_eq!(name_age_cmp.compare(ruff2, fido3), Greater);

It is often repetitive to compare two values of the same type by the same key, so the key-extraction logic can be factored out, simplifying the previous example:

use compare::{Compare, Extract};
use std::cmp::Ordering::{Less, Greater};

struct Pet { name: &'static str, age: u8 }

let fido4 = &Pet { name: "Fido", age: 4 };
let ruff2 = &Pet { name: "Ruff", age: 2 };
let fido3 = &Pet { name: "Fido", age: 3 };

let name_age_cmp = Extract::new(|p: &Pet| p.name)
             .then(Extract::new(|p: &Pet| p.age));

assert_eq!(name_age_cmp.compare(fido4, ruff2), Less);
assert_eq!(name_age_cmp.compare(fido4, fido3), Greater);
assert_eq!(name_age_cmp.compare(ruff2, fido3), Greater);

Structs

Borrowing

A comparator that borrows its parameters before comparing them.

Extract

A comparator that extracts a sort key from a value.

Natural

A comparator that delegates to Ord.

Rev

A comparator that reverses the ordering of another.

Swap

A comparator that swaps another's parameters, maintaining the underlying ordering.

Then

A comparator that lexicographically combines two others.

Traits

Compare

A comparator imposing a total order.

Functions

max

Returns the maximum of two values according to the given comparator, or r if they are equal.

min

Returns the minimum of two values according to the given comparator, or l if they are equal.

natural

Returns a comparator that delegates to Ord.