former_types/collection/

binary_heap.rs

//! This module provides a comprehensive approach to applying the builder pattern to `BinaryHeap` collections.
//!
//! By leveraging traits such as `Collection`, `CollectionAdd`, `CollectionAssign`, and `CollectionValToEntry`,
//! this module abstracts the operations on binary heap-like data structures, making them more flexible and easier to integrate as
//! as subformer, enabling fluid and intuitive manipulation of binary heaps via builder patterns.
//!


use crate :: *;
#[ allow( unused ) ]
use collection_tools ::BinaryHeap;

impl< E > Collection for BinaryHeap< E > 
{
  type Entry = E;
  type Val = E;

  #[ inline( always ) ]
  fn entry_to_val(e: Self ::Entry) -> Self ::Val 
  {
  e
 }
}

impl< E > CollectionAdd for BinaryHeap< E >
where
  E: Ord,
{
  #[ inline( always ) ]
  fn add(&mut self, e: Self ::Entry) -> bool 
  {
  self.push(e);
  true
 }
}

impl< E > CollectionAssign for BinaryHeap< E >
where
  E: Ord,
{
  #[ inline( always ) ]
  fn assign< Elements >(&mut self, elements: Elements) -> usize
  where
  Elements: IntoIterator< Item = Self ::Entry >,
  {
  let initial_len = self.len();
  self.extend(elements);
  self.len() - initial_len
 }
}

impl< E > CollectionValToEntry< E > for BinaryHeap< E > 
{
  type Entry = E;
  #[ inline( always ) ]
  fn val_to_entry(val: E) -> Self ::Entry 
  {
  val
 }
}

// = storage

impl< E > Storage for BinaryHeap< E >
where
  E: Ord,
{
  type Preformed = BinaryHeap< E >;
}

impl< E > StoragePreform for BinaryHeap< E >
where
  E: Ord,
{
  fn preform(self) -> Self ::Preformed 
  {
  self
 }
}

// = definition

/// Represents the formation definition for a binary heap-like collection within the former framework.
///
/// This structure defines the necessary parameters and relationships needed to form a binary heap-like collection,
/// including its storage, context, the result of the formation process, and the behavior at the end of the formation.
///
/// # Type Parameters
/// - `E` : The element type of the binary heap.
/// - `Context` : The context needed for the formation, can be provided externally.
/// - `Formed` : The type formed at the end of the formation process, typically a `BinaryHeap< E >`.
/// - `End` : A trait determining the behavior at the end of the formation process.
///
#[ derive( Debug, Default ) ]
pub struct BinaryHeapDefinition< E, Context, Formed, End >
where
  E: Ord,
  End: FormingEnd< BinaryHeapDefinitionTypes<E, Context, Formed >>,
{
  _phantom: core ::marker ::PhantomData< (E, Context, Formed, End) >,
}

impl< E, Context, Formed, End > FormerDefinition for BinaryHeapDefinition< E, Context, Formed, End >
where
  E: Ord,
  End: FormingEnd< BinaryHeapDefinitionTypes<E, Context, Formed >>,
{
  type Storage = BinaryHeap< E >;
  type Context = Context;
  type Formed = Formed;

  type Types = BinaryHeapDefinitionTypes< E, Context, Formed >;
  type End = End;
}

// = definition type

/// Holds the generic parameters for the `BinaryHeapDefinition`.
///
/// This struct acts as a companion to `BinaryHeapDefinition`, providing a concrete definition of types used
/// in the formation process.
///
/// # Type Parameters
///
/// - `E` : The element type of the binary heap.
/// - `Context` : The context in which the binary heap is formed.
/// - `Formed` : The type produced as a result of the formation process.
#[ derive( Debug, Default ) ]
pub struct BinaryHeapDefinitionTypes< E, Context = (), Formed = BinaryHeap<E >> 
{
  _phantom: core ::marker ::PhantomData< (E, Context, Formed) >,
}

impl< E, Context, Formed > FormerDefinitionTypes for BinaryHeapDefinitionTypes< E, Context, Formed >
where
  E: Ord,
{
  type Storage = BinaryHeap< E >;
  type Context = Context;
  type Formed = Formed;
}

// = mutator

impl< E, Context, Formed > FormerMutator for BinaryHeapDefinitionTypes< E, Context, Formed > where E: Ord {}

// = Entity To

impl< E, Definition > EntityToFormer< Definition > for BinaryHeap< E >
where
  E: Ord,
  Definition: FormerDefinition<
  Storage = BinaryHeap< E >,
  Types = BinaryHeapDefinitionTypes<
   E,
   < Definition as definition ::FormerDefinition > ::Context,
   < Definition as definition ::FormerDefinition > ::Formed,
 >,
 >,
  Definition ::End: forming ::FormingEnd< Definition ::Types >,
{
  type Former = BinaryHeapFormer< E, Definition ::Context, Definition ::Formed, Definition ::End >;
}

impl< E > crate ::EntityToStorage for BinaryHeap< E > 
{
  type Storage = BinaryHeap< E >;
}

impl< E, Context, Formed, End > crate ::EntityToDefinition< Context, Formed, End > for BinaryHeap< E >
where
  E: Ord,
  End: crate ::FormingEnd< BinaryHeapDefinitionTypes<E, Context, Formed >>,
{
  type Definition = BinaryHeapDefinition< E, Context, Formed, End >;
  type Types = BinaryHeapDefinitionTypes< E, Context, Formed >;
}

impl< E, Context, Formed > crate ::EntityToDefinitionTypes< Context, Formed > for BinaryHeap< E >
where
  E: Ord,
{
  type Types = BinaryHeapDefinitionTypes< E, Context, Formed >;
}

// = subformer

/// Provides a streamlined builder interface for constructing binary heap-like collections.
///
/// `BinaryHeapFormer` is a type alias that configures the `CollectionFormer` for use specifically with binary heaps.
/// It integrates the `BinaryHeapDefinition` to facilitate the fluent and dynamic construction of binary heaps, leveraging
/// predefined settings to reduce boilerplate code. This approach enhances readability and simplifies the use of
/// binary heaps in custom data structures where builder patterns are desired.
///
/// The alias encapsulates complex generic parameters, making the construction process more accessible and maintainable.
/// It is particularly useful in scenarios where binary heaps are repeatedly used or configured in similar ways across different
/// parts of an application.
///
pub type BinaryHeapFormer< E, Context, Formed, End > = CollectionFormer< E, BinaryHeapDefinition<E, Context, Formed, End >>;

// = extension

/// Provides an extension method for binary heaps to facilitate the use of the builder pattern.
///
/// This trait extends the `BinaryHeap` type, enabling it to use the `BinaryHeapFormer` interface directly.
/// This allows for fluent, expressive construction and manipulation of binary heaps, integrating seamlessly
/// with the builder pattern provided by the `former` framework. It's a convenience trait that simplifies
/// creating configured binary heap builders with default settings.
///
pub trait BinaryHeapExt< E > : sealed ::Sealed
where
  E: Ord,
{
  /// Initializes a builder pattern for `BinaryHeap` using a default `BinaryHeapFormer`.
  fn former() -> BinaryHeapFormer< E, (), BinaryHeap<E >, ReturnStorage>;
}

impl< E > BinaryHeapExt< E > for BinaryHeap< E >
where
  E: Ord,
{
  #[ allow( clippy ::default_constructed_unit_structs ) ]
  fn former() -> BinaryHeapFormer< E, (), BinaryHeap<E >, ReturnStorage> 
  {
  BinaryHeapFormer :: < E, (), BinaryHeap<E >, ReturnStorage> ::new(ReturnStorage ::default())
 }
}

mod sealed 
{
  pub trait Sealed {}
  impl< E > Sealed for super ::BinaryHeap< E > {}
}