From 78c98384819d56819f43899fa773ff9551a35e88 Mon Sep 17 00:00:00 2001 From: Zachary Dremann Date: Tue, 25 Jun 2024 19:01:44 -0400 Subject: [PATCH] More must_use Adding must_use is technically a breaking change, would like to get this in now --- croaring/src/bitmap/imp.rs | 17 ++++++++++++++--- croaring/src/bitmap/iter.rs | 5 +++++ croaring/src/bitmap64/imp.rs | 19 ++++++++++++++++--- croaring/src/bitmap64/iter.rs | 2 ++ 4 files changed, 37 insertions(+), 6 deletions(-) diff --git a/croaring/src/bitmap/imp.rs b/croaring/src/bitmap/imp.rs index e07ac7f..b0b328e 100644 --- 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>(&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>(&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::(&mut data); - /// // do something with data + /// let serialized: &[u8] = bitmap.serialize_into_vec::(&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) -> &'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(buffer: &[u8]) -> Self { Self::try_deserialize::(buffer).unwrap_or_else(Bitmap::new) } @@ -999,6 +1007,7 @@ impl Bitmap { /// assert_eq!(bitmap3.iter().collect::>(), [3, 4, 5]); #[inline] #[doc(alias = "roaring_bitmap_from_range")] + #[must_use] pub fn from_range>(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>(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>(&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 index 331e1bb..74bd620 100644 --- 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 { 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 { self.cursor.current() } diff --git a/croaring/src/bitmap64/imp.rs b/croaring/src/bitmap64/imp.rs index 21c0cec..de4a2b0 100644 --- a/croaring/src/bitmap64/imp.rs +++ b/croaring/src/bitmap64/imp.rs @@ -41,6 +41,7 @@ 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())) } } @@ -48,6 +49,7 @@ impl Bitmap64 { /// Create a new bitmap containing all the values in a range #[inline] #[doc(alias = "roaring64_bitmap_from_range")] + #[must_use] pub fn from_range>(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>(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>(&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::(&mut data); - /// // do something with data + /// let serialized = bitmap.serialize_into_vec::(&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) -> &'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(buffer: &[u8]) -> Self { Self::try_deserialize::(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>(&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 index 037431b..aba3d50 100644 --- 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 { self.cursor.current() }