Package org.roaringbitmap

Interface ImmutableBitmapDataProvider

All Known Subinterfaces:
BitmapDataProvider
All Known Implementing Classes:
FastRankRoaringBitmap, ImmutableRoaringBitmap, MutableRoaringBitmap, RoaringBitmap
public interface ImmutableBitmapDataProvider
Interface representing an immutable bitmap.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static final class 
    ImmutableBitmapDataProvider.RoaringOfInt
    An internal class to help provide streams.

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    contains(int x)
    Checks whether the value in included, which is equivalent to checking if the corresponding bit is set (get in BitSet class).
    int
    first()
    Get the first (smallest) integer in this RoaringBitmap, that is, return the minimum of the set.
    void
    forEach(IntConsumer ic)
    Visit all values in the bitmap and pass them to the consumer.
    BatchIterator
    getBatchIterator()
    This iterator may be faster than others
    int
    getCardinality()
    Returns the number of distinct integers added to the bitmap (e.g., number of bits set).
    PeekableIntIterator
    getIntIterator()
    For better performance, consider the Use the forEach method.
    long
    getLongCardinality()
    Returns the number of distinct integers added to the bitmap (e.g., number of bits set).
    long
    getLongSizeInBytes()
    Estimate of the memory usage of this data structure.
    IntIterator
    getReverseIntIterator()
     
    int
    getSizeInBytes()
    Estimate of the memory usage of this data structure.
    boolean
    isEmpty()
    Checks whether the bitmap is empty.
    int
    last()
    Get the last (largest) integer in this RoaringBitmap, that is, return the maximum of the set.
    ImmutableBitmapDataProvider
    limit(int x)
    Create a new bitmap of the same class, containing at most maxcardinality integers.
    long
    nextAbsentValue(int fromValue)
    Returns the first absent value equal to or larger than the provided value (interpreted as an unsigned integer).
    long
    nextValue(int fromValue)
    Returns the first value equal to or larger than the provided value (interpreted as an unsigned integer).
    long
    previousAbsentValue(int fromValue)
    Returns the first absent value less than or equal to the provided value (interpreted as an unsigned integer).
    long
    previousValue(int fromValue)
    Returns the first value less than or equal to the provided value (interpreted as an unsigned integer).
    long
    rangeCardinality(long start, long end)
    Computes the number of values in the interval [start,end) where start is included and end excluded.
    int
    rank(int x)
    Rank returns the number of integers that are smaller or equal to x (rank(infinity) would be getCardinality()).
    long
    rankLong(int x)
    Rank returns the number of integers that are smaller or equal to x (rankLong(infinity) would be getLongCardinality()).
    default IntStream
    reverseStream()
     
    int
    select(int j)
    Return the jth value stored in this bitmap.
    void
    serialize(DataOutput out)
    Serialize this bitmap.
    void
    serialize(ByteBuffer buffer)
    Serialize this bitmap to a ByteBuffer.
    int
    serializedSizeInBytes()
    Report the number of bytes required to serialize this bitmap.
    default IntStream
    stream()
     
    int[]
    toArray()
    Return the set values as an array.

  • Method Details

    • contains

      boolean contains(int x)
      Checks whether the value in included, which is equivalent to checking if the corresponding bit is set (get in BitSet class).
      Parameters:
      x - integer value
      Returns:
      whether the integer value is included.

    • getCardinality

      int getCardinality()
      Returns the number of distinct integers added to the bitmap (e.g., number of bits set). Internally, this is computed as a 64-bit number.
      Returns:
      the cardinality

    • getLongCardinality

      long getLongCardinality()
      Returns the number of distinct integers added to the bitmap (e.g., number of bits set). This returns a full 64-bit result.
      Returns:
      the cardinality

    • forEach

      void forEach(IntConsumer ic)
      Visit all values in the bitmap and pass them to the consumer. * Usage: 
       
  bitmap.forEach(new IntConsumer() {

    {@literal @}Override
    public void accept(int value) {
      // do something here
      
    }});
   
 }
      Parameters:
      ic - the consumer

    • getIntIterator

      PeekableIntIterator getIntIterator()
      For better performance, consider the Use the forEach method.
      Returns:
      a custom iterator over set bits, the bits are traversed in ascending sorted order

    • getReverseIntIterator

      IntIterator getReverseIntIterator()
      Returns:
      a custom iterator over set bits, the bits are traversed in descending sorted order

    • stream

      default IntStream stream()
      Returns:
      an Ordered, Distinct, Sorted and Sized IntStream in ascending order

    • reverseStream

      default IntStream reverseStream()
      Returns:
      an Ordered, Distinct and Sized IntStream providing bits in descending sorted order

    • getBatchIterator

      BatchIterator getBatchIterator()
      This iterator may be faster than others
      Returns:
      iterator which works on batches of data.

    • getSizeInBytes

      int getSizeInBytes()
      Estimate of the memory usage of this data structure. Internally, this is computed as a 64-bit counter.
      Returns:
      estimated memory usage.

    • getLongSizeInBytes

      long getLongSizeInBytes()
      Estimate of the memory usage of this data structure. Provides full 64-bit number.
      Returns:
      estimated memory usage.

    • isEmpty

      boolean isEmpty()
      Checks whether the bitmap is empty.
      Returns:
      true if this bitmap contains no set bit

    • limit

      ImmutableBitmapDataProvider limit(int x)
      Create a new bitmap of the same class, containing at most maxcardinality integers.
      Parameters:
      x - maximal cardinality
      Returns:
      a new bitmap with cardinality no more than maxcardinality

    • rank

      int rank(int x)
      Rank returns the number of integers that are smaller or equal to x (rank(infinity) would be getCardinality()). If you provide the smallest value as a parameter, this function will return 1. If provide a value smaller than the smallest value, it will return 0. The value is internally computed as a 64-bit number.
      Parameters:
      x - upper limit
      Returns:
      the rank
      See Also:

    • rankLong

      long rankLong(int x)
      Rank returns the number of integers that are smaller or equal to x (rankLong(infinity) would be getLongCardinality()). If you provide the smallest value as a parameter, this function will return 1. If provide a value smaller than the smallest value, it will return 0. Same as "rank" but produces a full 64-bit value.
      Parameters:
      x - upper limit
      Returns:
      the rank
      See Also:

    • rangeCardinality

      long rangeCardinality(long start, long end)
      Computes the number of values in the interval [start,end) where start is included and end excluded. rangeCardinality(0,0x100000000) provides the total cardinality (getLongCardinality). The answer is a 64-bit value between 1 and 0x100000000.
      Parameters:
      start - lower limit (included)
      end - upper limit (excluded)
      Returns:
      the number of elements in [start,end), between 0 and 0x100000000.

    • select

      int select(int j)
      Return the jth value stored in this bitmap. The provided value needs to be smaller than the cardinality otherwise an IllegalArgumentException exception is thrown. The smallest value is at index 0. Note that this function differs in convention from the rank function which returns 1 when ranking the smallest value.
      Parameters:
      j - index of the value
      Returns:
      the value
      See Also:

    • first

      int first()
      Get the first (smallest) integer in this RoaringBitmap, that is, return the minimum of the set.
      Returns:
      the first (smallest) integer
      Throws:
      NoSuchElementException - if empty

    • last

      int last()
      Get the last (largest) integer in this RoaringBitmap, that is, return the maximum of the set.
      Returns:
      the last (largest) integer
      Throws:
      NoSuchElementException - if empty

    • nextValue

      long nextValue(int fromValue)
      Returns the first value equal to or larger than the provided value (interpreted as an unsigned integer). If no such bit exists then -1 is returned. It is not necessarily a computationally effective way to iterate through the values.
      Parameters:
      fromValue - the lower bound (inclusive)
      Returns:
      the smallest value larger than or equal to the specified value, or -1 if there is no such value

    • previousValue

      long previousValue(int fromValue)
      Returns the first value less than or equal to the provided value (interpreted as an unsigned integer). If no such bit exists then -1 is returned. It is not an efficient way to iterate through the values backwards.
      Parameters:
      fromValue - the upper bound (inclusive)
      Returns:
      the largest value less than or equal to the specified value, or -1 if there is no such value

    • nextAbsentValue

      long nextAbsentValue(int fromValue)
      Returns the first absent value equal to or larger than the provided value (interpreted as an unsigned integer). It is not necessarily a computationally effective way to iterate through the values.
      Parameters:
      fromValue - the lower bound (inclusive)
      Returns:
      the smallest absent value larger than or equal to the specified value.

    • previousAbsentValue

      long previousAbsentValue(int fromValue)
      Returns the first absent value less than or equal to the provided value (interpreted as an unsigned integer). It is not necessarily a computationally effective way to iterate through the values.
      Parameters:
      fromValue - the lower bound (inclusive)
      Returns:
      the smallest absent value larger than or equal to the specified value.

    • serialize

      void serialize(DataOutput out) throws IOException
      Serialize this bitmap. The current bitmap is not modified.
      Parameters:
      out - the DataOutput stream
      Throws:
      IOException - Signals that an I/O exception has occurred.

    • serialize

      void serialize(ByteBuffer buffer)
      Serialize this bitmap to a ByteBuffer. This is the preferred method to serialize to a byte array (byte[]) or to a String (via Base64.getEncoder().encodeToString).. Irrespective of the endianess of the provided buffer, data is written using LITTlE_ENDIAN as per the RoaringBitmap specification. The current bitmap is not modified. 
       
   byte[] array = new byte[mrb.serializedSizeInBytes()];
   mrb.serialize(ByteBuffer.wrap(array));
      Parameters:
      buffer - the ByteBuffer

    • serializedSizeInBytes

      int serializedSizeInBytes()
      Report the number of bytes required to serialize this bitmap. This is the number of bytes written out when using the serialize method. When using the writeExternal method, the count will be higher due to the overhead of Java serialization.
      Returns:
      the size in bytes

    • toArray

      int[] toArray()
      Return the set values as an array. The integer values are in sorted order.
      Returns:
      array representing the set values.