Crate former_types

Expand description

§Former Types - Core Trait Definitions and Type System Integration

This crate provides the foundational trait definitions and type system integration for the Former builder pattern ecosystem. It defines the core abstractions that enable flexible and extensible builder pattern implementations.

§Core Abstractions

§Formation Process Management

The crate defines several key traits that manage the formation process:

FormerDefinition: Links entities to their formation definitions
FormerDefinitionTypes: Specifies storage, formed, and context types
FormingEnd: Handles completion of the formation process
FormerMutator: Enables pre-formation data validation and manipulation
FormerBegin: Initiates subform creation with proper context

§Storage Management

Storage: Defines the interface for temporary state during formation
StoragePreform: Handles transition from storage to final formed state

§Collection Integration

Specialized support for collection types when the types_former feature is enabled:

Automatic trait implementations for standard collections
Custom collection support through extensible trait system
Type-safe collection builders with proper generic handling

§Architecture Design

§Type Safety and Generics

The trait system is designed to handle complex generic scenarios:

Lifetime Parameters: Full support for complex lifetime relationships
Generic Constraints: Proper constraint propagation through the type system
Associated Types: Clean separation of concerns through associated types

§Builder Pattern Integration

The traits work together to enable:

Fluent Interfaces: Method chaining with compile-time validation
Subform Support: Nested builders with proper context preservation
Custom Validation: Pre-formation validation and transformation
Flexible End Conditions: Customizable formation completion logic

§Feature Gates

types_former: Enables core Former trait definitions
use_alloc: Enables allocation-dependent features in no-std environments
no_std: Full no-std compatibility when used without std-dependent features

§Integration with Former Ecosystem

This crate serves as the foundation for:

[former]: Main user-facing crate with derive macro
[former_meta]: Procedural macro implementation
Collection Tools: Integration with external collection libraries

§Usage Patterns

Most users will not interact with this crate directly, but will instead use the higher-level [former] crate. However, this crate is essential for:

Custom Former implementations
Integration with external libraries
Advanced builder pattern scenarios

§Module :: `former_types`

A flexible implementation of the Builder pattern supporting nested builders and collection-specific subformers. Its compile-time structures and traits that are not generated but reused.

§Example: Using Trait Assign

Demonstrates setting various components (fields) of a struct.

The former_types crate provides a generic interface for setting components on an object. This example defines a Person struct and implements the Assign trait for its fields. It shows how to use these implementations to set the fields of a Person instance using different types that can be converted into the required types.

#[ cfg( any( not( feature = "types_former" ), not( feature = "enabled" ) ) ) ]
fn main() {}

#[ cfg( all( feature = "types_former", feature = "enabled" ) ) ]
fn main()
{
  use component_model_types::Assign;

  #[ derive( Default, PartialEq, Debug ) ]
  struct Person
  {
    age : i32,
    name : String,
  }

  impl< IntoT > Assign< i32, IntoT > for Person
  where
    IntoT : Into< i32 >,
  {
    fn assign( &mut self, component : IntoT )
    {
      self.age = component.into();
    }
  }

  impl< IntoT > Assign< String, IntoT > for Person
  where
    IntoT : Into< String >,
  {
    fn assign( &mut self, component : IntoT )
    {
      self.name = component.into();
    }
  }

  let mut got : Person = Default::default();
  got.assign( 13 );
  got.assign( "John" );
  assert_eq!( got, Person { age : 13, name : "John".to_string() } );
  dbg!( got );
  // > Person {
  // >   age: 13,
  // >   name: "John",
  // > }

}

Try out cargo run --example former_types_trivial.
See code.

Modules§

definition: Formation Definition System
dependency: Namespace with dependencies
exposed: Exposed namespace of the module.
forming: Formation Process Management
orphan: Parented namespace of the module.
own: Own namespace of the module.
prelude: Prelude to use essentials: use my_module::prelude::*.
storage: Storage Interface System

Structs§

BTreeMapDefinition: Represents the formation definition for a hash map-like collection within the former framework.
BTreeMapDefinitionTypes: Holds the generic parameters for the BTreeMapDefinition.
BTreeSetDefinition: Represents the formation definition for a binary tree set-like collection within the former framework.
BTreeSetDefinitionTypes: Holds the generic parameters for the BTreeSetDefinition.
BinaryHeapDefinition: Represents the formation definition for a binary heap-like collection within the former framework.
BinaryHeapDefinitionTypes: Holds the generic parameters for the BinaryHeapDefinition.
CollectionFormer: A builder structure for constructing collections with a fluent and flexible interface.
FormingEndClosure: A wrapper around a closure to be used as a FormingEnd.
HashMapDefinition: Represents the formation definition for a hash map-like collection within the former framework.
HashMapDefinitionTypes: Holds the generic parameters for the HashMapDefinition.
HashSetDefinition: Represents the formation definition for a hash set-like collection within the former framework.
HashSetDefinitionTypes: Holds the generic parameters for the HashSetDefinition.
LinkedListDefinition: Represents the formation definition for a list-like collection within the former framework.
LinkedListDefinitionTypes: Holds the generic parameters for the LinkedListDefinition.
NoEnd: A placeholder FormingEnd used when no end operation is required or applicable.
ReturnPreformed: A FormingEnd implementation that directly returns the formed collection as the final product of the forming process.
ReturnStorage: A FormingEnd implementation that returns the storage itself as the formed entity, disregarding any contextual data.
VecDequeDefinition: Represents the formation definition for a vector deque-like collection within the former framework.
VecDequeDefinitionTypes: Holds the generic parameters for the VecDequeDefinition.
VectorDefinition: Represents the formation definition for a vector-like collection within the former framework.
VectorDefinitionTypes: Holds the generic parameters for the VectorDefinition.

Traits§

BTreeMapExt: Provides an extension method for hash maps to facilitate the use of the builder pattern.
BTreeSetExt: Provides an extension method for binary tree sets to facilitate the use of the builder pattern.
BinaryHeapExt: Provides an extension method for binary heaps to facilitate the use of the builder pattern.
Collection: Represents a collection by defining the types of entries and values it handles.
CollectionAdd: Provides functionality to add individual entries to a collection.
CollectionAssign: Defines the capability to replace all entries in a collection with a new set of entries.
CollectionValToEntry: Provides a mechanism for transforming a value back into a collection-specific entry format.
EntityToDefinition: Maps a type of entity to its corresponding former definition.
EntityToDefinitionTypes: Provides a mapping between a type of entity and its associated formation type definitions.
EntityToFormer: Maps a type of entity to its corresponding former (builder) implementation.
EntityToStorage: Maps a type of entity to its storage type. This trait defines what storage structure is used to hold the interim state of an entity during its formation.
EntryToVal: Facilitates the conversion of collection entries to their corresponding value representations.
FormerBegin: A trait for initiating a structured subforming process with contextual and intermediary storage linkage.
FormerDefinition: Expands on FormerDefinitionTypes by incorporating an ending mechanism for the formation process. This trait connects the formation types with a specific endpoint, defining how the formation process concludes, including any necessary transformations or validations.
FormerDefinitionTypes: Defines the fundamental components involved in the formation of an entity. This trait specifies the types of storage, the formed entity, and the context used during the formation process.
FormerMutator: Provides a mechanism for mutating the context and storage just before the forming process is completed.
FormingEnd: Defines a handler for the end of a subforming process, enabling the return of the original context.
HashMapExt: Provides an extension method for hash maps to facilitate the use of the builder pattern.
HashSetExt: Provides an extension method for HashSet to facilitate the use of the builder pattern.
LinkedListExt: Provides an extension method for lists to facilitate the use of the builder pattern.
Storage: Defines the storage interface for entities being constructed using a forming pattern.
StoragePreform: Provides a mechanism to finalize the forming process by converting storage into its final formed state.
ValToEntry: Facilitates the conversion of values back into entries for specific collection types.
VecDequeExt: Provides an extension method for vector deques to facilitate the use of the builder pattern.
VecExt: Provides an extension method for vectors to facilitate the use of the builder pattern.

Type Aliases§

BTreeMapFormer: Provides a streamlined builder interface for constructing hash map-like collections.
BTreeSetFormer: Provides a streamlined builder interface for constructing binary tree set-like collections.
BinaryHeapFormer: Provides a streamlined builder interface for constructing binary heap-like collections.
HashMapFormer: Provides a streamlined builder interface for constructing hash map-like collections.
HashSetFormer: Provides a concise alias for CollectionFormer configured specifically for HashSet-like collections.
LinkedListFormer: Provides a streamlined builder interface for constructing list-like collections.
VecDequeFormer: Provides a streamlined builder interface for constructing vector deque-like collections.
VectorFormer: Provides a streamlined builder interface for constructing vector-like collections.