maplike 0.12.4

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

//! Individual container operation traits.

use core::borrow::Borrow;

use crate::containers::Container;

/// Construct a container with exactly one element.
pub trait WithOne<E>: Container {
    /// Construct a container containing only the given element.
    fn with_one(element: E) -> Self;
}

/// Replace self with a new value.
pub trait Assign<V = Self>: Container {
    /// Replace self with a new value.
    fn assign(&mut self, value: V);
}

/// Returns a reference to the value corresponding to the key.
pub trait Get<K, Q: ?Sized = K>: Container
where
    K: Borrow<Q>,
{
    /// Returns a reference to the value corresponding to the key.
    fn get(&self, key: &Q) -> Option<&Self::Value>;
}

/// Returns a reference to the right value corresponding to the given left value
/// in a bidirectional map.
///
/// Should be only implemented only for bidirectional maps (not for
/// unidirectional maps) along with [`GetByRight::get_by_right()`], and should
/// behave identically to [`Get`].
pub trait GetByLeft<K, Q: ?Sized = K>: Container
where
    K: Borrow<Q>,
{
    /// Returns a reference to the right value corresponding to the given left value.
    ///
    /// Should be only implemented only for bidirectional maps (not for
    /// unidirectional maps) along with [`GetByRight::get_by_right()`], and
    /// should behave identically to [`Get`].
    fn get_by_left(&self, key: &Q) -> Option<&Self::Value>;
}

/// Returns a reference to the left value corresponding to the given right value
/// in a bidirectional map.
///
/// Should be only implemented only for bidirectional maps (not for
/// unidirectional maps) along with [`GetByLeft::get_by_left()`].
///
/// Note that key and value are unusually inverted here: `Self::Value` is
/// actually the key, while `K` is the value.
pub trait GetByRight<K, Q: ?Sized = <Self as Container>::Value>: Container
where
    Self::Value: Borrow<Q>,
{
    /// Returns a reference to the right value corresponding to the given left value.
    ///
    /// Should be only implemented only for bidirectional maps (not for
    /// unidirectional maps) along with [`GetByLeft::get_by_left()`].
    ///
    /// Note that key and value are unusually inverted here: `Self::Value` is
    /// actually the key, while `K` is the value.
    fn get_by_right(&self, key: &Q) -> Option<&K>;
}

/// Set the value of an already existing element under a key.
///
/// Unlike [`insert`](Insert::insert), the key must already exist in the
/// container.
pub trait Set<K>: Container {
    /// Return type of [`set`](Set::set).
    type Output;

    /// Set the value of an already existing element under a key.
    ///
    /// Unlike [`insert`](Insert::insert), the key must already exist in the
    /// container.
    fn set(&mut self, key: K, value: Self::Value) -> Self::Output;
}

/// Modify the value under key with a closure.
///
/// This is useful if something always has to be done before or after the
/// modification to maintain an invariant.
pub trait Modify<K, Q: ?Sized = K>: Container
where
    K: Borrow<Q>,
{
    /// Modify the value under key with a closure.
    ///
    /// This is useful if something always has to be done before or after the
    /// modification to maintain an invariant.
    fn modify<F>(&mut self, key: &Q, f: F)
    where
        F: FnOnce(&mut Self::Value);
}

/// Insert a new key-value pair into the container at an arbitrary key.
///
/// The key can but does not have to already exist in the container.
pub trait Insert<K>: Container {
    /// Return type of [`insert`](Insert::insert).
    type Output;

    /// Insert a new key-value pair into the container at an arbitrary key.
    ///
    /// The key can but does not have to already exist in the container.
    fn insert(&mut self, key: K, value: Self::Value) -> Self::Output;
}

/// Remove an element under a key from the collection, returning the value
/// at the key if the key was previously in the map. Other keys are not
/// invalidated.
///
/// [`Vec`](https://doc.rust-lang.org/alloc/vec/struct.Vec.html) obviously does
/// not implement this trait because its element removal methods,
/// [`Vec::remove()`](https://doc.rust-lang.org/alloc/vec/struct.Vec.html#method.remove)
/// and
/// [`Vec::swap_remove()`](https://doc.rust-lang.org/alloc/vec/struct.Vec.html#method.swap_remove),
/// invalidate existing indices.
///
/// If you need this trait on a contiguous data type with constant-time
/// insertion, lookup, and removal, try
/// [`stable_vec::StableVec`](https://docs.rs/stable-vec/latest/stable_vec/type.StableVec.html)
/// or [`thunderdome::Arena`](https://docs.rs/thunderdome/latest/thunderdome/struct.Arena.html).
pub trait Remove<K, Q: ?Sized = K>: Container
where
    K: Borrow<Q>,
{
    /// Remove an element under a key from the collection, returning the value
    /// at the key if the key was previously in the map. Other keys are not
    /// invalidated.
    ///
    /// [`Vec`](https://doc.rust-lang.org/alloc/vec/struct.Vec.html) obviously
    /// does not implement this trait because its element removal methods,
    /// [`Vec::remove()`](https://doc.rust-lang.org/alloc/vec/struct.Vec.html#method.remove)
    /// and
    /// [`Vec::swap_remove()`](https://doc.rust-lang.org/alloc/vec/struct.Vec.html#method.swap_remove),
    /// invalidate existing indices.
    ///
    /// If you need this trait on a contiguous data type with constant-time
    /// insertion, lookup, and removal, try
    /// [`stable_vec::StableVec`](https://docs.rs/stable-vec/latest/stable_vec/type.StableVec.html)
    /// or [`thunderdome::Arena`](https://docs.rs/thunderdome/latest/thunderdome/struct.Arena.html).
    fn remove(&mut self, key: &Q) -> Option<Self::Value>;
}

/// Remove the left and right values from pair corresponding to the given left
/// value in a bidirectional map.
///
/// Should be only implemented only for bidirectional maps (not for
/// unidirectional maps) along with [`RemoveByRight::remove_by_right()`], and should
/// behave identically to [`Remove`].
pub trait RemoveByLeft<K, Q: ?Sized = K>: Container
where
    K: Borrow<Q>,
{
    /// Remove the left and right values from pair corresponding to the given
    /// left value in a bidirectional map.
    ///
    /// Should be only implemented only for bidirectional maps (not for
    /// unidirectional maps) along with [`RemoveByRight::remove_by_right()`],
    /// and should behave identically to [`Remove`].
    fn remove_by_left(&mut self, key: &Q) -> Option<Self::Value>;
}

/// Remove the left and right values from pair corresponding to the given right
/// value in a bidirectional map.
///
/// Should be only implemented only for bidirectional maps (not for
/// unidirectional maps) along with [`RemoveByLeft::remove_by_left()`].
///
/// Note that key and value are unusually inverted here: `Self::Value` is
/// actually the key, while `K` is the value.
pub trait RemoveByRight<K, Q: ?Sized = <Self as Container>::Value>: Container
where
    Self::Value: Borrow<Q>,
{
    /// Remove the left and right values from pair corresponding to the given
    /// right value in a bidirectional map.
    ///
    /// Should be only implemented only for bidirectional maps (not for
    /// unidirectional maps) along with [`RemoveByLeft::remove_by_left()`].
    ///
    /// Note that key and value are unusually inverted here: `Self::Value` is
    /// actually the key, while `K` is the value.
    fn remove_by_right(&mut self, key: &Q) -> Option<K>;
}

/// Insert a value into the collection without specifying a key, returning
/// the key that was automatically generated.
pub trait Push<K>: Container {
    /// Insert a value into the collection without specifying a key, returning
    /// the key that was automatically generated.
    fn push(&mut self, value: Self::Value) -> K;
}

/// Remove the last element of the collection, returning it.
///
/// If `Push` is also implemented, calling `Pop` should revert the previous
/// pushes in their reversed order.
pub trait Pop: Container {
    /// Remove the last element of the collection, returning it.
    ///
    /// If `Push` is also implemented, calling `Pop` should revert the previous
    /// pushes in their reversed order.
    fn pop(&mut self) -> Option<Self::Value>;
}

/// Put a new value in the container.
///
/// This is basically [`push`](Push::push), but unlike it:
///
/// - it also works for sets,
/// - it does not matter what is the key,
/// - in some containers, `.put()` may evict elements.
///
/// If the insertion has happened to evict (aka. override or displace) an existing element,
/// this element is returned.
pub trait Put<E>: Container {
    /// Put a new value in the container.
    ///
    /// This is basically [`push`](Push::push), but unlike it:
    ///
    /// - it also works for sets,
    /// - it does not matter what is the key,
    /// - in some containers, `.put()` may evict elements.
    ///
    /// If the insertion has happened to evict (aka. override or displace) an existing element,
    /// this element is returned.
    fn put(&mut self, element: E) -> Option<E>;
}

/// Remove all elements from the collection.
pub trait Clear: Container {
    /// Remove all elements from the collection.
    fn clear(&mut self);
}

/// Returns the length of the collection.
///
/// Should be only implemented for truly contiguous data structures, for which
/// it makes sense to have a `.pop()` operation. Currently
/// [`Vec`](https://doc.rust-lang.org/alloc/vec/struct.Vec.html) and
/// [`tinyvec::ArrayVec`](https://docs.rs/tinyvec/latest/tinyvec/struct.ArrayVec.html)
/// satisfy this property.
pub trait Len: Container {
    /// Returns the length of the collection.
    ///
    /// Should be only implemented for truly contiguous data structures, for which
    /// it makes sense to have a `.pop()` operation. Currently
    /// [`Vec`](https://doc.rust-lang.org/alloc/vec/struct.Vec.html) and
    /// [`tinyvec::ArrayVec`](https://docs.rs/tinyvec/latest/tinyvec/struct.ArrayVec.html)
    /// satisfy this property.
    fn len(&self) -> Self::Key;
}

/// Resize the collection to the given length.
///
/// If `new_len` is greater than the current length, the collection is extended
/// by cloning `value` until its length equals `new_len`.
///
/// If `new_len` is less than the current length, the collection is truncated.
pub trait Resize: Container {
    /// Resize the collection to the given length.
    ///
    /// If `new_len` is greater than the current length, the collection is extended
    /// by cloning `value` until its length equals `new_len`.
    ///
    /// If `new_len` is less than the current length, the collection is truncated.
    fn resize(&mut self, new_len: usize, value: Self::Value)
    where
        Self::Value: Clone;
}

/// Consume the collection and yield owned key-value pairs.
pub trait IntoIter<K>: Container {
    /// Iterator that consumes the collection.
    type IntoIter: Iterator<Item = (K, Self::Value)>;

    /// Consume the collection and yield owned key-value pairs.
    fn into_iter(self) -> Self::IntoIter;
}