Add doc attributes for docs.rs build

Cargo.toml

@@ -43,6 +43,7 @@ experimental_write_impl = []
 
 [package.metadata.docs.rs]
 all-features = true
+rustdoc-args = ["--cfg","docs_rs"]
 
 [profile.test]
 opt-level = 3

README.md

@@ -7,6 +7,13 @@
 
 # tinyvec
 
-A 100% safe crate of vec-like types.
+A 100% safe crate of vec-like types. `#![forbid(unsafe_code)]`
 
-For details, please see [the docs.rs documentation](https://docs.rs/tinyvec/)
+Main types are as follows:
+* `ArrayVec` is an array-backed vec-like data structure. It panics on overflow.
+* `SliceVec` is the same deal, but using a `&mut [T]`.
+* `TinyVec` (`alloc` feature) is an enum that's either an `Inline(ArrayVec)` or a `Heap(Vec)`. If a `TinyVec` is `Inline` and would overflow it automatically transitions to `Heap` and continues whatever it was doing.
+
+To attain this "100% safe code" status there is one compromise: the element type of the vecs must implement `Default`.
+
+For more details, please see [the docs.rs documentation](https://docs.rs/tinyvec/)

src/array.rs

@@ -8,7 +8,9 @@
 ///
 /// 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.
+/// of 2 up to 4,096).
+///
+/// **Additional lengths can easily be added upon request.**
 ///
 /// ## Safety Reminder
 ///

src/lib.rs

@@ -26,36 +26,39 @@
 //! If a `TinyVec` is `Inline` and would overflow it automatically transitions
 //! itself into being `Heap` mode instead of a panic.
 //!
-//! All of this is done with no `unsafe` code within the crate. Technically
-//! the `Vec` type from the standard library uses `unsafe` internally, but *this
+//! All of this is done with no `unsafe` code within the crate. Technically the
+//! `Vec` type from the standard library uses `unsafe` internally, but *this
 //! crate* introduces no new `unsafe` code into your project.
 //!
 //! The limitation is that the element type of a vec from this crate must
 //! support the [`Default`] trait. This means that this crate isn't suitable for
 //! all situations, but a very surprising number of types do support `Default`.
 //!
+//! ## Other Features
+//! * `grab_spare_slice` lets you get access to the "inactive" portions of an
+//!   ArrayVec.
+//! * `rustc_1_40` makes the crate assume a minimum rust version of `1.40.0`,
+//!   which allows some better internal optimizations.
+//!
 //! ## API
 //! The general goal of the crate is that, as much as possible, the vecs here
 //! should be a "drop in" replacement for the standard library `Vec` type. We
 //! strive to provide all of the `Vec` methods with the same names and
-//! signatures. The "exception" is of course that the element type of each
-//! method will have a `Default` bound that's not part of the normal `Vec` type.
+//! signatures. The exception is that the element type of some methods will have
+//! a `Default` bound that's not part of the normal `Vec` type.
 //!
-//! The vecs here also have additional methods that aren't on the `Vec` type. In
-//! this case, the names tend to be fairly long so that they are unlikely to
-//! clash with any future methods added to `Vec`.
+//! The vecs here also have a few additional methods that aren't on the `Vec`
+//! type. In this case, the names tend to be fairly long so that they are
+//! unlikely to clash with any future methods added to `Vec`.
 //!
 //! ## Stability
-//! `tinyvec` is starting to get some real usage within the ecosystem! The more
-//! popular you are, the less people want you breaking anything that they're
-//! using.
-//!
-//! * With the 0.4 release we had to make a small breaking change to how the vec
-//!   creation macros work, because of an unfortunate problem with how `rustc`
-//!   was parsing things under the old syntax.
-//!
-//! If we don't have any more unexpected problems, I'd like to declare the crate
-//! to be 1.0 by the end of 2020.
+//! * The `1.0` series of the crate works with Rustc `1.34.0` or later, though
+//!   you still need to have Rustc `1.36.0` to use the `alloc` feature.
+//! * The `2.0` version of the crate is planned for some time after the
+//!   `min_const_generics` stuff becomes stable. This would greatly raise the
+//!   minimum rust version and also allow us to totally eliminate the need for
+//!   the `Array` trait. The actual usage of the crate is not expected to break
+//!   significantly in this transition.
 
 #[allow(unused_imports)]
 use core::{

src/tinyvec.rs

@@ -26,6 +26,7 @@ use alloc::vec::{self, Vec};
 /// let many_ints: TinyVec<[i32; 4]> = tiny_vec!(1, 2, 3, 4, 5, 6, 7, 8, 9, 10);
 /// ```
 #[macro_export]
+#[cfg_attr(docs_rs, doc(cfg(feature = "alloc")))]
 macro_rules! tiny_vec {
   ($array_type:ty => $($elem:expr),* $(,)?) => {
     {
@@ -82,6 +83,7 @@ pub enum TinyVecConstructor<A: Array> {
 /// let some_ints = tiny_vec!([i32; 4] => 1, 2, 3);
 /// ```
 #[derive(Clone)]
+#[cfg_attr(docs_rs, doc(cfg(feature = "alloc")))]
 pub enum TinyVec<A: Array> {
   #[allow(missing_docs)]
   Inline(ArrayVec<A>),
@@ -256,7 +258,7 @@ impl<A: Array> TinyVec<A> {
   /// ```text
   /// Note that the allocator may give the collection more space than it requests.
   /// Therefore, capacity can not be relied upon to be precisely minimal.
-  /// Prefer reserve if future insertions are expected.
+  /// Prefer `reserve` if future insertions are expected.
   /// ```
   /// ```rust
   /// use tinyvec::*;
@@ -280,6 +282,33 @@ impl<A: Array> TinyVec<A> {
     /* In this place array has enough place, so no work is needed more */
     return;
   }
+
+  /// Makes a new TinyVec with _at least_ the given capacity.
+  ///
+  /// If the requested capacity is less than or equal to the array capacity you
+  /// get an inline vec. If it's greater than you get a heap vec.
+  /// ```
+  /// # use tinyvec::*;
+  /// let t = TinyVec::<[u8; 10]>::with_capacity(5);
+  /// assert!(t.is_inline());
+  /// assert!(t.capacity() >= 5);
+  ///
+  /// let t = TinyVec::<[u8; 10]>::with_capacity(20);
+  /// assert!(t.is_heap());
+  /// assert!(t.capacity() >= 20);
+  /// ```
+  #[inline]
+  #[must_use]
+  pub fn with_capacity(cap: usize) -> Self
+  where
+    A: Default,
+  {
+    if cap <= A::CAPACITY {
+      TinyVec::Inline(ArrayVec::default())
+    } else {
+      TinyVec::Heap(Vec::with_capacity(cap))
+    }
+  }
 }
 
 impl<A: Array> TinyVec<A> {