roaring 0.3.0 → 0.4.0

data/ext/roaring/roaring.h

@@ -1,5 +1,5 @@
 // !!! DO NOT EDIT - THIS IS AN AUTO-GENERATED FILE !!!
-// Created by amalgamation.sh on 2024-05-13T21:29:25Z
+// Created by amalgamation.sh on 2024-09-21T20:01:13Z
 
 /*
  * The CRoaring project is under a dual license (Apache/MIT).
@@ -59,165 +59,14 @@
 // /include/roaring/roaring_version.h automatically generated by release.py, do not change by hand
 #ifndef ROARING_INCLUDE_ROARING_VERSION
 #define ROARING_INCLUDE_ROARING_VERSION
-#define ROARING_VERSION "4.0.0"
+#define ROARING_VERSION "4.1.7"
 enum {
     ROARING_VERSION_MAJOR = 4,
-    ROARING_VERSION_MINOR = 0,
-    ROARING_VERSION_REVISION = 0
+    ROARING_VERSION_MINOR = 1,
+    ROARING_VERSION_REVISION = 7
 };
 #endif // ROARING_INCLUDE_ROARING_VERSION
 // clang-format on/* end file include/roaring/roaring_version.h */
-/* begin file include/roaring/roaring_types.h */
-/*
-  Typedefs used by various components
-*/
-
-#ifndef ROARING_TYPES_H
-#define ROARING_TYPES_H
-
-#include <stdbool.h>
-#include <stdint.h>
-
-#ifdef __cplusplus
-extern "C" {
-namespace roaring {
-namespace api {
-#endif
-
-/**
- * When building .c files as C++, there's added compile-time checking if the
- * container types are derived from a `container_t` base class.  So long as
- * such a base class is empty, the struct will behave compatibly with C structs
- * despite the derivation.  This is due to the Empty Base Class Optimization:
- *
- * https://en.cppreference.com/w/cpp/language/ebo
- *
- * But since C isn't namespaced, taking `container_t` globally might collide
- * with other projects.  So roaring.h uses ROARING_CONTAINER_T, while internal
- * code #undefs that after declaring `typedef ROARING_CONTAINER_T container_t;`
- */
-#if defined(__cplusplus)
-extern "C++" {
-struct container_s {};
-}
-#define ROARING_CONTAINER_T ::roaring::api::container_s
-#else
-#define ROARING_CONTAINER_T void  // no compile-time checking
-#endif
-
-#define ROARING_FLAG_COW UINT8_C(0x1)
-#define ROARING_FLAG_FROZEN UINT8_C(0x2)
-
-/**
- * Roaring arrays are array-based key-value pairs having containers as values
- * and 16-bit integer keys. A roaring bitmap  might be implemented as such.
- */
-
-// parallel arrays.  Element sizes quite different.
-// Alternative is array
-// of structs.  Which would have better
-// cache performance through binary searches?
-
-typedef struct roaring_array_s {
-    int32_t size;
-    int32_t allocation_size;
-    ROARING_CONTAINER_T **containers;  // Use container_t in non-API files!
-    uint16_t *keys;
-    uint8_t *typecodes;
-    uint8_t flags;
-} roaring_array_t;
-
-typedef bool (*roaring_iterator)(uint32_t value, void *param);
-typedef bool (*roaring_iterator64)(uint64_t value, void *param);
-
-/**
- *  (For advanced users.)
- * The roaring_statistics_t can be used to collect detailed statistics about
- * the composition of a roaring bitmap.
- */
-typedef struct roaring_statistics_s {
-    uint32_t n_containers; /* number of containers */
-
-    uint32_t n_array_containers;  /* number of array containers */
-    uint32_t n_run_containers;    /* number of run containers */
-    uint32_t n_bitset_containers; /* number of bitmap containers */
-
-    uint32_t
-        n_values_array_containers;    /* number of values in array containers */
-    uint32_t n_values_run_containers; /* number of values in run containers */
-    uint32_t
-        n_values_bitset_containers; /* number of values in  bitmap containers */
-
-    uint32_t n_bytes_array_containers;  /* number of allocated bytes in array
-                                           containers */
-    uint32_t n_bytes_run_containers;    /* number of allocated bytes in run
-                                           containers */
-    uint32_t n_bytes_bitset_containers; /* number of allocated bytes in  bitmap
-                                           containers */
-
-    uint32_t
-        max_value; /* the maximal value, undefined if cardinality is zero */
-    uint32_t
-        min_value; /* the minimal value, undefined if cardinality is zero */
-    uint64_t sum_value; /* deprecated always zero */
-
-    uint64_t cardinality; /* total number of values stored in the bitmap */
-
-    // and n_values_arrays, n_values_rle, n_values_bitmap
-} roaring_statistics_t;
-
-/**
- *  (For advanced users.)
- * The roaring64_statistics_t can be used to collect detailed statistics about
- * the composition of a roaring64 bitmap.
- */
-typedef struct roaring64_statistics_s {
-    uint64_t n_containers; /* number of containers */
-
-    uint64_t n_array_containers;  /* number of array containers */
-    uint64_t n_run_containers;    /* number of run containers */
-    uint64_t n_bitset_containers; /* number of bitmap containers */
-
-    uint64_t
-        n_values_array_containers;    /* number of values in array containers */
-    uint64_t n_values_run_containers; /* number of values in run containers */
-    uint64_t
-        n_values_bitset_containers; /* number of values in  bitmap containers */
-
-    uint64_t n_bytes_array_containers;  /* number of allocated bytes in array
-                                           containers */
-    uint64_t n_bytes_run_containers;    /* number of allocated bytes in run
-                                           containers */
-    uint64_t n_bytes_bitset_containers; /* number of allocated bytes in  bitmap
-                                           containers */
-
-    uint64_t
-        max_value; /* the maximal value, undefined if cardinality is zero */
-    uint64_t
-        min_value; /* the minimal value, undefined if cardinality is zero */
-
-    uint64_t cardinality; /* total number of values stored in the bitmap */
-
-    // and n_values_arrays, n_values_rle, n_values_bitmap
-} roaring64_statistics_t;
-
-/**
- * Roaring-internal type used to iterate within a roaring container.
- */
-typedef struct roaring_container_iterator_s {
-    // For bitset and array containers this is the index of the bit / entry.
-    // For run containers this points at the run.
-    int32_t index;
-} roaring_container_iterator_t;
-
-#ifdef __cplusplus
-}
-}
-}  // extern "C" { namespace roaring { namespace api {
-#endif
-
-#endif /* ROARING_TYPES_H */
-/* end file include/roaring/roaring_types.h */
 /* begin file include/roaring/portability.h */
 /*
  * portability.h
@@ -806,10 +655,22 @@ static inline uint32_t croaring_refcount_get(const croaring_refcount_t *val) {
 
 #if defined(__GNUC__) || defined(__clang__)
 #define CROARING_DEPRECATED __attribute__((deprecated))
+#elif defined(_MSC_VER)
+#define CROARING_DEPRECATED __declspec(deprecated)
 #else
 #define CROARING_DEPRECATED
 #endif  // defined(__GNUC__) || defined(__clang__)
 
+// We want to initialize structs to zero portably (C and C++), without
+// warnings. We can do mystruct s = CROARING_ZERO_INITIALIZER;
+#if __cplusplus
+#define CROARING_ZERO_INITIALIZER \
+    {}
+#else
+#define CROARING_ZERO_INITIALIZER \
+    { 0 }
+#endif
+
 // We need portability.h to be included first,
 // but we also always want isadetection.h to be
 // included (right after).
@@ -819,6 +680,160 @@ static inline uint32_t croaring_refcount_get(const croaring_refcount_t *val) {
 // strict requirement.
 #endif                             /* INCLUDE_PORTABILITY_H_ */
 /* end file include/roaring/portability.h */
+/* begin file include/roaring/roaring_types.h */
+/*
+  Typedefs used by various components
+*/
+
+#ifndef ROARING_TYPES_H
+#define ROARING_TYPES_H
+
+#include <stdbool.h>
+#include <stdint.h>
+
+
+#ifdef __cplusplus
+extern "C" {
+namespace roaring {
+namespace api {
+#endif
+
+/**
+ * When building .c files as C++, there's added compile-time checking if the
+ * container types are derived from a `container_t` base class.  So long as
+ * such a base class is empty, the struct will behave compatibly with C structs
+ * despite the derivation.  This is due to the Empty Base Class Optimization:
+ *
+ * https://en.cppreference.com/w/cpp/language/ebo
+ *
+ * But since C isn't namespaced, taking `container_t` globally might collide
+ * with other projects.  So roaring.h uses ROARING_CONTAINER_T, while internal
+ * code #undefs that after declaring `typedef ROARING_CONTAINER_T container_t;`
+ */
+#if defined(__cplusplus)
+extern "C++" {
+struct container_s {};
+}
+#define ROARING_CONTAINER_T ::roaring::api::container_s
+#else
+#define ROARING_CONTAINER_T void  // no compile-time checking
+#endif
+
+#define ROARING_FLAG_COW UINT8_C(0x1)
+#define ROARING_FLAG_FROZEN UINT8_C(0x2)
+
+/**
+ * Roaring arrays are array-based key-value pairs having containers as values
+ * and 16-bit integer keys. A roaring bitmap  might be implemented as such.
+ */
+
+// parallel arrays.  Element sizes quite different.
+// Alternative is array
+// of structs.  Which would have better
+// cache performance through binary searches?
+
+typedef struct roaring_array_s {
+    int32_t size;
+    int32_t allocation_size;
+    ROARING_CONTAINER_T **containers;  // Use container_t in non-API files!
+    uint16_t *keys;
+    uint8_t *typecodes;
+    uint8_t flags;
+} roaring_array_t;
+
+typedef bool (*roaring_iterator)(uint32_t value, void *param);
+typedef bool (*roaring_iterator64)(uint64_t value, void *param);
+
+/**
+ *  (For advanced users.)
+ * The roaring_statistics_t can be used to collect detailed statistics about
+ * the composition of a roaring bitmap.
+ */
+typedef struct roaring_statistics_s {
+    uint32_t n_containers; /* number of containers */
+
+    uint32_t n_array_containers;  /* number of array containers */
+    uint32_t n_run_containers;    /* number of run containers */
+    uint32_t n_bitset_containers; /* number of bitmap containers */
+
+    uint32_t
+        n_values_array_containers;    /* number of values in array containers */
+    uint32_t n_values_run_containers; /* number of values in run containers */
+    uint32_t
+        n_values_bitset_containers; /* number of values in  bitmap containers */
+
+    uint32_t n_bytes_array_containers;  /* number of allocated bytes in array
+                                           containers */
+    uint32_t n_bytes_run_containers;    /* number of allocated bytes in run
+                                           containers */
+    uint32_t n_bytes_bitset_containers; /* number of allocated bytes in  bitmap
+                                           containers */
+
+    uint32_t
+        max_value; /* the maximal value, undefined if cardinality is zero */
+    uint32_t
+        min_value; /* the minimal value, undefined if cardinality is zero */
+
+    CROARING_DEPRECATED
+    uint64_t sum_value; /* deprecated always zero */
+
+    uint64_t cardinality; /* total number of values stored in the bitmap */
+
+    // and n_values_arrays, n_values_rle, n_values_bitmap
+} roaring_statistics_t;
+
+/**
+ *  (For advanced users.)
+ * The roaring64_statistics_t can be used to collect detailed statistics about
+ * the composition of a roaring64 bitmap.
+ */
+typedef struct roaring64_statistics_s {
+    uint64_t n_containers; /* number of containers */
+
+    uint64_t n_array_containers;  /* number of array containers */
+    uint64_t n_run_containers;    /* number of run containers */
+    uint64_t n_bitset_containers; /* number of bitmap containers */
+
+    uint64_t
+        n_values_array_containers;    /* number of values in array containers */
+    uint64_t n_values_run_containers; /* number of values in run containers */
+    uint64_t
+        n_values_bitset_containers; /* number of values in  bitmap containers */
+
+    uint64_t n_bytes_array_containers;  /* number of allocated bytes in array
+                                           containers */
+    uint64_t n_bytes_run_containers;    /* number of allocated bytes in run
+                                           containers */
+    uint64_t n_bytes_bitset_containers; /* number of allocated bytes in  bitmap
+                                           containers */
+
+    uint64_t
+        max_value; /* the maximal value, undefined if cardinality is zero */
+    uint64_t
+        min_value; /* the minimal value, undefined if cardinality is zero */
+
+    uint64_t cardinality; /* total number of values stored in the bitmap */
+
+    // and n_values_arrays, n_values_rle, n_values_bitmap
+} roaring64_statistics_t;
+
+/**
+ * Roaring-internal type used to iterate within a roaring container.
+ */
+typedef struct roaring_container_iterator_s {
+    // For bitset and array containers this is the index of the bit / entry.
+    // For run containers this points at the run.
+    int32_t index;
+} roaring_container_iterator_t;
+
+#ifdef __cplusplus
+}
+}
+}  // extern "C" { namespace roaring { namespace api {
+#endif
+
+#endif /* ROARING_TYPES_H */
+/* end file include/roaring/roaring_types.h */
 /* begin file include/roaring/bitset/bitset.h */
 #ifndef CROARING_CBITSET_BITSET_H
 #define CROARING_CBITSET_BITSET_H
@@ -1664,6 +1679,10 @@ size_t roaring_bitmap_shrink_to_fit(roaring_bitmap_t *r);
  * This function is endian-sensitive. If you have a big-endian system (e.g., a
  * mainframe IBM s390x), the data format is going to be big-endian and not
  * compatible with little-endian systems.
+ *
+ * When serializing data to a file, we recommend that you also use
+ * checksums so that, at deserialization, you can be confident
+ * that you are recovering the correct data.
  */
 size_t roaring_bitmap_serialize(const roaring_bitmap_t *r, char *buf);
 
@@ -1727,7 +1746,10 @@ roaring_bitmap_t *roaring_bitmap_portable_deserialize(const char *buf);
  * https://github.com/RoaringBitmap/RoaringFormatSpec
  *
  * The function itself is safe in the sense that it will not cause buffer
- * overflows. However, for correct operations, it is assumed that the bitmap
+ * overflows: it will not read beyond the scope of the provided buffer
+ * (buf,maxbytes).
+ *
+ * However, for correct operations, it is assumed that the bitmap
  * read was once serialized from a valid bitmap (i.e., it follows the format
  * specification). If you provided an incorrect input (garbage), then the bitmap
  * read may not be in a valid state and following operations may not lead to
@@ -1737,8 +1759,10 @@ roaring_bitmap_t *roaring_bitmap_portable_deserialize(const char *buf);
  * but not for random inputs.
  *
  * You may use roaring_bitmap_internal_validate to check the validity of the
- * bitmap prior to using it. You may also use other strategies to check for
- * corrupted inputs (e.g., checksums).
+ * bitmap prior to using it.
+ *
+ * We recommend that you use checksums to check that serialized data corresponds
+ * to a serialized bitmap.
  *
  * This function is endian-sensitive. If you have a big-endian system (e.g., a
  * mainframe IBM s390x), the data format is going to be big-endian and not
@@ -1800,6 +1824,10 @@ size_t roaring_bitmap_portable_size_in_bytes(const roaring_bitmap_t *r);
  * This function is endian-sensitive. If you have a big-endian system (e.g., a
  * mainframe IBM s390x), the data format is going to be big-endian and not
  * compatible with little-endian systems.
+ *
+ * When serializing data to a file, we recommend that you also use
+ * checksums so that, at deserialization, you can be confident
+ * that you are recovering the correct data.
  */
 size_t roaring_bitmap_portable_serialize(const roaring_bitmap_t *r, char *buf);
 
@@ -1834,6 +1862,10 @@ size_t roaring_bitmap_frozen_size_in_bytes(const roaring_bitmap_t *r);
  * This function is endian-sensitive. If you have a big-endian system (e.g., a
  * mainframe IBM s390x), the data format is going to be big-endian and not
  * compatible with little-endian systems.
+ *
+ * When serializing data to a file, we recommend that you also use
+ * checksums so that, at deserialization, you can be confident
+ * that you are recovering the correct data.
  */
 void roaring_bitmap_frozen_serialize(const roaring_bitmap_t *r, char *buf);
 
@@ -2247,12 +2279,12 @@ using namespace ::roaring::api;
 #ifndef INCLUDE_ROARING_MEMORY_H_
 #define INCLUDE_ROARING_MEMORY_H_
 
+#include <stddef.h>  // for size_t
+
 #ifdef __cplusplus
 extern "C" {
 #endif
 
-#include <stddef.h>  // for size_t
-
 typedef void* (*roaring_malloc_p)(size_t);
 typedef void* (*roaring_realloc_p)(void*, size_t);
 typedef void* (*roaring_calloc_p)(size_t, size_t);
@@ -2376,6 +2408,14 @@ roaring64_bitmap_t *roaring64_bitmap_of_ptr(size_t n_args,
         &((const uint64_t[]){0, __VA_ARGS__})[1])
 #endif
 
+/**
+ * Create a new bitmap by moving containers from a 32 bit roaring bitmap.
+ *
+ * After calling this function, the original bitmap will be empty, and the
+ * returned bitmap will contain all the values from the original bitmap.
+ */
+roaring64_bitmap_t *roaring64_bitmap_move_from_roaring32(roaring_bitmap_t *r);
+
 /**
  * Create a new bitmap containing all the values in [min, max) that are at a
  * distance k*step from min.
@@ -2486,6 +2526,11 @@ void roaring64_bitmap_remove_range(roaring64_bitmap_t *r, uint64_t min,
 void roaring64_bitmap_remove_range_closed(roaring64_bitmap_t *r, uint64_t min,
                                           uint64_t max);
 
+/**
+ * Empties the bitmap.
+ */
+void roaring64_bitmap_clear(roaring64_bitmap_t *r);
+
 /**
  * Returns true if the provided value is present.
  */
@@ -2556,6 +2601,12 @@ uint64_t roaring64_bitmap_get_cardinality(const roaring64_bitmap_t *r);
 uint64_t roaring64_bitmap_range_cardinality(const roaring64_bitmap_t *r,
                                             uint64_t min, uint64_t max);
 
+/**
+ * Returns the number of elements in the range [min, max]
+ */
+uint64_t roaring64_bitmap_range_closed_cardinality(const roaring64_bitmap_t *r,
+                                                   uint64_t min, uint64_t max);
+
 /**
  * Returns true if the bitmap is empty (cardinality is zero).
  */
@@ -2775,6 +2826,10 @@ size_t roaring64_bitmap_portable_size_in_bytes(const roaring64_bitmap_t *r);
  * This function is endian-sensitive. If you have a big-endian system (e.g., a
  * mainframe IBM s390x), the data format is going to be big-endian and not
  * compatible with little-endian systems.
+ *
+ * When serializing data to a file, we recommend that you also use
+ * checksums so that, at deserialization, you can be confident
+ * that you are recovering the correct data.
  */
 size_t roaring64_bitmap_portable_serialize(const roaring64_bitmap_t *r,
                                            char *buf);
@@ -2789,14 +2844,17 @@ size_t roaring64_bitmap_portable_deserialize_size(const char *buf,
                                                   size_t maxbytes);
 
 /**
- * Read a bitmap from a serialized buffer safely (reading up to maxbytes).
+ * Read a bitmap from a serialized buffer (reading up to maxbytes).
  * In case of failure, NULL is returned.
  *
  * This is meant to be compatible with other languages
  * https://github.com/RoaringBitmap/RoaringFormatSpec#extension-for-64-bit-implementations
  *
  * The function itself is safe in the sense that it will not cause buffer
- * overflows. However, for correct operations, it is assumed that the bitmap
+ * overflows: it will not read beyond the scope of the provided buffer
+ * (buf,maxbytes).
+ *
+ * However, for correct operations, it is assumed that the bitmap
  * read was once serialized from a valid bitmap (i.e., it follows the format
  * specification). If you provided an incorrect input (garbage), then the bitmap
  * read may not be in a valid state and following operations may not lead to
@@ -2805,6 +2863,12 @@ size_t roaring64_bitmap_portable_deserialize_size(const char *buf,
  * order. This is is guaranteed to happen when serializing an existing bitmap,
  * but not for random inputs.
  *
+ * You may use roaring64_bitmap_internal_validate to check the validity of the
+ * bitmap prior to using it.
+ *
+ * We recommend that you use checksums to check that serialized data corresponds
+ * to a serialized bitmap.
+ *
  * This function is endian-sensitive. If you have a big-endian system (e.g., a
  * mainframe IBM s390x), the data format is going to be big-endian and not
  * compatible with little-endian systems.

data/lib/roaring/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Roaring
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/roaring.rb

@@ -8,37 +8,67 @@ module Roaring
   class Error < StandardError; end
 
   module BitmapCommon
-    def self.included(base)
-      super
-
-      base.extend ClassMethods
-
-      base.alias_method :size, :cardinality
-      base.alias_method :length, :cardinality
-      base.alias_method :count, :cardinality
-
-      base.alias_method :+, :|
-      base.alias_method :union, :|
-      base.alias_method :intersection, :&
-      base.alias_method :difference, :-
-
-      base.alias_method :delete, :remove
-      base.alias_method :delete?, :remove?
-
-      base.alias_method :first, :min
-      base.alias_method :last, :max
-
-      base.alias_method :eql?, :==
-
-      base.alias_method :===, :include?
-
-      base.alias_method :subset?, :<=
-      base.alias_method :proper_subset?, :<
-      base.alias_method :superset?, :>=
-      base.alias_method :proper_superset?, :>
-    end
-
     module ClassMethods
+      # @private
+      # @!macro [attach] property
+      #   @!parse alias_method :<<, :add
+      #
+      #   @!parse alias_method :size, :cardinality
+      #   @!parse alias_method :length, :cardinality
+      #   @!parse alias_method :count, :cardinality
+      #
+      #   @!parse alias_method :&, :and
+      #   @!parse alias_method :|, :or
+      #   @!parse alias_method :^, :xor
+      #   @!parse alias_method :-, :andnot
+      #   @!parse alias_method :+, :or
+      #   @!parse alias_method :union, :or
+      #   @!parse alias_method :intersection, :and
+      #   @!parse alias_method :difference, :andnot
+      #
+      #   @!parse alias_method :delete, :remove
+      #   @!parse alias_method :delete?, :remove?
+      #
+      #   @!parse alias_method :first, :min
+      #   @!parse alias_method :last, :max
+      #
+      #   @!parse alias_method :eql?, :==
+      #
+      #   @!parse alias_method :===, :include?
+      #
+      #   @!parse alias_method :subset?, :<=
+      #   @!parse alias_method :proper_subset?, :<
+      def define_roaring_aliases!
+        alias_method :<<, :add
+
+        alias_method :size, :cardinality
+        alias_method :length, :cardinality
+        alias_method :count, :cardinality
+
+        alias_method :&, :and
+        alias_method :|, :or
+        alias_method :^, :xor
+        alias_method :-, :andnot
+        alias_method :+, :or
+        alias_method :union, :or
+        alias_method :intersection, :and
+        alias_method :difference, :andnot
+
+        alias_method :delete, :remove
+        alias_method :delete?, :remove?
+
+        alias_method :first, :min
+        alias_method :last, :max
+
+        alias_method :eql?, :==
+
+        alias_method :===, :include?
+
+        alias_method :subset?, :<=
+        alias_method :proper_subset?, :<
+      end
+
+      # Convenience method for building a bitmap
       def [](*args)
         if args.size == 0
           new
@@ -61,6 +91,12 @@ module Roaring
 
       if enum.instance_of?(self.class)
         replace(enum)
+      elsif Range === enum
+        if enum.exclude_end?
+          add_range(enum.begin, enum.end)
+        else
+          add_range_closed(enum.begin, enum.end)
+        end
       else
         enum.each { |x| self << x }
       end
@@ -74,14 +110,27 @@ module Roaring
       replace(other)
     end
 
-    def >(other)
+    # Check if `self` is a superset of `other`. A superset requires that `self` contain all of `other`'s elemtents. They may be equal.
+    # @return [Boolean] `true` if `self` is a strict subset of `other`, otherwise `false`
+    def superset?(other)
+      other <= self
+    end
+
+    # Check if `self` is a strict superset of `other`. A strict superset requires that `self` contain all of `other`'s elemtents, but that they aren't exactly equal.
+    # @return [Boolean] `true` if `self` is a strict subset of `other`, otherwise `false`
+    def proper_superset?(other)
       other < self
     end
 
-    def >=(other)
-      other <= self
+    alias_method :>=, :superset?
+    alias_method :>, :proper_superset?
+
+    def add_range(min, max)
+      return if max <= min
+      add_range_closed(min, max - 1)
     end
 
+    # @return [Integer] Returns 0 if the bitmaps are equal, -1 / +1 if the set is a subset / superset of the given set, or nil if they both have unique elements.
     def <=>(other)
       if self == other
         0
@@ -102,14 +151,15 @@ module Roaring
       serialize
     end
 
-    def to_a
-      map(&:itself)
-    end
-
     def to_set
-      ::Set.new(to_a)
+      ::Set.new(self)
     end
 
+    # @example Small bitmap
+    #   Roaring::Bitmap32[1,2,3].inspect #=> "#<Roaring::Bitmap32 {1, 2, 3}>"
+    # @example Large bitmap
+    #   Roaring::Bitmap32[1..1000].inspect #=> "#<Roaring::Bitmap32 (1000 values)>"
+    # @return [String] a programmer-readable representation of the bitmap
     def inspect
       cardinality = self.cardinality
       if cardinality < 64
@@ -122,6 +172,9 @@ module Roaring
 
   class Bitmap32
     include BitmapCommon
+    extend BitmapCommon::ClassMethods
+
+    define_roaring_aliases!
 
     MIN = 0
     MAX = (2**32) - 1
@@ -130,6 +183,9 @@ module Roaring
 
   class Bitmap64
     include BitmapCommon
+    extend BitmapCommon::ClassMethods
+
+    define_roaring_aliases!
 
     MIN = 0
     MAX = (2**64) - 1