1+ //! Faster vec type.
2+
13use std:: ops:: { Deref , DerefMut } ;
24
35#[ cfg( feature = "rkyv" ) ]
46mod rkyv;
57
68use crate :: { boxed:: Box , FastAlloc } ;
79
10+ /// Faster version of [`std::vec::Vec`].
811#[ derive( Debug , Clone , PartialEq , Eq , PartialOrd , Ord , Hash ) ]
912#[ repr( transparent) ]
1013#[ cfg_attr(
@@ -14,15 +17,116 @@ use crate::{boxed::Box, FastAlloc};
1417pub struct Vec < T > ( allocator_api2:: vec:: Vec < T , FastAlloc > ) ;
1518
1619impl < T > Vec < T > {
20+ /// Constructs a new, empty `Vec<T>`.
21+ ///
22+ /// The vector will not allocate until elements are pushed onto it.
23+ ///
24+ /// # Examples
25+ ///
26+ /// ```
27+ /// # #![allow(unused_mut)]
28+ /// let mut vec: Vec<i32> = Vec::new();
29+ /// ```
30+ ///
31+ /// Note: This is slower than using [Self::new_in] with cached [FastAlloc].
1732pub fn new ( ) -> Self {
18- Default :: default ( )
33+ Self :: new_in ( Default :: default ( ) )
1934 }
2035
36+ /// Constructs a new, empty `Vec<T, A>`.
37+ ///
38+ /// The vector will not allocate until elements are pushed onto it.
39+ ///
40+ /// See [std::vec::Vec::new_in] for more information.
41+ pub fn new_in ( alloc : FastAlloc ) -> Self {
42+ Self ( allocator_api2:: vec:: Vec :: new_in ( alloc) )
43+ }
44+
45+ /// Constructs a new, empty `Vec<T>` with at least the specified capacity.
46+ ///
47+ /// The vector will be able to hold at least `capacity` elements without
48+ /// reallocating. This method is allowed to allocate for more elements than
49+ /// `capacity`. If `capacity` is 0, the vector will not allocate.
50+ ///
51+ /// It is important to note that although the returned vector has the
52+ /// minimum *capacity* specified, the vector will have a zero *length*. For
53+ /// an explanation of the difference between length and capacity, see
54+ /// *[Capacity and reallocation]*.
55+ ///
56+ /// If it is important to know the exact allocated capacity of a `Vec`,
57+ /// always use the [`capacity`] method after construction.
58+ ///
59+ /// For `Vec<T>` where `T` is a zero-sized type, there will be no allocation
60+ /// and the capacity will always be `usize::MAX`.
61+ ///
62+ /// [Capacity and reallocation]: #capacity-and-reallocation
63+ /// [`capacity`]: Vec::capacity
64+ ///
65+ /// # Panics
66+ ///
67+ /// Panics if the new capacity exceeds `isize::MAX` bytes.
68+ ///
69+ /// # Examples
70+ ///
71+ /// ```
72+ /// let mut vec = Vec::with_capacity(10);
73+ ///
74+ /// // The vector contains no items, even though it has capacity for more
75+ /// assert_eq!(vec.len(), 0);
76+ /// assert!(vec.capacity() >= 10);
77+ ///
78+ /// // These are all done without reallocating...
79+ /// for i in 0..10 {
80+ /// vec.push(i);
81+ /// }
82+ /// assert_eq!(vec.len(), 10);
83+ /// assert!(vec.capacity() >= 10);
84+ ///
85+ /// // ...but this may make the vector reallocate
86+ /// vec.push(11);
87+ /// assert_eq!(vec.len(), 11);
88+ /// assert!(vec.capacity() >= 11);
89+ ///
90+ /// // A vector of a zero-sized type will always over-allocate, since no
91+ /// // allocation is necessary
92+ /// let vec_units = Vec::<()>::with_capacity(10);
93+ /// assert_eq!(vec_units.capacity(), usize::MAX);
94+ /// ```
95+ ///
96+ /// Note: This is slower than using [Self::with_capacity_in] with cached
97+ /// [FastAlloc].
2198pub fn with_capacity ( capacity : usize ) -> Self {
22- Self ( allocator_api2:: vec:: Vec :: with_capacity_in (
23- capacity,
24- FastAlloc :: default ( ) ,
25- ) )
99+ Self :: with_capacity_in ( capacity, Default :: default ( ) )
100+ }
101+
102+ /// Constructs a new, empty `Vec<T, A>` with at least the specified capacity
103+ /// with the provided allocator.
104+ ///
105+ /// The vector will be able to hold at least `capacity` elements without
106+ /// reallocating. This method is allowed to allocate for more elements than
107+ /// `capacity`. If `capacity` is 0, the vector will not allocate.
108+ ///
109+ /// It is important to note that although the returned vector has the
110+ /// minimum *capacity* specified, the vector will have a zero *length*. For
111+ /// an explanation of the difference between length and capacity, see
112+ /// *[Capacity and reallocation]*.
113+ ///
114+ /// If it is important to know the exact allocated capacity of a `Vec`,
115+ /// always use the [`capacity`] method after construction.
116+ ///
117+ /// For `Vec<T, A>` where `T` is a zero-sized type, there will be no
118+ /// allocation and the capacity will always be `usize::MAX`.
119+ ///
120+ /// [Capacity and reallocation]: #capacity-and-reallocation
121+ /// [`capacity`]: Vec::capacity
122+ ///
123+ /// # Panics
124+ ///
125+ /// Panics if the new capacity exceeds `isize::MAX` bytes.
126+ ///
127+ /// See [std::vec::Vec::with_capacity_in] for more information.
128+ pub fn with_capacity_in ( capacity : usize , alloc : FastAlloc ) -> Self {
129+ Self ( allocator_api2:: vec:: Vec :: with_capacity_in ( capacity, alloc) )
26130 }
27131
28132 /// Converts the vector into [`Box<[T]>`][owned slice].
@@ -105,7 +209,7 @@ impl<T> Vec<T> {
105209/// * `capacity` needs to be the capacity that the pointer was allocated
106210/// with.
107211/// * The allocated size in bytes must be no larger than `isize::MAX`. See
108- /// the safety documentation of [`pointer::offset`].
212+ /// the safety documentation of [`std:: pointer::offset`].
109213///
110214/// These requirements are always upheld by any `ptr` that has been
111215/// allocated via `Vec<T>`. Other allocation sources are allowed if the
@@ -243,16 +347,3 @@ impl<T> Extend<T> for Vec<T> {
243347 self . 0 . extend ( iter)
244348 }
245349}
246-
247- impl FastAlloc {
248- pub fn vec < T > ( & self ) -> Vec < T > {
249- Vec ( allocator_api2:: vec:: Vec :: new_in ( self . clone ( ) ) )
250- }
251-
252- pub fn vec_with_capacity < T > ( & self , capacity : usize ) -> Vec < T > {
253- Vec ( allocator_api2:: vec:: Vec :: with_capacity_in (
254- capacity,
255- self . clone ( ) ,
256- ) )
257- }
258- }
0 commit comments