From 6423cba9547d9d79342aee9c1e6e4a43be67a41d Mon Sep 17 00:00:00 2001 From: Lokathor Date: Fri, 17 Jan 2020 22:47:53 -0700 Subject: [PATCH] breaking: make Array trait follow standard Rust naming --- Cargo.toml | 2 +- src/array.rs | 22 +++++++------- src/arrayvec.rs | 24 +++++++-------- src/lib.rs | 78 ++++++++++++++++++++++++------------------------- src/tinyvec.rs | 2 +- 5 files changed, 63 insertions(+), 65 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index 8ac98a4..8cd927a 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,7 +1,7 @@ [package] name = "tinyvec" description = "Just, really the littlest Vec you could need. So smol." -version = "0.2.0-alpha.0" +version = "0.3.0-alpha.0" authors = ["Lokathor "] edition = "2018" license = "Zlib" diff --git a/src/array.rs b/src/array.rs index 8976918..33268f8 100644 --- a/src/array.rs +++ b/src/array.rs @@ -1,20 +1,20 @@ /// A trait for types that can be the backing store of an /// [`ArrayVec`](ArrayVec::). /// -/// An "array", for our purposes, has the following basic properties: +/// An "array", for our purposes, has the following properties: /// * Owns some number of elements. /// * The element type can be generic, but must implement [`Default`]. -/// * The capacity is fixed based on the array type. +/// * The capacity is fixed at compile time, based on the implementing type. /// * You can get a shared or mutable slice to the elements. /// -/// You are generally note expected to need to implement this yourself. It is -/// already implemented for all the major array lengths. Additional lengths can -/// probably be added upon request. +/// You are generally **not** expected to need to implement this yourself. It is +/// already implemented for all the major array lengths (`0..=32` and the powers +/// of 2 up to 4,096). Additional lengths can easily be added upon request. /// /// ## Safety Reminder /// -/// As a reminder, this trait is 100% safe, which means that `unsafe` code -/// **must not** rely on an instance of the trait being correct to avoid UB. +/// Just a reminder: this trait is 100% safe, which means that `unsafe` code +/// **must not** rely on an instance of this trait being correct. pub trait Array { /// The type of the items in the thing. type Item: Default; @@ -26,13 +26,13 @@ pub trait Array { /// /// A correct implementation will return a slice with a length equal to the /// `CAPACITY` value. - fn slice(&self) -> &[Self::Item]; + fn as_slice(&self) -> &[Self::Item]; /// Gives a unique slice over the whole thing. /// /// A correct implementation will return a slice with a length equal to the /// `CAPACITY` value. - fn slice_mut(&mut self) -> &mut [Self::Item]; + fn as_slice_mut(&mut self) -> &mut [Self::Item]; } macro_rules! impl_array_for_len { @@ -41,11 +41,11 @@ macro_rules! impl_array_for_len { type Item = T; const CAPACITY: usize = $len; #[inline(always)] - fn slice(&self) -> &[T] { + fn as_slice(&self) -> &[T] { &*self } #[inline(always)] - fn slice_mut(&mut self) -> &mut [T] { + fn as_slice_mut(&mut self) -> &mut [T] { &mut *self } })+ diff --git a/src/arrayvec.rs b/src/arrayvec.rs index 45c312c..fdf9663 100644 --- a/src/arrayvec.rs +++ b/src/arrayvec.rs @@ -49,7 +49,7 @@ impl Deref for ArrayVec { #[inline(always)] #[must_use] fn deref(&self) -> &Self::Target { - &self.data.slice()[..self.len] + &self.data.as_slice()[..self.len] } } @@ -57,7 +57,7 @@ impl DerefMut for ArrayVec { #[inline(always)] #[must_use] fn deref_mut(&mut self) -> &mut Self::Target { - &mut self.data.slice_mut()[..self.len] + &mut self.data.as_slice_mut()[..self.len] } } @@ -95,7 +95,7 @@ impl ArrayVec { #[inline(always)] #[must_use] pub fn as_mut_ptr(&mut self) -> *mut A::Item { - self.data.slice_mut().as_mut_ptr() + self.data.as_slice_mut().as_mut_ptr() } /// Helper for getting the mut slice. @@ -113,7 +113,7 @@ impl ArrayVec { #[inline(always)] #[must_use] pub fn as_ptr(&self) -> *const A::Item { - self.data.slice().as_ptr() + self.data.as_slice().as_ptr() } /// Helper for getting the shared slice. @@ -330,7 +330,7 @@ impl ArrayVec { if self.len > 0 { self.len -= 1; let out = - replace(&mut self.data.slice_mut()[self.len], A::Item::default()); + replace(&mut self.data.as_slice_mut()[self.len], A::Item::default()); Some(out) } else { None @@ -508,7 +508,7 @@ impl ArrayVec { } let mut new = Self::default(); let moves = &mut self.as_mut_slice()[at..]; - let targets = new.data.slice_mut(); + let targets = new.data.as_slice_mut(); for (m, t) in moves.iter_mut().zip(targets) { replace(t, replace(m, A::Item::default())); } @@ -590,7 +590,7 @@ impl ArrayVec { #[inline] pub fn try_push(&mut self, val: A::Item) -> Result<(), A::Item> { if self.len < A::CAPACITY { - replace(&mut self.data.slice_mut()[self.len], val); + replace(&mut self.data.as_slice_mut()[self.len], val); self.len += 1; Ok(()) } else { @@ -682,7 +682,7 @@ impl From for ArrayVec { /// If you want to select a length, use /// [`from_array_len`](ArrayVec::from_array_len) fn from(data: A) -> Self { - Self { len: data.slice().len(), data } + Self { len: data.as_slice().len(), data } } } @@ -710,7 +710,7 @@ impl Iterator for ArrayVecIterator { fn next(&mut self) -> Option { if self.base < self.len { let out = - replace(&mut self.data.slice_mut()[self.base], A::Item::default()); + replace(&mut self.data.as_slice_mut()[self.base], A::Item::default()); self.base += 1; Some(out) } else { @@ -729,13 +729,13 @@ impl Iterator for ArrayVecIterator { } #[inline] fn last(mut self) -> Option { - Some(replace(&mut self.data.slice_mut()[self.len], A::Item::default())) + Some(replace(&mut self.data.as_slice_mut()[self.len], A::Item::default())) } #[inline] fn nth(&mut self, n: usize) -> Option { let i = self.base + (n - 1); if i < self.len { - let out = replace(&mut self.data.slice_mut()[i], A::Item::default()); + let out = replace(&mut self.data.as_slice_mut()[i], A::Item::default()); self.base = i + 1; Some(out) } else { @@ -794,7 +794,7 @@ where #[inline] #[must_use] fn eq(&self, other: &&A) -> bool { - self.deref() == other.slice() + self.deref() == other.as_slice() } } diff --git a/src/lib.rs b/src/lib.rs index 2fa19e7..032db2d 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -16,52 +16,50 @@ //! [arrayvec](https://docs.rs/arrayvec) and //! [smallvec](https://docs.rs/smallvec). //! -//! * Being 100% safe means that you have to have some sort of compromise -//! compared to the versions using `unsafe`. In this case, the compromise is -//! that the element type must implement `Default` to be usable in these vecs. -//! This makes TinyVec structures not applicable for truly arbitrary data types. -//! However, [quite a -//! few](https://doc.rust-lang.org/std/default/trait.Default.html#implementors) -//! types have a `Default` impl, including the common cases such as `u8`, `char` -//! and even `&str`. -//! * [`ArrayVec`] is an array-backed vec-like structure with a fixed capacity. -//! If you try to grow the length past the -//! array's capacity it will error or panic (depending on the method used). -//! * (Note: I am _very sorry_ that this type has the same name as the -//! `ArrayVec` type in the `arrayvec` crate. We really couldn't think of -//! another name for this sort of data structure. Please [contact -//! us](https://github.com/Lokathor/tinyvec/issues) with a better name -//! before this crate is 1.0 if you can think of one.) -//! * [`TinyVec`] is an enum that's either an "inline" `ArrayVec` or a "heap" -//! `Vec`. If it's in array mode and you try to grow the vec beyond its -//! capacity it'll quietly transition into heap mode for you and then continue -//! operation. This type is naturally behind the `alloc` feature gate. +//! Being 100% safe means that you have to have some sort of compromise compared +//! to the versions using `unsafe`. In this case, the compromise is that the +//! element type must implement `Default` to be usable in these vecs. This makes +//! TinyVec structures not applicable for truly arbitrary data types. However, +//! [quite a +//! few](https://doc.rust-lang.org/std/default/trait.Default.html#implementors) +//! types have a `Default` impl, including the common cases such as `u8`, `char` +//! and even `&str`. +//! +//! * [`ArrayVec`](ArrayVec::) is an array-backed vec-like structure with a +//! fixed capacity. If you try to grow the length past the array's capacity it +//! will error or panic (depending on the method used). +//! * [`TinyVec`](TinyVec::) is an enum that's either an "inline" `ArrayVec` +//! or a "heap" `Vec`. If it's in array mode and you try to grow the vec +//! beyond its capacity it'll quietly transition into heap mode for you and +//! then continue operation. This type is naturally behind the `alloc` feature +//! gate. //! //! ## Stability Goal //! //! The crate is still in development, but we have some very clear goals: //! -//! 1) The crate is 100% safe code. Not just a safe API - no `unsafe` internals -//! either. `#![forbid(unsafe_code)]`. +//! 1) The crate is 100% safe code. Not just a safe API, there are also no +//! `unsafe` internals. `#![forbid(unsafe_code)]`. //! 2) No required dependencies. -//! * We might provide optional dependencies for extra -//! functionality (eg: `serde` compatability), but none of them will be -//! required. -//! 3) The _intended_ API is that, as much as possible, these types are -//! essentially a "drop-in" replacement for the standard -//! [`Vec`](alloc::vec::Vec) type. -//! * For `Vec` methods that are not yet Stable, they are sometimes provided -//! via a crate feature, in which case the feature requires Nightly. -//! * If `Vec` methods that are stable but which rely on an unstable library -//! internals, that also requires a feature and a nightly compiler (sorry). -//! * Some of the methods provided are **not** part of the `Vec` API but are -//! none the less important methods to have. In this case, the method names -//! are usually fairly long and perhaps even a little silly. It is the hope -//! that this "convention" will prevent any potential name clash between -//! our vec types and the standard `Vec` type. -//! * That said, if `Vec` lands -//! some method with the same name as something we have, we'll just bite -//! the bullet and fix it with a breaking change. +//! * We might provide optional dependencies for extra functionality (eg: +//! `serde` compatability), but none of them will be required. +//! 3) The intended API is that, _as much as possible_, these types are +//! essentially a "drop-in" replacement for the standard [`Vec`](Vec::) +//! type. +//! * Stable `Vec` methods that the vecs here also have should have the exact +//! same signature. +//! * Unstable `Vec` methods are sometimes provided via a crate feature, but +//! if so they also require Nightly. +//! * Some methods are provided that _are not_ part of the `Vec` type, such +//! as additional constructor methods. In this case, the names are rather +//! long and whimsical in the hopes that they don't class with any possible +//! future methods of `Vec` +//! * If, in the future, `Vec` stabilizes a method that clashes with an +//! existing extra method here then we'll simply be forced to release a +//! 2.y.z version. Not the end of the world. +//! * Some methods of `Vec` are simply inappropriate and will not be +//! implemented here. For example, `ArrayVec` cannot possibly implement +//! [`from_raw_parts`](Vec::::from_raw_parts). use core::{ borrow::{Borrow, BorrowMut}, diff --git a/src/tinyvec.rs b/src/tinyvec.rs index 4604b8a..9fc6650 100644 --- a/src/tinyvec.rs +++ b/src/tinyvec.rs @@ -779,7 +779,7 @@ where #[inline] #[must_use] fn eq(&self, other: &&A) -> bool { - self.deref() == other.slice() + self.as_slice() == other.as_slice() } }