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 |
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 |
min |
Returns the minimum of two values according to the given comparator, or |
natural |
Returns a comparator that delegates to |