FEAT: Make .push() use panics for errors, add .try_push()

src/lib.rs

@@ -151,8 +151,7 @@ impl<A: Array> ArrayVec<A> {
 
     /// Push `element` to the end of the vector.
     ///
-    /// Return `None` if the push succeeds, or and return `Some(` *element* `)`
+    /// ***Panics*** if the array is already full.
-    /// if the vector is full.
     ///
     /// ```
     /// use arrayvec::ArrayVec;
@@ -161,22 +160,47 @@ impl<A: Array> ArrayVec<A> {
     ///
     /// array.push(1);
     /// array.push(2);
-    /// let overflow = array.push(3);
     ///
     /// assert_eq!(&array[..], &[1, 2]);
-    /// assert_eq!(overflow, Some(3));
     /// ```
-    pub fn push(&mut self, element: A::Item) -> Option<A::Item> {
+    pub fn push(&mut self, element: A::Item) {
+        self.try_push(element).unwrap()
+    }
+
+    /// Push `element` to the end of the vector.
+    ///
+    /// Return `None` if the push succeeds, or and return `Some(` *element* `)`
+    /// if the vector is full.
+    ///
+    /// ```
+    /// use arrayvec::ArrayVec;
+    ///
+    /// let mut array = ArrayVec::<[_; 2]>::new();
+    ///
+    /// let push1 = array.try_push(1);
+    /// let push2 = array.try_push(2);
+    ///
+    /// assert!(push1.is_ok());
+    /// assert!(push2.is_ok());
+    ///
+    /// let overflow = array.try_push(3);
+    ///
+    /// assert_eq!(&array[..], &[1, 2]);
+    ///
+    /// assert!(overflow.is_err());
+    /// ```
+    pub fn try_push(&mut self, element: A::Item) -> Result<(), CapacityError<A::Item>> {
         if self.len() < A::capacity() {
             unsafe {
                 self.push_unchecked(element);
             }
-            None
+            Ok(())
         } else {
-            Some(element)
+            Err(CapacityError::new(element))
         }
     }
 
+
     /// Push `element` to the end of the vector without checking the capacity.
     ///
     /// It is up to the caller to ensure the capacity of the vector is

tests/tests.rs

@@ -31,9 +31,9 @@ fn test_u16_index() {
     const N: usize = 4096;
     let mut vec: ArrayVec<[_; N]> = ArrayVec::new();
     for _ in 0..N {
-        assert!(vec.push(1u8).is_none());
+        assert!(vec.try_push(1u8).is_ok());
     }
-    assert!(vec.push(0).is_some());
+    assert!(vec.try_push(0).is_err());
     assert_eq!(vec.len(), N);
 }
 
@@ -78,7 +78,9 @@ fn test_drop() {
         array.push(vec![Bump(flag)]);
         array.push(vec![Bump(flag), Bump(flag)]);
         array.push(vec![]);
-        array.push(vec![Bump(flag)]);
+        let push4 = array.try_push(vec![Bump(flag)]);
+        assert_eq!(flag.get(), 0);
+        drop(push4);
         assert_eq!(flag.get(), 1);
         drop(array.pop());
         assert_eq!(flag.get(), 1);
@@ -218,7 +220,7 @@ fn test_drop_panic_into_iter() {
 #[test]
 fn test_insert() {
     let mut v = ArrayVec::from([]);
-    assert_eq!(v.push(1), Some(1));
+    assert_matches!(v.try_push(1), Err(_));
     assert_matches!(v.try_insert(0, 1), Err(_));
 
     let mut v = ArrayVec::<[_; 3]>::new();