Module std::cmp

Equality and comparison

Protocols

Functions

• fn compare<T>(a: &T, b: &T) -> Ordering

  T: Comparable<T>

  source

  Compare two values using the compare method of a type implementing the Comparable protocol.

  See Comparable for details.

• fn reversed<T>(a: &T, b: &T) -> Ordering

  T: Comparable<T>

  source

  Compare two values using the compare method of a type implementing the Comparable protocol, but in reverse order.

  Useful for sorting collections in descending order. See also compare.

  Example

  use std::cmp::{sort_by, reversed};
  
  let arr = [4, 8, 2, 9, 7, 10, 3, 1, 6, 5];
  arr[..].sort_by(reversed::<i32>);
  
  assert_eq!(arr[..], &[10, 9, 8, 7, 6, 5, 4, 3, 2, 1]);
  Run this example

• fn max<T>(a: T, b: T) -> T

  T: Comparable<T>

  source

  Returns the greater of the two arguments.

  Example

  use std::cmp::max;
  
  assert_eq!(max(1, 2), 2);
  Run this example

• fn min<T>(a: T, b: T) -> T

  T: Comparable<T>

  source

  Returns the least of the two arguments.

  Example

  use std::cmp::min;
  
  assert_eq!(min(1, 2), 1);
  Run this example

• fn is_sorted_by<T, F>(arr: &[T], f: F) -> bool

  F: CompareFunction<T>

  source

  Returns true if the array is sorted by the given comparison function.

  Example

  use std::cmp::is_sorted_by;
  
  let arr1 = [5, 3, 2, 4, 1];
  let arr2 = [1, 2, 3, 4, 5];
  
  assert!(!arr1[..].is_sorted_by(i32::compare));
  assert!(arr2[..].is_sorted_by(i32::compare));
  Run this example

• fn is_sorted_by_key<T, F, K>(arr: &[T], key: F) -> bool

  F: Fn(&T) -> K

  K: Comparable<K>

  source

  Returns true if the array is sorted using a key extraction function.

  Example

  use std::cmp::is_sorted_by_key;
  
  let arr = [(5, 1), (3, 2), (2, 3), (4, 4), (1, 5)];
  
  assert!(!arr[..].is_sorted_by_key(|e: &(i32, i32)| -> i32 { e.0 }));
  assert!(arr[..].is_sorted_by_key(|e: &(i32, i32)| -> i32 { e.1 }));
  Run this example

• fn is_sorted<T>(arr: &[T]) -> bool

  T: Comparable<T>

  source

  Returns true if the array is sorted.

  Example

  use std::cmp::is_sorted;
  
  let arr1 = [5, 3, 2, 4, 1];
  let arr2 = [1, 2, 3, 4, 5];
  
  assert!(!arr1[..].is_sorted());
  assert!(arr2[..].is_sorted());
  Run this example

• fn sort_by<T, F>(arr: &mut [T], f: F)

  F: CompareFunction<T>

  source

  Sorts a slice using a custom comparison function. The sort is unstable (i.e. does not preserve the order of equal elements).

  The algorithm used is introsort (quicksort with a fallback to heapsort and insertion sort when the recursion depth exceeds a certain limit and when the array is small, respectively).

  Example

  use std::cmp::{Ordering, sort_by};
  
  let arr = [4, 8, 2, 9, 7, 10, 3, 1, 6, 5];
  arr[..].sort_by(|a: &i32, b: &i32| -> Ordering { b.compare(a) });
  
  assert_eq!(arr[..], &[10, 9, 8, 7, 6, 5, 4, 3, 2, 1]);
  Run this example

• fn sort_by_key<T, F, K>(arr: &mut [T], key: F)

  F: Fn(&T) -> K

  K: Comparable<K>

  source

  Sorts a slice using a key extraction function. The sort is unstable (i.e. does not preserve the order of equal elements).

  The algorithm used is introsort (quicksort with a fallback to heapsort and insertion sort when the recursion depth exceeds a certain limit and when the array is small, respectively).

  Example

  use std::cmp::sort_by_key;
  
  let arr = [4, 8, 2, 9, 7, 10, 3, 1, 6, 5];
  arr[..].sort_by_key(|v: &i32| -> i32 { -*v });
  
  assert_eq!(arr[..], &[10, 9, 8, 7, 6, 5, 4, 3, 2, 1]);
  Run this example

• fn sort<T>(arr: &mut [T])

  T: Comparable<T>

  source

  Sorts a slice. The sort is unstable (i.e. does not preserve the order of equal elements).

  The algorithm used is introsort (quicksort with a fallback to heapsort and insertion sort when the recursion depth exceeds a certain limit and when the array is small, respectively).

  Example

  use std::cmp::sort;
  
  let arr = [4, 8, 2, 9, 7, 10, 3, 1, 6, 5];
  arr[..].sort();
  
  assert_eq!(arr[..], &[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
  Run this example

• fn stable_sort_by<T, F>(arr: &mut [T], f: F)

  F: CompareFunction<T>

  source

  Sorts a slice using a custom comparison function. The sort is stable (i.e. preserves the order of equal elements).

  The algorithm used is mergesort. it internally allocates a temporary buffer the size of the slice.

  Example

  use std::cmp::{Ordering, stable_sort_by};
  
  let arr = [4, 8, 2, 9, 7, 10, 3, 1, 6, 5];
  arr[..].stable_sort_by(|a: &i32, b: &i32| -> Ordering { b.compare(a) });
  
  assert_eq!(arr[..], &[10, 9, 8, 7, 6, 5, 4, 3, 2, 1]);
  Run this example

• fn stable_sort_by_key<T, F, K>(arr: &mut [T], key: F)

  F: Fn(&T) -> K

  K: Comparable<K>

  source

  Sorts a slice using a key extraction function. The sort is stable (i.e. preserves the order of equal elements).

  The algorithm used is mergesort. it internally allocates a temporary buffer the size of the slice.

  Example

  use std::cmp::stable_sort_by_key;
  
  let arr = [4, 8, 2, 9, 7, 10, 3, 1, 6, 5];
  arr[..].stable_sort_by_key(|v: &i32| -> i32 { -*v });
  
  assert_eq!(arr[..], &[10, 9, 8, 7, 6, 5, 4, 3, 2, 1]);
  Run this example

• fn stable_sort<T>(arr: &mut [T])

  T: Comparable<T>

  source

  Sorts a slice. The sort is stable (i.e. preserves the order of equal elements).

  The algorithm used is mergesort. it internally allocates a temporary buffer the size of the slice.

  Example

  use std::cmp::stable_sort;
  
  let arr = [4, 8, 2, 9, 7, 10, 3, 1, 6, 5];
  arr[..].stable_sort();
  
  assert_eq!(arr[..], &[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
  Run this example

• fn binary_search<T>(arr: &[T], needle: &T) -> Result<usize, usize>

  T: Comparable<T>

  source

  Performs a binary search on a sorted slice.

  If the element is found, returns Result::ok(index), otherwise returns the index where the element should be inserted as Result::err(index).

  Example

  use std::cmp::binary_search;
  
  let arr = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
  
  assert_eq!(arr[..].binary_search(&5), Result::ok(4usize));
  assert_eq!(arr[..].binary_search(&11), Result::err(10usize));
  Run this example

• fn binary_search_by<T, F>(arr: &[T], f: F) -> Result<usize, usize>

  F: Fn(&T) -> Ordering

  source

  Performs a binary search on a sorted slice using a custom comparison function.

  If the element is found, returns Result::ok(index), otherwise returns the index where the element should be inserted as Result::err(index).

  Example

  use std::cmp::{Ordering, binary_search_by};
  
  let arr = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
  
  assert_eq!(arr[..].binary_search_by(|k: &i32| -> Ordering { k.compare(&5) }), Result::ok(4usize));
  assert_eq!(arr[..].binary_search_by(|k: &i32| -> Ordering { k.compare(&11) }), Result::err(10usize));
  Run this example

• fn binary_search_by_key<T, F, K>(arr: &[T], needle: &K, key: F) -> Result<usize, usize>

  F: Fn(&T) -> K

  K: Comparable<K>

  source

  Performs a binary search on a sorted slice using a key extraction function.

  If the element is found, returns Result::ok(index), otherwise returns the index where the element should be inserted as Result::err(index).

  Example

  use std::cmp::binary_search_by_key;
  
  let arr = [
      (0, 0), (1, 2), (2, 4),
      (3, 6), (4, 8), (5, 10),
      (6, 12), (7, 14), (8, 16)
  ];
  
  assert_eq!(arr[..].binary_search_by_key(&5, |v: &(i32, i32)| -> i32 { v.0 }), Result::ok(5usize));
  assert_eq!(arr[..].binary_search_by_key(&11, |v: &(i32, i32)| -> i32 { v.0 }), Result::err(9usize));
  Run this example

Types

• type CompareFunction<T> = Fn(&T, &T) -> Ordering

  source

  Protocol for comparison functions.

  See Comparable for details.

Enums

Macros