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
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154

//! A collection of data structures that implement the [`Collection`] trait, allowing for a common
//! interface for all the data structures in this crate. This crate is intended to be a proof of
//! concept a common interface for all the data structures in Rust. Not all the data structures
//! are implemented in this crate, but the ones that are implemented are:
//!
//! - [`Queue`]: A `FIFO` data structure based on linked nodes.
//! - [`Deque`]: A `FIFO` and `LIFO` data structure based on linked nodes.
//! - [`CircularDeque`]: A `FIFO` and `LIFO` data structure based on a circular array.
//! - [`Stack`]: A `LIFO` data structure based on a linked nodes.
//! - [`ArrayStack`]: A `LIFO` data structure based on a fixed size array.
//! - [`BinaryHeap`]: A `PriorityQueue` data structure based on a binary heap.
//!
//! The crate also contains the following traits:
//!
//! - [`Collection`]: A trait that defines the common interface for all the data structures in this
//! crate.
//! - [`FixedSizeCollection`]: A trait that defines the common interface for all the data structures
//! in this crate that have a fixed size.
//! - [`Iterators`]: A trait that defines the common interface for all the iterators in this crate.
//! - [`DequeCollection`]: A trait that defines the common interface for all the data structures in
//! this crate that are both `FIFO` and `LIFO`.
//!
//! The crate also contains the following macros for easily creating data structures:
//! - [`queue!`]: A macro that creates a [`Queue`] data structure.
//! - [`deque!`]: A macro that creates a [`Deque`] data structure.
//! - [`circular_deque!`]: A macro that creates a [`CircularDeque`] data structure.
//! - [`stack!`]: A macro that creates a [`Stack`] data structure.
//! - [`array_stack!`]: A macro that creates a [`ArrayStack`] data structure.
//! - [`binary_heap!`]: A macro that creates a [`BinaryHeap`] data structure.
//!
//! The crate also contain extra modules for creating new data structures and for creating macros
//! that can be used to add functionality to the data structures in this crate. For more information
//! about these modules, see the documentation of [`macros`].
//!
//! # Example
//!
//! ```
//! use trait_based_collection::{import, Deque};
//! import!();
//!
//! # fn main() {
//! let mut deque = deque![1, 2, 3];
//!
//! for i in 4..=10 {
//!    deque.add(i);
//! }
//!
//! for i in 1..=10 {
//!    assert_eq!(deque.remove(), Some(i));
//! }
//! # }
//! ```
#![warn(missing_docs)]
#![allow(clippy::module_name_repetitions)]
extern crate trait_based_collection_macros;

pub mod collection;
pub mod priority_queue;
pub mod queue;
pub mod stack;

pub use self::collection::{Collection, ExpansionMode, FixedSizeCollection, Iterators};
pub use self::priority_queue::BinaryHeap;
pub use self::queue::{CircularDeque, Deque, DequeCollection, Queue};
pub use self::stack::{ArrayStack, Stack};

/// A collection of all the procedural macros used in this crate. This macros can be divided into
/// two categories:
///
/// - **Derive macros**: These macros are used to derive traits for the data structures in this
/// crate. These macros are:
///    - [`Default`]: Default implementation for creating a new instance of the data structure. This
/// macro is used to implement the [`Default`](std::default::Default) trait.
///    - [`Display`]: Allows the data structure to be printed using the
/// [`Display`](std::fmt::Display) trait.
///    - [`Drop`]: Allows the data structure to be safely dropped using the [`Drop`](std::ops::Drop)
/// trait.
///    - [`Extend`]: Allows the data structure to be extended using the
/// [`Extend`](std::iter::Extend) trait.
///    - [`FromIterator`]: Allows the data structure to be created from an iterator using the
/// [`FromIterator`](std::iter::FromIterator) trait.
///    - [`Index`]: Allows the data structure to be indexed using the [`Index`](std::ops::Index)
/// trait.
///   - [`IntoIterator`]: Allows the data structure to be iterated using the
/// [`IntoIterator`](std::iter::IntoIterator) trait.
///   - [`NewMacro`]: Allows the data structure to be created a macro with the same features as the
/// [`vec!`](std::vec!) macro.
///   - [`All`]: Allows the data structure to derive all the above traits.
///
/// - **Attribute macros**: These macros are used to add functionality to the data structures in
/// this crate. These macros are:
///   - [`check_expansion_add`]: This macro is used to add the [`check_expansion`] method to the
/// the beginning of the [`add`] method. This macro can be used for any data structure that
/// implements the [`FixedSizeCollection`] trait.
///
/// [`Default`]: trait_based_collection_macros::Default
/// [`Display`]: trait_based_collection_macros::Display
/// [`Drop`]: trait_based_collection_macros::Drop
/// [`Extend`]: trait_based_collection_macros::Extend
/// [`FromIterator`]: trait_based_collection_macros::FromIterator
/// [`Index`]: trait_based_collection_macros::Index
/// [`IntoIterator`]: trait_based_collection_macros::IntoIterator
/// [`NewMacro`]: trait_based_collection_macros::NewMacro
/// [`All`]: trait_based_collection_macros::All
/// [`check_expansion_add`]: trait_based_collection_macros::check_expansion_add
/// [`check_expansion`]: crate::collection::check_expansion
/// [`add`]: Collection::add
/// [`FixedSizeCollection`]: FixedSizeCollection
pub mod macros {
    pub use trait_based_collection_macros::{
        check_expansion_add, All, Default, Display, Drop, Extend, FromIterator, Index,
        IntoIterator, NewMacro,
    };
}

/// A module that contains all the traits that are used in this crate. This module is meant to be
/// used as a total import using the `prelude::*` syntax. The module also contains a macro that
/// creates the prelude for this crate allowing to also import the macros in this crate.
///
/// This macro avoids the need to write the following code:
/// ```
/// use trait_based_collection::prelude::*;
/// #[macro_use]
/// use trait_based_collection;
/// ```
/// Instead, the following code can be used:
/// ```
/// use trait_based_collection::import;
/// import!();
/// # fn main() {}
/// ```
pub mod prelude {
    pub use super::collection::{Collection, ExpansionMode, FixedSizeCollection, Iterators};
    pub use super::queue::DequeCollection;

    /// Creates the prelude for this crate. This macro is meant to a substitute for the
    /// `use trait_based_collection::prelude::*` statement if the macros in this crate are also needed.
    ///
    /// # Example
    /// ```
    /// use trait_based_collection::import;
    /// import!();
    /// # fn main() {}
    /// ```
    #[macro_export]
    macro_rules! import {
        () => {
            use trait_based_collection::prelude::*;
            // We only need the macros from this crate so we can use a dummy name.
            #[macro_use]
            extern crate trait_based_collection as _;
        };
    }
}