From b2c3141a6a5406ec1b0e5521e68203a1b59766fb Mon Sep 17 00:00:00 2001 From: Lokathor Date: Mon, 13 Jan 2020 21:34:22 -0700 Subject: [PATCH] more docs, more renames, closer to being good. --- src/arrayvec.rs | 26 +++++++++++++------------- src/lib.rs | 4 ++-- src/{tiny_vec.rs => tinyvec.rs} | 31 ++++++++++++++++++++++++++++++- tests/arrayvec.rs | 10 +++++----- 4 files changed, 50 insertions(+), 21 deletions(-) rename src/{tiny_vec.rs => tinyvec.rs} (95%) diff --git a/src/arrayvec.rs b/src/arrayvec.rs index e8bb2a1..9b39cb3 100644 --- a/src/arrayvec.rs +++ b/src/arrayvec.rs @@ -11,12 +11,12 @@ use super::*; /// ```rust /// use tinyvec::*; /// -/// let empty_av = arr_vec!([u8; 16]); +/// let empty_av = array_vec!([u8; 16]); /// -/// let some_ints = arr_vec!([i32; 4], 1, 2, 3); +/// let some_ints = array_vec!([i32; 4], 1, 2, 3); /// ``` #[macro_export] -macro_rules! arr_vec { +macro_rules! array_vec { ($array_type:ty) => { { let mut av: ArrayVec<$array_type> = Default::default(); @@ -180,7 +180,7 @@ impl ArrayVec { /// ## Example /// ```rust /// use tinyvec::*; - /// let mut av = arr_vec!([i32; 4], 1, 2, 3); + /// let mut av = array_vec!([i32; 4], 1, 2, 3); /// let av2: ArrayVec<[i32; 4]> = av.drain(1..).collect(); /// assert_eq!(av.as_slice(), &[1][..]); /// assert_eq!(av2.as_slice(), &[2, 3][..]); @@ -264,7 +264,7 @@ impl ArrayVec { /// ## Example /// ```rust /// use tinyvec::*; - /// let mut av = arr_vec!([i32; 10], 1, 2, 3); + /// let mut av = array_vec!([i32; 10], 1, 2, 3); /// av.insert(1, 4); /// assert_eq!(av.as_slice(), &[1, 4, 2, 3]); /// av.insert(4, 5); @@ -358,7 +358,7 @@ impl ArrayVec { /// /// ```rust /// use tinyvec::*; - /// let mut av = arr_vec!([i32; 4], 1, 2, 3); + /// let mut av = array_vec!([i32; 4], 1, 2, 3); /// assert_eq!(av.remove(1), 2); /// assert_eq!(av.as_slice(), &[1, 3][..]); /// ``` @@ -385,11 +385,11 @@ impl ArrayVec { /// ```rust /// use tinyvec::*; /// - /// let mut av = arr_vec!([&str; 10], "hello"); + /// let mut av = array_vec!([&str; 10], "hello"); /// av.resize(3, "world"); /// assert_eq!(av.as_slice(), &["hello", "world", "world"][..]); /// - /// let mut av = arr_vec!([i32; 10], 1, 2, 3, 4); + /// let mut av = array_vec!([i32; 10], 1, 2, 3, 4); /// av.resize(2, 0); /// assert_eq!(av.as_slice(), &[1, 2][..]); /// ``` @@ -420,11 +420,11 @@ impl ArrayVec { /// ```rust /// use tinyvec::*; /// - /// let mut av = arr_vec!([i32; 10], 1, 2, 3); + /// let mut av = array_vec!([i32; 10], 1, 2, 3); /// av.resize_with(5, Default::default); /// assert_eq!(av.as_slice(), &[1, 2, 3, 0, 0][..]); /// - /// let mut av = arr_vec!([i32; 10]); + /// let mut av = array_vec!([i32; 10]); /// let mut p = 1; /// av.resize_with(4, || { /// p *= 2; @@ -457,7 +457,7 @@ impl ArrayVec { /// ```rust /// use tinyvec::*; /// - /// let mut av = arr_vec!([i32; 10], 1, 2, 3, 4); + /// let mut av = array_vec!([i32; 10], 1, 2, 3, 4); /// av.retain(|&x| x % 2 == 0); /// assert_eq!(av.as_slice(), &[2, 4][..]); /// ``` @@ -486,7 +486,7 @@ impl ArrayVec { /// /// ```rust /// use tinyvec::*; - /// let mut av = arr_vec!([i32; 4], 1, 2, 3); + /// let mut av = array_vec!([i32; 4], 1, 2, 3); /// let av2 = av.split_off(1); /// assert_eq!(av.as_slice(), &[1][..]); /// assert_eq!(av2.as_slice(), &[2, 3][..]); @@ -522,7 +522,7 @@ impl ArrayVec { /// ## Example /// ```rust /// use tinyvec::*; - /// let mut av = arr_vec!([&str; 4], "foo", "bar", "quack", "zap"); + /// let mut av = array_vec!([&str; 4], "foo", "bar", "quack", "zap"); /// /// assert_eq!(av.swap_remove(1), "bar"); /// assert_eq!(av.as_slice(), &["foo", "zap", "quack"][..]); diff --git a/src/lib.rs b/src/lib.rs index 8a17c35..9d32356 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -93,6 +93,6 @@ mod arrayvec; pub use arrayvec::*; #[cfg(feature = "alloc")] -mod tiny_vec; +mod tinyvec; #[cfg(feature = "alloc")] -pub use tiny_vec::*; +pub use tinyvec::*; diff --git a/src/tiny_vec.rs b/src/tinyvec.rs similarity index 95% rename from src/tiny_vec.rs rename to src/tinyvec.rs index 025bd01..27ed2cf 100644 --- a/src/tiny_vec.rs +++ b/src/tinyvec.rs @@ -4,6 +4,21 @@ use super::*; use alloc::vec::Vec; +/// Helper to make a `TinyVec`. +/// +/// You specify the backing array type, and optionally give all the elements you +/// want to initially place into the array. +/// +/// As an unfortunate restriction, the backing array type must support `Default` +/// for it to work with this macro. +/// +/// ```rust +/// use tinyvec::*; +/// +/// let empty_av = tiny_vec!([u8; 16]); +/// +/// let some_ints = tiny_vec!([i32; 4], 1, 2, 3); +/// ``` #[macro_export] macro_rules! tiny_vec { ($array_type:ty) => { @@ -22,20 +37,32 @@ macro_rules! tiny_vec { } /// A vector that starts inline, but can automatically move to the heap. -/// +/// /// * Requires the `alloc` feature +/// +/// Note: This is currently an enum but you can mostly ignore that detail if you +/// like. In future versions this **may** become an opaque struct, but for now +/// we're being a little more liberal about allowing you to "access the +/// internals" since no safety invariants are on the line. It's kinda wild how +/// much you can just let people poke at stuff without worry when it's 100% safe +/// code. #[derive(Clone)] pub enum TinyVec { + #[allow(missing_docs)] Inline(ArrayVec), + #[allow(missing_docs)] Heap(Vec) } impl Default for TinyVec { + #[inline] + #[must_use] fn default() -> Self { TinyVec::Inline(ArrayVec::default()) } } impl TinyVec { /// Moves the content of the TinyVec to the heap, if it's inline. + #[allow(clippy::missing_inline_in_public_items)] pub fn move_to_the_heap(&mut self) { match self { TinyVec::Inline(ref mut arr) => { @@ -651,7 +678,9 @@ impl FromIterator for TinyVec { /// Iterator for consuming an `TinyVec` and returning owned elements. pub enum TinyVecIterator { + #[allow(missing_docs)] Inline(ArrayVecIterator), + #[allow(missing_docs)] Heap(alloc::vec::IntoIter) } impl Iterator for TinyVecIterator { diff --git a/tests/arrayvec.rs b/tests/arrayvec.rs index 252e48f..09a9613 100644 --- a/tests/arrayvec.rs +++ b/tests/arrayvec.rs @@ -10,7 +10,7 @@ fn test_a_vec() { expected.push(2); expected.push(3); - let actual = arr_vec!([i32; 4], 1, 2, 3); + let actual = array_vec!([i32; 4], 1, 2, 3); assert_eq!(expected, actual); } @@ -88,7 +88,7 @@ fn ArrayVec_formatting() { #[test] fn ArrayVec_iteration() { - let av = arr_vec!([i32; 4], 10, 11, 12, 13); + let av = array_vec!([i32; 4], 10, 11, 12, 13); let mut i = av.into_iter(); assert_eq!(i.next(), Some(10)); @@ -97,7 +97,7 @@ fn ArrayVec_iteration() { assert_eq!(i.next(), Some(13)); assert_eq!(i.next(), None); - let av = arr_vec!([i32; 4], 10, 11, 12, 13); + let av = array_vec!([i32; 4], 10, 11, 12, 13); let av2: ArrayVec<[i32; 4]> = av.clone().into_iter().collect(); assert_eq!(av, av2); @@ -105,8 +105,8 @@ fn ArrayVec_iteration() { #[test] fn ArrayVec_append() { - let mut av = arr_vec!([i32; 8], 1, 2, 3); - let mut av2 = arr_vec!([i32; 8], 4, 5, 6); + let mut av = array_vec!([i32; 8], 1, 2, 3); + let mut av2 = array_vec!([i32; 8], 4, 5, 6); // av.append(&mut av2); assert_eq!(av.as_slice(), &[1_i32, 2, 3, 4, 5, 6]);