maplike 0.12.4

Derive macros for maplike.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105

// SPDX-FileCopyrightText: 2025 maplike contributors
//
// SPDX-License-Identifier: MIT OR Apache-2.0

use crate::containers::Container;

/// Gets the given key's corresponding entry in the container for in-place
/// manipulation.
pub trait Entry<K>: Container {
    /// Entry type returned by [`entry`](Entry::entry).
    type Entry<'a>
    where
        Self: 'a,
        K: 'a;

    /// Gets the given key's corresponding entry in the container for in-place
    /// manipulation.
    fn entry(&mut self, key: K) -> Self::Entry<'_>;
}

/// A view into a single entry in a map, which may either be vacant or occupied.
pub trait CombinedEntry<'a, K, V>: Sized {
    /// Occupied entry type returned by [`insert_entry`](CombinedEntry::insert_entry).
    type OccupiedEntry: OccupiedEntry<'a, K, V>;

    /// Returns a reference to this entry's key.
    fn key(&self) -> &K;

    /// Ensures a value is in the entry by inserting the default if empty, and
    /// returns a mutable reference to the value in the entry.
    fn or_insert(self, default: V) -> &'a mut V;

    /// Ensures a value is in the entry by inserting the result of the default
    /// function if empty, and returns a mutable reference to the value in the entry.
    fn or_insert_with<F>(self, default: F) -> &'a mut V
    where
        F: FnOnce() -> V;

    /// Ensures a value is in the entry by inserting, if empty, the result of
    /// the default function.
    fn or_insert_with_key<F>(self, default: F) -> &'a mut V
    where
        F: FnOnce(&K) -> V;

    /// Provides in-place mutable access to an occupied entry before any
    /// potential inserts into the map.
    fn and_modify<F>(self, f: F) -> Self
    where
        F: FnOnce(&mut V);

    /// Sets the value of the entry, and returns a `OccupiedEntry`.
    fn insert_entry(self, value: V) -> Self::OccupiedEntry;

    /// Ensures a value is in the entry by inserting the default value if empty,
    /// and returns a mutable reference to the value in the entry.
    fn or_default(self) -> &'a mut V
    where
        V: Default;
}

/// A view into an occupied entry in a `BTreeMap`.
pub trait OccupiedEntry<'a, K, V> {
    /// Gets a reference to the key in the entry.
    fn key(&self) -> &K;

    /// Gets a reference to the value in the entry.
    fn get(&self) -> &V;

    /// Gets a mutable reference to the value in the entry.
    fn get_mut(&mut self) -> &mut V;

    /// Converts the entry into a mutable reference to its value.
    fn into_mut(self) -> &'a mut V;

    /// Sets the value of the entry with this view's key, and returns the
    /// entry's old value.
    fn insert(&mut self, value: V) -> V;

    /// Takes the value of the entry out of the map, and returns it.
    fn remove(self) -> V;

    /// Take ownership of the key and value from the map.
    fn remove_entry(self) -> (K, V);
}

/// A view into a vacant entry in a `BTreeMap`.
pub trait VacantEntry<'a, K, V> {
    /// Occupied entry type returned by [`insert_entry`](VacantEntry::insert_entry).
    type OccupiedEntry: OccupiedEntry<'a, K, V>;

    /// Gets a reference to the key that would be used when inserting a value
    /// through the VacantEntry.
    fn key(&self) -> &K;

    /// Take ownership of the key.
    fn into_key(self) -> K;

    /// Sets the value of the entry with this view's key, and returns a mutable
    /// reference to it.
    fn insert(self, value: V) -> &'a mut V;

    /// Sets the value of the entry with this view's key, and returns an
    /// `OccupiedEntry`.
    fn insert_entry(self, value: V) -> Self::OccupiedEntry;
}