More must_use

Adding must_use is technically a breaking change, would like to get this in now
RoaringBitmap · Jul 3, 2024 · 78c9838 · 78c9838
1 parent 6bf6d81
commit 78c9838
Show file tree

Hide file tree

Showing 4 changed files with 37 additions and 6 deletions.
diff --git a/croaring/src/bitmap/imp.rs b/croaring/src/bitmap/imp.rs
@@ -14,6 +14,7 @@ use core::prelude::v1::*;
 impl Bitmap {
     #[inline]
     #[allow(clippy::assertions_on_constants)]
+    #[must_use]
     pub(crate) unsafe fn take_heap(p: *mut roaring_bitmap_t) -> Self {
         // Based heavily on the `roaring.hh` cpp header from croaring
 
@@ -219,6 +220,7 @@ impl Bitmap {
     /// ```
     #[inline]
     #[doc(alias = "roaring_bitmap_contains_range")]
+    #[must_use]
     pub fn contains_range<R: RangeBounds<u32>>(&self, range: R) -> bool {
         let (start, end) = range_to_exclusive(range);
         unsafe { ffi::roaring_bitmap_contains_range(&self.bitmap, start, end) }
@@ -364,6 +366,7 @@ impl Bitmap {
     /// ```
     #[inline]
     #[doc(alias = "roaring_bitmap_range_cardinality")]
+    #[must_use]
     pub fn range_cardinality<R: RangeBounds<u32>>(&self, range: R) -> u64 {
         let (start, end) = range_to_exclusive(range);
         unsafe { ffi::roaring_bitmap_range_cardinality(&self.bitmap, start, end) }
@@ -873,7 +876,8 @@ impl Bitmap {
     /// Serializes a bitmap to a slice of bytes in format `S`, re-using existing capacity
     ///
     /// `dst` is not cleared, data is added after any existing data. Returns the added slice of `dst`.
-    /// If `dst` is empty, it is guaranteed to hold only the serialized data after this call
+    /// Because of alignment requirements, the serialized data may not start at the beginning of
+    /// `dst`: the returned slice may not start at `dst.as_ptr()`.
     ///
     /// # Examples
     ///
@@ -886,12 +890,14 @@ impl Bitmap {
     /// let mut data = Vec::new();
     /// for bitmap in [original_bitmap_1, original_bitmap_2] {
     ///     data.clear();
-    ///     bitmap.try_serialize_into::<Portable>(&mut data);
-    ///     // do something with data
+    ///     let serialized: &[u8] = bitmap.serialize_into_vec::<Portable>(&mut data);
+    ///     // do something with serialized data
+    ///     # let _ = serialized;
     /// }
     /// ```
     #[inline]
     #[cfg(feature = "alloc")]
+    #[must_use]
     pub fn serialize_into_vec<'a, S: Serializer>(&self, dst: &'a mut Vec<u8>) -> &'a mut [u8] {
         S::serialize_into_vec(self, dst)
     }
@@ -907,6 +913,7 @@ impl Bitmap {
     /// See also [`Self::serialize_into_vec`] for a version that uses a Vec instead, or, for
     /// advanced use-cases, see [`Serializer::try_serialize_into`].
     #[inline]
+    #[must_use]
     pub fn try_serialize_into<'a, S: Serializer>(&self, dst: &'a mut [u8]) -> Option<&'a mut [u8]> {
         S::try_serialize_into_aligned(self, dst)
     }
@@ -945,6 +952,7 @@ impl Bitmap {
     ///
     /// On invalid input returns empty bitmap.
     #[inline]
+    #[must_use]
     pub fn deserialize<D: Deserializer>(buffer: &[u8]) -> Self {
         Self::try_deserialize::<D>(buffer).unwrap_or_else(Bitmap::new)
     }
@@ -999,6 +1007,7 @@ impl Bitmap {
     /// assert_eq!(bitmap3.iter().collect::<Vec<_>>(), [3, 4, 5]);
     #[inline]
     #[doc(alias = "roaring_bitmap_from_range")]
+    #[must_use]
     pub fn from_range<R: RangeBounds<u32>>(range: R) -> Self {
         let mut result = Self::new();
         result.add_range(range);
@@ -1045,6 +1054,7 @@ impl Bitmap {
     /// ```
     #[inline]
     #[doc(alias = "roaring_bitmap_from_range")]
+    #[must_use]
     pub fn from_range_with_step<R: RangeBounds<u32>>(range: R, step: u32) -> Self {
         // This can't use `range_to_exclusive` because when the start is excluded, we want
         // to start at the next step, not one more
@@ -1243,6 +1253,7 @@ impl Bitmap {
     /// ```
     #[inline]
     #[doc(alias = "roaring_bitmap_intersect_with_range")]
+    #[must_use]
     pub fn intersect_with_range<R: RangeBounds<u32>>(&self, range: R) -> bool {
         let (start, end) = range_to_exclusive(range);
         unsafe { ffi::roaring_bitmap_intersect_with_range(&self.bitmap, start, end) }

diff --git a/croaring/src/bitmap/iter.rs b/croaring/src/bitmap/iter.rs
@@ -59,6 +59,7 @@ impl<'a> BitmapCursor<'a> {
     /// assert!(!cursor.has_value());
     /// ```
     #[inline]
+    #[must_use]
     pub fn has_value(&self) -> bool {
         self.raw.has_value
     }
@@ -79,6 +80,7 @@ impl<'a> BitmapCursor<'a> {
     /// assert_eq!(cursor.current(), None);
     /// ```
     #[inline]
+    #[must_use]
     pub fn current(&self) -> Option<u32> {
         if self.has_value() {
             Some(self.raw.current_value)
@@ -291,6 +293,7 @@ impl<'a> BitmapCursor<'a> {
     /// ```
     #[inline]
     #[doc(alias = "roaring_uint32_iterator_read")]
+    #[must_use]
     pub fn read_many(&mut self, dst: &mut [u32]) -> usize {
         let count = u32::try_from(dst.len()).unwrap_or(u32::MAX);
         let result =
@@ -404,6 +407,7 @@ impl<'a> BitmapIterator<'a> {
     /// ```
     #[inline]
     #[doc(alias = "roaring_uint32_iterator_read")]
+    #[must_use]
     pub fn next_many(&mut self, dst: &mut [u32]) -> usize {
         self.cursor.read_many(dst)
     }
@@ -449,6 +453,7 @@ impl<'a> BitmapIterator<'a> {
     /// assert_eq!(iter.next(), Some(1));
     /// ```
     #[inline]
+    #[must_use]
     pub fn peek(&self) -> Option<u32> {
         self.cursor.current()
     }

diff --git a/croaring/src/bitmap64/imp.rs b/croaring/src/bitmap64/imp.rs
@@ -41,13 +41,15 @@ impl Bitmap64 {
     /// ```
     #[inline]
     #[doc(alias = "roaring64_bitmap_of_ptr")]
+    #[must_use]
     pub fn of(slice: &[u64]) -> Self {
         unsafe { Self::take_heap(ffi::roaring64_bitmap_of_ptr(slice.len(), slice.as_ptr())) }
     }
 
     /// Create a new bitmap containing all the values in a range
     #[inline]
     #[doc(alias = "roaring64_bitmap_from_range")]
+    #[must_use]
     pub fn from_range<R: RangeBounds<u64>>(range: R) -> Self {
         Self::from_range_with_step(range, 1)
     }
@@ -91,6 +93,7 @@ impl Bitmap64 {
     /// ```
     #[inline]
     #[doc(alias = "roaring64_bitmap_from_range")]
+    #[must_use]
     pub fn from_range_with_step<R: RangeBounds<u64>>(range: R, step: u64) -> Self {
         // This can't use `range_to_exclusive` because when the start is excluded, we want
         // to start at the next step, not one more
@@ -461,6 +464,9 @@ impl Bitmap64 {
     /// assert!(!bitmap4.is_strict_subset(&bitmap1));
     /// assert!(!bitmap1.is_strict_subset(&bitmap1));
     ///
+    #[inline]
+    #[must_use]
+    #[doc(alias = "roaring64_bitmap_is_strict_subset")]
     pub fn is_strict_subset(&self, other: &Self) -> bool {
         unsafe { ffi::roaring64_bitmap_is_strict_subset(self.raw.as_ptr(), other.raw.as_ptr()) }
     }
@@ -575,6 +581,7 @@ impl Bitmap64 {
     /// assert!(bitmap.contains_range(10..0));
     /// ```
     #[inline]
+    #[must_use]
     #[doc(alias = "roaring64_bitmap_contains_range")]
     pub fn contains_range<R: RangeBounds<u64>>(&self, range: R) -> bool {
         let Some(exclusive_range) = range_to_exclusive(range) else {
@@ -821,7 +828,8 @@ impl Bitmap64 {
     /// Serializes a bitmap to a slice of bytes in format `S`, re-using existing capacity
     ///
     /// `dst` is not cleared, data is added after any existing data. Returns the added slice of `dst`.
-    /// If `dst` is empty, it is guaranteed to hold only the serialized data after this call
+    /// Because of alignment requirements, the serialized data may not start at the beginning of
+    /// `dst`: the returned slice may not start at `dst.as_ptr()`.
     ///
     /// # Examples
     ///
@@ -834,11 +842,13 @@ impl Bitmap64 {
     /// let mut data = Vec::new();
     /// for bitmap in [original_bitmap_1, original_bitmap_2] {
     ///     data.clear();
-    ///     bitmap.serialize_into_vec::<Portable>(&mut data);
-    ///     // do something with data
+    ///     let serialized = bitmap.serialize_into_vec::<Portable>(&mut data);
+    ///     // do something with serialized
+    ///     # let _ = serialized;
     /// }
     /// ```
     #[inline]
+    #[must_use]
     #[doc(alias = "roaring64_bitmap_portable_serialize")]
     #[cfg(feature = "alloc")]
     pub fn serialize_into_vec<'a, S: Serializer>(&self, dst: &'a mut Vec<u8>) -> &'a [u8] {
@@ -856,6 +866,7 @@ impl Bitmap64 {
     /// See also [`Self::serialize_into_vec`] for a version that uses a Vec instead, or, for
     /// advanced use-cases, see [`Serializer::try_serialize_into`].
     #[inline]
+    #[must_use]
     pub fn try_serialize_into<'a, S: Serializer>(&self, dst: &'a mut [u8]) -> Option<&'a mut [u8]> {
         S::try_serialize_into_aligned(self, dst)
     }
@@ -892,6 +903,7 @@ impl Bitmap64 {
     ///
     /// On invalid input returns empty bitmap.
     #[inline]
+    #[must_use]
     pub fn deserialize<D: Deserializer>(buffer: &[u8]) -> Self {
         Self::try_deserialize::<D>(buffer).unwrap_or_default()
     }
@@ -1071,6 +1083,7 @@ impl Bitmap64 {
     /// assert!(!bitmap.intersect_with_range(100..0));
     /// ```
     #[inline]
+    #[must_use]
     #[doc(alias = "roaring64_bitmap_intersect_with_range")]
     pub fn intersect_with_range<R: RangeBounds<u64>>(&self, range: R) -> bool {
         let Some(exclusive_range) = range_to_exclusive(range) else {

diff --git a/croaring/src/bitmap64/iter.rs b/croaring/src/bitmap64/iter.rs
@@ -504,6 +504,7 @@ impl<'a> Bitmap64Iterator<'a> {
     /// # print_by_chunks(&Bitmap64::of(&[1, 2, 8, 20, 1000]));
     /// ```
     #[inline]
+    #[must_use]
     #[doc(alias = "roaring64_iterator_read")]
     pub fn next_many(&mut self, dst: &mut [u64]) -> usize {
         self.cursor.read_many(dst)
@@ -550,6 +551,7 @@ impl<'a> Bitmap64Iterator<'a> {
     /// assert_eq!(iter.next(), Some(1));
     /// ```
     #[inline]
+    #[must_use]
     pub fn peek(&self) -> Option<u64> {
         self.cursor.current()
     }