Struct BTreeSet
struct BTreeSet<T, A: Allocator + Clone = crate::alloc::Global> { ... }
An ordered set based on a B-Tree.
See BTreeMap's documentation for a detailed discussion of this collection's performance
benefits and drawbacks.
It is a logic error for an item to be modified in such a way that the item's ordering relative
to any other item, as determined by the Ord trait, changes while it is in the set. This is
normally only possible through Cell, RefCell, global state, I/O, or unsafe code.
The behavior resulting from such a logic error is not specified, but will be encapsulated to the
BTreeSet that observed the logic error and not result in undefined behavior. This could
include panics, incorrect results, aborts, memory leaks, and non-termination.
Iterators returned by BTreeSet::iter and BTreeSet::into_iter produce their items in order, and take worst-case
logarithmic and amortized constant time per item returned.
Examples
use BTreeSet;
// Type inference lets us omit an explicit type signature (which
// would be `BTreeSet<&str>` in this example).
let mut books = new;
// Add some books.
books.insert;
books.insert;
books.insert;
books.insert;
// Check for a specific one.
if !books.contains
// Remove a book.
books.remove;
// Iterate over everything.
for book in &books
A BTreeSet with a known list of items can be initialized from an array:
use BTreeSet;
let set = from;
Implementations
impl<T> BTreeSet<T>
const fn new() -> BTreeSet<T>Makes a new, empty
BTreeSet.Does not allocate anything on its own.
Examples
# use BTreeSet; let mut set: = new;
impl<T, A: Allocator + Clone> BTreeSet<T, A>
const fn new_in(alloc: A) -> BTreeSet<T, A>Makes a new
BTreeSetwith a reasonable choice of B.Examples
# # # use BTreeSet; use Global; let mut set: = new_in;fn range<K, R>(self: &Self, range: R) -> Range<'_, T> where K: Ord + ?Sized, T: Borrow<K> + Ord, R: RangeBounds<K>Constructs a double-ended iterator over a sub-range of elements in the set. The simplest way is to use the range syntax
min..max, thusrange(min..max)will yield elements from min (inclusive) to max (exclusive). The range may also be entered as(Bound<T>, Bound<T>), so for examplerange((Excluded(4), Included(10)))will yield a left-exclusive, right-inclusive range from 4 to 10.Panics
Panics if range
start > end. Panics if rangestart == endand both bounds areExcluded.Examples
use BTreeSet; use Included; let mut set = new; set.insert; set.insert; set.insert; for &elem in set.range assert_eq!;fn difference<'a>(self: &'a Self, other: &'a BTreeSet<T, A>) -> Difference<'a, T, A> where T: OrdVisits the elements representing the difference, i.e., the elements that are in
selfbut not inother, in ascending order.Examples
use BTreeSet; let mut a = new; a.insert; a.insert; let mut b = new; b.insert; b.insert; let diff: = a.difference.cloned.collect; assert_eq!;fn symmetric_difference<'a>(self: &'a Self, other: &'a BTreeSet<T, A>) -> SymmetricDifference<'a, T> where T: OrdVisits the elements representing the symmetric difference, i.e., the elements that are in
selfor inotherbut not in both, in ascending order.Examples
use BTreeSet; let mut a = new; a.insert; a.insert; let mut b = new; b.insert; b.insert; let sym_diff: = a.symmetric_difference.cloned.collect; assert_eq!;fn intersection<'a>(self: &'a Self, other: &'a BTreeSet<T, A>) -> Intersection<'a, T, A> where T: OrdVisits the elements representing the intersection, i.e., the elements that are both in
selfandother, in ascending order.Examples
use BTreeSet; let mut a = new; a.insert; a.insert; let mut b = new; b.insert; b.insert; let intersection: = a.intersection.cloned.collect; assert_eq!;fn union<'a>(self: &'a Self, other: &'a BTreeSet<T, A>) -> Union<'a, T> where T: OrdVisits the elements representing the union, i.e., all the elements in
selforother, without duplicates, in ascending order.Examples
use BTreeSet; let mut a = new; a.insert; let mut b = new; b.insert; let union: = a.union.cloned.collect; assert_eq!;fn clear(self: &mut Self) where A: CloneClears the set, removing all elements.
Examples
use BTreeSet; let mut v = new; v.insert; v.clear; assert!;fn contains<Q>(self: &Self, value: &Q) -> bool where T: Borrow<Q> + Ord, Q: Ord + ?SizedReturns
trueif the set contains an element equal to the value.The value may be any borrowed form of the set's element type, but the ordering on the borrowed form must match the ordering on the element type.
Examples
use BTreeSet; let set = from; assert_eq!; assert_eq!;fn get<Q>(self: &Self, value: &Q) -> Option<&T> where T: Borrow<Q> + Ord, Q: Ord + ?SizedReturns a reference to the element in the set, if any, that is equal to the value.
The value may be any borrowed form of the set's element type, but the ordering on the borrowed form must match the ordering on the element type.
Examples
use BTreeSet; let set = from; assert_eq!; assert_eq!;fn is_disjoint(self: &Self, other: &BTreeSet<T, A>) -> bool where T: OrdReturns
trueifselfhas no elements in common withother. This is equivalent to checking for an empty intersection.Examples
use BTreeSet; let a = from; let mut b = new; assert_eq!; b.insert; assert_eq!; b.insert; assert_eq!;fn is_subset(self: &Self, other: &BTreeSet<T, A>) -> bool where T: OrdReturns
trueif the set is a subset of another, i.e.,othercontains at least all the elements inself.Examples
use BTreeSet; let sup = from; let mut set = new; assert_eq!; set.insert; assert_eq!; set.insert; assert_eq!;fn is_superset(self: &Self, other: &BTreeSet<T, A>) -> bool where T: OrdReturns
trueif the set is a superset of another, i.e.,selfcontains at least all the elements inother.Examples
use BTreeSet; let sub = from; let mut set = new; assert_eq!; set.insert; set.insert; assert_eq!; set.insert; assert_eq!;fn first(self: &Self) -> Option<&T> where T: OrdReturns a reference to the first element in the set, if any. This element is always the minimum of all elements in the set.
Examples
Basic usage:
use BTreeSet; let mut set = new; assert_eq!; set.insert; assert_eq!; set.insert; assert_eq!;fn last(self: &Self) -> Option<&T> where T: OrdReturns a reference to the last element in the set, if any. This element is always the maximum of all elements in the set.
Examples
Basic usage:
use BTreeSet; let mut set = new; assert_eq!; set.insert; assert_eq!; set.insert; assert_eq!;fn pop_first(self: &mut Self) -> Option<T> where T: OrdRemoves the first element from the set and returns it, if any. The first element is always the minimum element in the set.
Examples
use BTreeSet; let mut set = new; set.insert; while let Some = set.pop_first assert!;fn pop_last(self: &mut Self) -> Option<T> where T: OrdRemoves the last element from the set and returns it, if any. The last element is always the maximum element in the set.
Examples
use BTreeSet; let mut set = new; set.insert; while let Some = set.pop_last assert!;fn insert(self: &mut Self, value: T) -> bool where T: OrdAdds a value to the set.
Returns whether the value was newly inserted. That is:
- If the set did not previously contain an equal value,
trueis returned. - If the set already contained an equal value,
falseis returned, and the entry is not updated.
See the module-level documentation for more.
Examples
use BTreeSet; let mut set = new; assert_eq!; assert_eq!; assert_eq!;- If the set did not previously contain an equal value,
fn replace(self: &mut Self, value: T) -> Option<T> where T: OrdAdds a value to the set, replacing the existing element, if any, that is equal to the value. Returns the replaced element.
Examples
use BTreeSet; let mut set = new; set.insert; assert_eq!; set.replace; assert_eq!;fn get_or_insert(self: &mut Self, value: T) -> &T where T: OrdInserts the given
valueinto the set if it is not present, then returns a reference to the value in the set.Examples
use BTreeSet; let mut set = from; assert_eq!; assert_eq!; assert_eq!; assert_eq!; // 100 was insertedfn get_or_insert_with<Q, F>(self: &mut Self, value: &Q, f: F) -> &T where T: Borrow<Q> + Ord, Q: Ord + ?Sized, F: FnOnce(&Q) -> TInserts a value computed from
finto the set if the givenvalueis not present, then returns a reference to the value in the set.Examples
use BTreeSet; let mut set: = .iter.map.collect; assert_eq!; for &pet in & assert_eq!; // a new "fish" was insertedfn entry(self: &mut Self, value: T) -> Entry<'_, T, A> where T: OrdGets the given value's corresponding entry in the set for in-place manipulation.
Examples
use BTreeSet; use *; let mut singles = new; let mut dupes = new; for ch in "a short treatise on fungi".chars assert!; assert!; assert!;fn remove<Q>(self: &mut Self, value: &Q) -> bool where T: Borrow<Q> + Ord, Q: Ord + ?SizedIf the set contains an element equal to the value, removes it from the set and drops it. Returns whether such an element was present.
The value may be any borrowed form of the set's element type, but the ordering on the borrowed form must match the ordering on the element type.
Examples
use BTreeSet; let mut set = new; set.insert; assert_eq!; assert_eq!;fn take<Q>(self: &mut Self, value: &Q) -> Option<T> where T: Borrow<Q> + Ord, Q: Ord + ?SizedRemoves and returns the element in the set, if any, that is equal to the value.
The value may be any borrowed form of the set's element type, but the ordering on the borrowed form must match the ordering on the element type.
Examples
use BTreeSet; let mut set = from; assert_eq!; assert_eq!;fn retain<F>(self: &mut Self, f: F) where T: Ord, F: FnMut(&T) -> boolRetains only the elements specified by the predicate.
In other words, remove all elements
efor whichf(&e)returnsfalse. The elements are visited in ascending order.Examples
use BTreeSet; let mut set = from; // Keep only the even numbers. set.retain; assert!;fn append(self: &mut Self, other: &mut Self) where T: Ord, A: CloneMoves all elements from
otherintoself, leavingotherempty.Examples
use BTreeSet; let mut a = new; a.insert; a.insert; a.insert; let mut b = new; b.insert; b.insert; b.insert; a.append; assert_eq!; assert_eq!; assert!; assert!; assert!; assert!; assert!;fn split_off<Q: ?Sized + Ord>(self: &mut Self, value: &Q) -> Self where T: Borrow<Q> + Ord, A: CloneSplits the collection into two at the value. Returns a new collection with all elements greater than or equal to the value.
Examples
Basic usage:
use BTreeSet; let mut a = new; a.insert; a.insert; a.insert; a.insert; a.insert; let b = a.split_off; assert_eq!; assert_eq!; assert!; assert!; assert!; assert!; assert!;fn extract_if<F, R>(self: &mut Self, range: R, pred: F) -> ExtractIf<'_, T, R, F, A> where T: Ord, R: RangeBounds<T>, F: FnMut(&T) -> boolCreates an iterator that visits elements in the specified range in ascending order and uses a closure to determine if an element should be removed.
If the closure returns
true, the element is removed from the set and yielded. If the closure returnsfalse, or panics, the element remains in the set and will not be yielded.If the returned
ExtractIfis not exhausted, e.g. because it is dropped without iterating or the iteration short-circuits, then the remaining elements will be retained. Useextract_if().for_each(drop)if you do not need the returned iterator, orretainwith a negated predicate if you also do not need to restrict the range.Examples
use BTreeSet; // Splitting a set into even and odd values, reusing the original set: let mut set: = .collect; let evens: = set.extract_if.collect; let odds = set; assert_eq!; assert_eq!; // Splitting a set into low and high halves, reusing the original set: let mut set: = .collect; let low: = set.extract_if.collect; let high = set; assert_eq!; assert_eq!;fn iter(self: &Self) -> Iter<'_, T>Gets an iterator that visits the elements in the
BTreeSetin ascending order.Examples
use BTreeSet; let set = from; let mut set_iter = set.iter; assert_eq!; assert_eq!; assert_eq!; assert_eq!;const fn len(self: &Self) -> usizeReturns the number of elements in the set.
Examples
use BTreeSet; let mut v = new; assert_eq!; v.insert; assert_eq!;const fn is_empty(self: &Self) -> boolReturns
trueif the set contains no elements.Examples
use BTreeSet; let mut v = new; assert!; v.insert; assert!;fn lower_bound<Q>(self: &Self, bound: Bound<&Q>) -> Cursor<'_, T> where T: Borrow<Q> + Ord, Q: Ord + ?SizedReturns a
Cursorpointing at the gap before the smallest element greater than the given bound.Passing
Bound::Included(x)will return a cursor pointing to the gap before the smallest element greater than or equal tox.Passing
Bound::Excluded(x)will return a cursor pointing to the gap before the smallest element greater thanx.Passing
Bound::Unboundedwill return a cursor pointing to the gap before the smallest element in the set.Examples
use BTreeSet; use Bound; let set = from; let cursor = set.lower_bound; assert_eq!; assert_eq!; let cursor = set.lower_bound; assert_eq!; assert_eq!; let cursor = set.lower_bound; assert_eq!; assert_eq!;fn lower_bound_mut<Q>(self: &mut Self, bound: Bound<&Q>) -> CursorMut<'_, T, A> where T: Borrow<Q> + Ord, Q: Ord + ?SizedReturns a
CursorMutpointing at the gap before the smallest element greater than the given bound.Passing
Bound::Included(x)will return a cursor pointing to the gap before the smallest element greater than or equal tox.Passing
Bound::Excluded(x)will return a cursor pointing to the gap before the smallest element greater thanx.Passing
Bound::Unboundedwill return a cursor pointing to the gap before the smallest element in the set.Examples
use BTreeSet; use Bound; let mut set = from; let mut cursor = set.lower_bound_mut; assert_eq!; assert_eq!; let mut cursor = set.lower_bound_mut; assert_eq!; assert_eq!; let mut cursor = set.lower_bound_mut; assert_eq!; assert_eq!;fn upper_bound<Q>(self: &Self, bound: Bound<&Q>) -> Cursor<'_, T> where T: Borrow<Q> + Ord, Q: Ord + ?SizedReturns a
Cursorpointing at the gap after the greatest element smaller than the given bound.Passing
Bound::Included(x)will return a cursor pointing to the gap after the greatest element smaller than or equal tox.Passing
Bound::Excluded(x)will return a cursor pointing to the gap after the greatest element smaller thanx.Passing
Bound::Unboundedwill return a cursor pointing to the gap after the greatest element in the set.Examples
use BTreeSet; use Bound; let set = from; let cursor = set.upper_bound; assert_eq!; assert_eq!; let cursor = set.upper_bound; assert_eq!; assert_eq!; let cursor = set.upper_bound; assert_eq!; assert_eq!;fn upper_bound_mut<Q>(self: &mut Self, bound: Bound<&Q>) -> CursorMut<'_, T, A> where T: Borrow<Q> + Ord, Q: Ord + ?SizedReturns a
CursorMutpointing at the gap after the greatest element smaller than the given bound.Passing
Bound::Included(x)will return a cursor pointing to the gap after the greatest element smaller than or equal tox.Passing
Bound::Excluded(x)will return a cursor pointing to the gap after the greatest element smaller thanx.Passing
Bound::Unboundedwill return a cursor pointing to the gap after the greatest element in the set.Examples
use BTreeSet; use Bound; let mut set = from; let mut cursor = set.upper_bound_mut; assert_eq!; assert_eq!; let mut cursor = set.upper_bound_mut; assert_eq!; assert_eq!; let mut cursor = set.upper_bound_mut; assert_eq!; assert_eq!;
impl<'a, T: 'a + Ord + Copy, A: Allocator + Clone> Extend for BTreeSet<T, A>
fn extend<I: IntoIterator<Item = &'a T>>(self: &mut Self, iter: I)fn extend_one(self: &mut Self, elem: &'a T)
impl<T> Any for BTreeSet<T, A>
fn type_id(self: &Self) -> TypeId
impl<T> Borrow for BTreeSet<T, A>
fn borrow(self: &Self) -> &T
impl<T> BorrowMut for BTreeSet<T, A>
fn borrow_mut(self: &mut Self) -> &mut T
impl<T> CloneToUninit for BTreeSet<T, A>
unsafe fn clone_to_uninit(self: &Self, dest: *mut u8)
impl<T> Default for BTreeSet<T>
fn default() -> BTreeSet<T>Creates an empty
BTreeSet.
impl<T> From for BTreeSet<T, A>
fn from(t: T) -> TReturns the argument unchanged.
impl<T> ToOwned for BTreeSet<T, A>
fn to_owned(self: &Self) -> Tfn clone_into(self: &Self, target: &mut T)
impl<T, A> Freeze for BTreeSet<T, A>
impl<T, A> RefUnwindSafe for BTreeSet<T, A>
impl<T, A> Send for BTreeSet<T, A>
impl<T, A> Sync for BTreeSet<T, A>
impl<T, A> Unpin for BTreeSet<T, A>
impl<T, A> UnsafeUnpin for BTreeSet<T, A>
impl<T, A> UnwindSafe for BTreeSet<T, A>
impl<T, A: Allocator + Clone> IntoIterator for BTreeSet<T, A>
fn into_iter(self: Self) -> IntoIter<T, A>Gets an iterator for moving out the
BTreeSet's contents in ascending order.Examples
use BTreeSet; let set = from; let v: = set.into_iter.collect; assert_eq!;
impl<T, U> Into for BTreeSet<T, A>
fn into(self: Self) -> UCalls
U::from(self).That is, this conversion is whatever the implementation of
[From]<T> for Uchooses to do.
impl<T, U> TryFrom for BTreeSet<T, A>
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
impl<T, U> TryInto for BTreeSet<T, A>
fn try_into(self: Self) -> Result<U, <U as TryFrom<T>>::Error>
impl<T: Clone, A: Allocator + Clone> Clone for BTreeSet<T, A>
fn clone(self: &Self) -> Selffn clone_from(self: &mut Self, source: &Self)
impl<T: Debug, A: Allocator + Clone> Debug for BTreeSet<T, A>
fn fmt(self: &Self, f: &mut Formatter<'_>) -> Result
impl<T: Eq, A: Allocator + Clone> Eq for BTreeSet<T, A>
impl<T: Hash, A: Allocator + Clone> Hash for BTreeSet<T, A>
fn hash<H: Hasher>(self: &Self, state: &mut H)
impl<T: Ord> FromIterator for BTreeSet<T>
fn from_iter<I: IntoIterator<Item = T>>(iter: I) -> BTreeSet<T>
impl<T: Ord, A: Allocator + Clone> Extend for BTreeSet<T, A>
fn extend<Iter: IntoIterator<Item = T>>(self: &mut Self, iter: Iter)fn extend_one(self: &mut Self, elem: T)
impl<T: Ord, A: Allocator + Clone> Ord for BTreeSet<T, A>
fn cmp(self: &Self, other: &BTreeSet<T, A>) -> Ordering
impl<T: Ord, N: usize> From for BTreeSet<T>
fn from(arr: [T; N]) -> SelfConverts a
[T; N]into aBTreeSet<T>.If the array contains any equal values, all but one will be dropped.
Examples
use BTreeSet; let set1 = from; let set2: = .into; assert_eq!;
impl<T: PartialEq, A: Allocator + Clone> PartialEq for BTreeSet<T, A>
fn eq(self: &Self, other: &BTreeSet<T, A>) -> bool
impl<T: PartialOrd, A: Allocator + Clone> PartialOrd for BTreeSet<T, A>
fn partial_cmp(self: &Self, other: &BTreeSet<T, A>) -> Option<Ordering>