predictable collection api (#182)

Author: stegaBOB

star_frame/src/unsize/impls/set.rs

@@ -127,7 +127,9 @@ where
         self.list.get(index)
     }
 
-    /// Adds a value to the set. Returns whether the value was already present. If the value is already present, the set is unchanged.
+    /// Adds a value to the set.
+    ///
+    /// Returns whether the value was newly inserted. If the value is already present, the set is unchanged and `false` is returned.
     ///
     /// # Examples
     ///

star_frame/src/unsize/impls/unsized_map.rs

@@ -168,7 +168,7 @@ where
         }
     }
 
-    /// Inserts or modifies an item into the map, returning true if the item already existed, and false otherwise.
+    /// Inserts or modifies an item into the map, returning true if the item was newly inserted, and false otherwise.
     #[exclusive]
     pub fn insert<I>(&mut self, key: K, value: I) -> Result<bool>
     where
@@ -179,12 +179,12 @@ where
                 // TODO: optimize this by just modifying bytes to fit and then writing to them
                 self.list().remove(existing_index)?;
                 self.list().insert_with_offset(existing_index, value, key)?;
-                Ok(true)
+                Ok(false)
             }
             Err(insertion_index) => {
                 self.list()
                     .insert_with_offset(insertion_index, value, key)?;
-                Ok(false)
+                Ok(true)
             }
         }
     }