alloc/collections/btree/set/
entry.rs

1use core::fmt::{self, Debug};
2
3use Entry::*;
4
5use super::{SetValZST, map};
6use crate::alloc::{Allocator, Global};
7
8/// A view into a single entry in a set, which may either be vacant or occupied.
9///
10/// This `enum` is constructed from the [`entry`] method on [`BTreeSet`].
11///
12/// [`BTreeSet`]: super::BTreeSet
13/// [`entry`]: super::BTreeSet::entry
14///
15/// # Examples
16///
17/// ```
18/// #![feature(btree_set_entry)]
19///
20/// use std::collections::btree_set::BTreeSet;
21///
22/// let mut set = BTreeSet::new();
23/// set.extend(["a", "b", "c"]);
24/// assert_eq!(set.len(), 3);
25///
26/// // Existing value (insert)
27/// let entry = set.entry("a");
28/// let _raw_o = entry.insert();
29/// assert_eq!(set.len(), 3);
30/// // Nonexistent value (insert)
31/// set.entry("d").insert();
32///
33/// // Existing value (or_insert)
34/// set.entry("b").or_insert();
35/// // Nonexistent value (or_insert)
36/// set.entry("e").or_insert();
37///
38/// println!("Our BTreeSet: {:?}", set);
39/// assert!(set.iter().eq(&["a", "b", "c", "d", "e"]));
40/// ```
41#[unstable(feature = "btree_set_entry", issue = "133549")]
42pub enum Entry<
43    'a,
44    T,
45    #[unstable(feature = "allocator_api", issue = "32838")] A: Allocator + Clone = Global,
46> {
47    /// An occupied entry.
48    ///
49    /// # Examples
50    ///
51    /// ```
52    /// #![feature(btree_set_entry)]
53    ///
54    /// use std::collections::btree_set::{Entry, BTreeSet};
55    ///
56    /// let mut set = BTreeSet::from(["a", "b"]);
57    ///
58    /// match set.entry("a") {
59    ///     Entry::Vacant(_) => unreachable!(),
60    ///     Entry::Occupied(_) => { }
61    /// }
62    /// ```
63    #[unstable(feature = "btree_set_entry", issue = "133549")]
64    Occupied(OccupiedEntry<'a, T, A>),
65
66    /// A vacant entry.
67    ///
68    /// # Examples
69    ///
70    /// ```
71    /// #![feature(btree_set_entry)]
72    ///
73    /// use std::collections::btree_set::{Entry, BTreeSet};
74    ///
75    /// let mut set = BTreeSet::new();
76    ///
77    /// match set.entry("a") {
78    ///     Entry::Occupied(_) => unreachable!(),
79    ///     Entry::Vacant(_) => { }
80    /// }
81    /// ```
82    #[unstable(feature = "btree_set_entry", issue = "133549")]
83    Vacant(VacantEntry<'a, T, A>),
84}
85
86#[unstable(feature = "btree_set_entry", issue = "133549")]
87impl<T: Debug + Ord, A: Allocator + Clone> Debug for Entry<'_, T, A> {
88    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
89        match *self {
90            Vacant(ref v) => f.debug_tuple("Entry").field(v).finish(),
91            Occupied(ref o) => f.debug_tuple("Entry").field(o).finish(),
92        }
93    }
94}
95
96/// A view into an occupied entry in a `BTreeSet`.
97/// It is part of the [`Entry`] enum.
98///
99/// # Examples
100///
101/// ```
102/// #![feature(btree_set_entry)]
103///
104/// use std::collections::btree_set::{Entry, BTreeSet};
105///
106/// let mut set = BTreeSet::new();
107/// set.extend(["a", "b", "c"]);
108///
109/// let _entry_o = set.entry("a").insert();
110/// assert_eq!(set.len(), 3);
111///
112/// // Existing key
113/// match set.entry("a") {
114///     Entry::Vacant(_) => unreachable!(),
115///     Entry::Occupied(view) => {
116///         assert_eq!(view.get(), &"a");
117///     }
118/// }
119///
120/// assert_eq!(set.len(), 3);
121///
122/// // Existing key (take)
123/// match set.entry("c") {
124///     Entry::Vacant(_) => unreachable!(),
125///     Entry::Occupied(view) => {
126///         assert_eq!(view.remove(), "c");
127///     }
128/// }
129/// assert_eq!(set.get(&"c"), None);
130/// assert_eq!(set.len(), 2);
131/// ```
132#[unstable(feature = "btree_set_entry", issue = "133549")]
133pub struct OccupiedEntry<
134    'a,
135    T,
136    #[unstable(feature = "allocator_api", issue = "32838")] A: Allocator + Clone = Global,
137> {
138    pub(super) inner: map::OccupiedEntry<'a, T, SetValZST, A>,
139}
140
141#[unstable(feature = "btree_set_entry", issue = "133549")]
142impl<T: Debug + Ord, A: Allocator + Clone> Debug for OccupiedEntry<'_, T, A> {
143    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
144        f.debug_struct("OccupiedEntry").field("value", self.get()).finish()
145    }
146}
147
148/// A view into a vacant entry in a `BTreeSet`.
149/// It is part of the [`Entry`] enum.
150///
151/// # Examples
152///
153/// ```
154/// #![feature(btree_set_entry)]
155///
156/// use std::collections::btree_set::{Entry, BTreeSet};
157///
158/// let mut set = BTreeSet::<&str>::new();
159///
160/// let entry_v = match set.entry("a") {
161///     Entry::Vacant(view) => view,
162///     Entry::Occupied(_) => unreachable!(),
163/// };
164/// entry_v.insert();
165/// assert!(set.contains("a") && set.len() == 1);
166///
167/// // Nonexistent key (insert)
168/// match set.entry("b") {
169///     Entry::Vacant(view) => view.insert(),
170///     Entry::Occupied(_) => unreachable!(),
171/// }
172/// assert!(set.contains("b") && set.len() == 2);
173/// ```
174#[unstable(feature = "btree_set_entry", issue = "133549")]
175pub struct VacantEntry<
176    'a,
177    T,
178    #[unstable(feature = "allocator_api", issue = "32838")] A: Allocator + Clone = Global,
179> {
180    pub(super) inner: map::VacantEntry<'a, T, SetValZST, A>,
181}
182
183#[unstable(feature = "btree_set_entry", issue = "133549")]
184impl<T: Debug + Ord, A: Allocator + Clone> Debug for VacantEntry<'_, T, A> {
185    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
186        f.debug_tuple("VacantEntry").field(self.get()).finish()
187    }
188}
189
190impl<'a, T: Ord, A: Allocator + Clone> Entry<'a, T, A> {
191    /// Sets the value of the entry, and returns an `OccupiedEntry`.
192    ///
193    /// # Examples
194    ///
195    /// ```
196    /// #![feature(btree_set_entry)]
197    ///
198    /// use std::collections::BTreeSet;
199    ///
200    /// let mut set = BTreeSet::new();
201    /// let entry = set.entry("horseyland").insert();
202    ///
203    /// assert_eq!(entry.get(), &"horseyland");
204    /// ```
205    #[inline]
206    #[unstable(feature = "btree_set_entry", issue = "133549")]
207    pub fn insert(self) -> OccupiedEntry<'a, T, A> {
208        match self {
209            Occupied(entry) => entry,
210            Vacant(entry) => entry.insert_entry(),
211        }
212    }
213
214    /// Ensures a value is in the entry by inserting if it was vacant.
215    ///
216    /// # Examples
217    ///
218    /// ```
219    /// #![feature(btree_set_entry)]
220    ///
221    /// use std::collections::BTreeSet;
222    ///
223    /// let mut set = BTreeSet::new();
224    ///
225    /// // nonexistent key
226    /// set.entry("poneyland").or_insert();
227    /// assert!(set.contains("poneyland"));
228    ///
229    /// // existing key
230    /// set.entry("poneyland").or_insert();
231    /// assert!(set.contains("poneyland"));
232    /// assert_eq!(set.len(), 1);
233    /// ```
234    #[inline]
235    #[unstable(feature = "btree_set_entry", issue = "133549")]
236    pub fn or_insert(self) {
237        if let Vacant(entry) = self {
238            entry.insert();
239        }
240    }
241
242    /// Returns a reference to this entry's value.
243    ///
244    /// # Examples
245    ///
246    /// ```
247    /// #![feature(btree_set_entry)]
248    ///
249    /// use std::collections::BTreeSet;
250    ///
251    /// let mut set = BTreeSet::new();
252    /// set.entry("poneyland").or_insert();
253    ///
254    /// // existing key
255    /// assert_eq!(set.entry("poneyland").get(), &"poneyland");
256    /// // nonexistent key
257    /// assert_eq!(set.entry("horseland").get(), &"horseland");
258    /// ```
259    #[inline]
260    #[unstable(feature = "btree_set_entry", issue = "133549")]
261    pub fn get(&self) -> &T {
262        match *self {
263            Occupied(ref entry) => entry.get(),
264            Vacant(ref entry) => entry.get(),
265        }
266    }
267}
268
269impl<'a, T: Ord, A: Allocator + Clone> OccupiedEntry<'a, T, A> {
270    /// Gets a reference to the value in the entry.
271    ///
272    /// # Examples
273    ///
274    /// ```
275    /// #![feature(btree_set_entry)]
276    ///
277    /// use std::collections::btree_set::{Entry, BTreeSet};
278    ///
279    /// let mut set = BTreeSet::new();
280    /// set.entry("poneyland").or_insert();
281    ///
282    /// match set.entry("poneyland") {
283    ///     Entry::Vacant(_) => panic!(),
284    ///     Entry::Occupied(entry) => assert_eq!(entry.get(), &"poneyland"),
285    /// }
286    /// ```
287    #[inline]
288    #[unstable(feature = "btree_set_entry", issue = "133549")]
289    pub fn get(&self) -> &T {
290        self.inner.key()
291    }
292
293    /// Takes the value out of the entry, and returns it.
294    ///
295    /// # Examples
296    ///
297    /// ```
298    /// #![feature(btree_set_entry)]
299    ///
300    /// use std::collections::BTreeSet;
301    /// use std::collections::btree_set::Entry;
302    ///
303    /// let mut set = BTreeSet::new();
304    /// set.entry("poneyland").or_insert();
305    ///
306    /// if let Entry::Occupied(o) = set.entry("poneyland") {
307    ///     assert_eq!(o.remove(), "poneyland");
308    /// }
309    ///
310    /// assert_eq!(set.contains("poneyland"), false);
311    /// ```
312    #[inline]
313    #[unstable(feature = "btree_set_entry", issue = "133549")]
314    pub fn remove(self) -> T {
315        self.inner.remove_entry().0
316    }
317}
318
319impl<'a, T: Ord, A: Allocator + Clone> VacantEntry<'a, T, A> {
320    /// Gets a reference to the value that would be used when inserting
321    /// through the `VacantEntry`.
322    ///
323    /// # Examples
324    ///
325    /// ```
326    /// #![feature(btree_set_entry)]
327    ///
328    /// use std::collections::BTreeSet;
329    ///
330    /// let mut set = BTreeSet::new();
331    /// assert_eq!(set.entry("poneyland").get(), &"poneyland");
332    /// ```
333    #[inline]
334    #[unstable(feature = "btree_set_entry", issue = "133549")]
335    pub fn get(&self) -> &T {
336        self.inner.key()
337    }
338
339    /// Take ownership of the value.
340    ///
341    /// # Examples
342    ///
343    /// ```
344    /// #![feature(btree_set_entry)]
345    ///
346    /// use std::collections::btree_set::{Entry, BTreeSet};
347    ///
348    /// let mut set = BTreeSet::new();
349    ///
350    /// match set.entry("poneyland") {
351    ///     Entry::Occupied(_) => panic!(),
352    ///     Entry::Vacant(v) => assert_eq!(v.into_value(), "poneyland"),
353    /// }
354    /// ```
355    #[inline]
356    #[unstable(feature = "btree_set_entry", issue = "133549")]
357    pub fn into_value(self) -> T {
358        self.inner.into_key()
359    }
360
361    /// Sets the value of the entry with the VacantEntry's value.
362    ///
363    /// # Examples
364    ///
365    /// ```
366    /// #![feature(btree_set_entry)]
367    ///
368    /// use std::collections::BTreeSet;
369    /// use std::collections::btree_set::Entry;
370    ///
371    /// let mut set = BTreeSet::new();
372    ///
373    /// if let Entry::Vacant(o) = set.entry("poneyland") {
374    ///     o.insert();
375    /// }
376    /// assert!(set.contains("poneyland"));
377    /// ```
378    #[inline]
379    #[unstable(feature = "btree_set_entry", issue = "133549")]
380    pub fn insert(self) {
381        self.inner.insert(SetValZST);
382    }
383
384    #[inline]
385    fn insert_entry(self) -> OccupiedEntry<'a, T, A> {
386        OccupiedEntry { inner: self.inner.insert_entry(SetValZST) }
387    }
388}
alloc/collections/btree/set/entry.rs

alloc/collections/btree/set/
entry.rs
