Package org.roaringbitmap

Class FastRankRoaringBitmap

java.lang.Object
org.roaringbitmap.RoaringBitmap
org.roaringbitmap.FastRankRoaringBitmap
All Implemented Interfaces:
Externalizable, Serializable, Cloneable, Iterable<Integer>, AppendableStorage<Container>, BitmapDataProvider, ImmutableBitmapDataProvider
public class FastRankRoaringBitmap extends RoaringBitmap
This extends RoaringBitmap to provide better performance for .rank and .select operations, at the cost of maintain a cache of cardinalities. On RoaringBitmap.select(int) and RoaringBitmap.rank(int) operations, RoaringBitmap needs to iterate along all underlying buckets to cumulate their cardinalities. This may lead to sub-optimal performance for application doing a large amount of .rank/.select over read-only RoaringBitmap, especially if the RoaringBitmap holds a large number of underlying buckets. This implementation will discard the cache of cardinality on any write operations, and it will memoize the computed cardinalities on any .rank or .select operation
See Also:
Serialized Form

  • Constructor Details

    • FastRankRoaringBitmap

      public FastRankRoaringBitmap()

    • FastRankRoaringBitmap

      public FastRankRoaringBitmap​(RoaringArray array)

  • Method Details

    • add

      public void add​(long rangeStart, long rangeEnd)
      Description copied from class: RoaringBitmap
      Add to the current bitmap all integers in [rangeStart,rangeEnd).
      Specified by:
      add in interface BitmapDataProvider
      Overrides:
      add in class RoaringBitmap
      Parameters:
      rangeStart - inclusive beginning of range
      rangeEnd - exclusive ending of range

    • add

      public void add​(int x)
      Description copied from class: RoaringBitmap
      Add the value to the container (set the value to "true"), whether it already appears or not. Java lacks native unsigned integers but the x argument is considered to be unsigned. Within bitmaps, numbers are ordered according to Integer.compareUnsigned(int, int). We order the numbers like 0, 1, ..., 2147483647, -2147483648, -2147483647,..., -1.
      Specified by:
      add in interface BitmapDataProvider
      Overrides:
      add in class RoaringBitmap
      Parameters:
      x - integer value

    • add

      public void add​(int... dat)
      Description copied from class: RoaringBitmap
      Set all the specified values to true. This can be expected to be slightly faster than calling "add" repeatedly. The provided integers values don't have to be in sorted order, but it may be preferable to sort them from a performance point of view.
      Overrides:
      add in class RoaringBitmap
      Parameters:
      dat - set values

    • add

      @Deprecated public void add​(int rangeStart, int rangeEnd)
      Deprecated.
      Description copied from class: RoaringBitmap
      Add to the current bitmap all integers in [rangeStart,rangeEnd).
      Overrides:
      add in class RoaringBitmap
      Parameters:
      rangeStart - inclusive beginning of range
      rangeEnd - exclusive ending of range

    • clear

      public void clear()
      Description copied from class: RoaringBitmap
      reset to an empty bitmap; result occupies as much space a newly created bitmap.
      Overrides:
      clear in class RoaringBitmap

    • flip

      public void flip​(int x)
      Description copied from class: RoaringBitmap
      Add the value if it is not already present, otherwise remove it.
      Overrides:
      flip in class RoaringBitmap
      Parameters:
      x - integer value

    • flip

      @Deprecated public void flip​(int rangeStart, int rangeEnd)
      Deprecated.
      Description copied from class: RoaringBitmap
      Modifies the current bitmap by complementing the bits in the given range, from rangeStart (inclusive) rangeEnd (exclusive).
      Overrides:
      flip in class RoaringBitmap
      Parameters:
      rangeStart - inclusive beginning of range
      rangeEnd - exclusive ending of range

    • flip

      public void flip​(long rangeStart, long rangeEnd)
      Description copied from class: RoaringBitmap
      Modifies the current bitmap by complementing the bits in the given range, from rangeStart (inclusive) rangeEnd (exclusive).
      Overrides:
      flip in class RoaringBitmap
      Parameters:
      rangeStart - inclusive beginning of range
      rangeEnd - exclusive ending of range

    • and

      public void and​(RoaringBitmap x2)
      Description copied from class: RoaringBitmap
      In-place bitwise AND (intersection) operation. The current bitmap is modified.
      Overrides:
      and in class RoaringBitmap
      Parameters:
      x2 - other bitmap

    • andNot

      public void andNot​(RoaringBitmap x2)
      Description copied from class: RoaringBitmap
      In-place bitwise ANDNOT (difference) operation. The current bitmap is modified.
      Overrides:
      andNot in class RoaringBitmap
      Parameters:
      x2 - other bitmap

    • remove

      @Deprecated public void remove​(int rangeStart, int rangeEnd)
      Deprecated.
      Description copied from class: RoaringBitmap
      Remove from the current bitmap all integers in [rangeStart,rangeEnd).
      Overrides:
      remove in class RoaringBitmap
      Parameters:
      rangeStart - inclusive beginning of range
      rangeEnd - exclusive ending of range

    • remove

      public void remove​(int x)
      Description copied from class: RoaringBitmap
      If present remove the specified integer (effectively, sets its bit value to false)
      Specified by:
      remove in interface BitmapDataProvider
      Overrides:
      remove in class RoaringBitmap
      Parameters:
      x - integer value representing the index in a bitmap

    • remove

      public void remove​(long rangeStart, long rangeEnd)
      Description copied from class: RoaringBitmap
      Remove from the current bitmap all integers in [rangeStart,rangeEnd).
      Overrides:
      remove in class RoaringBitmap
      Parameters:
      rangeStart - inclusive beginning of range
      rangeEnd - exclusive ending of range

    • checkedAdd

      public boolean checkedAdd​(int x)
      Description copied from class: RoaringBitmap
      Add the value to the container (set the value to "true"), whether it already appears or not.
      Overrides:
      checkedAdd in class RoaringBitmap
      Parameters:
      x - integer value
      Returns:
      true if the added int wasn't already contained in the bitmap. False otherwise.

    • checkedRemove

      public boolean checkedRemove​(int x)
      Description copied from class: RoaringBitmap
      If present remove the specified integer (effectively, sets its bit value to false)
      Overrides:
      checkedRemove in class RoaringBitmap
      Parameters:
      x - integer value representing the index in a bitmap
      Returns:
      true if the unset bit was already in the bitmap

    • or

      public void or​(RoaringBitmap x2)
      Description copied from class: RoaringBitmap
      In-place bitwise OR (union) operation. The current bitmap is modified.
      Overrides:
      or in class RoaringBitmap
      Parameters:
      x2 - other bitmap

    • xor

      public void xor​(RoaringBitmap x2)
      Description copied from class: RoaringBitmap
      In-place bitwise XOR (symmetric difference) operation. The current bitmap is modified.
      Overrides:
      xor in class RoaringBitmap
      Parameters:
      x2 - other bitmap

    • rankLong

      public long rankLong​(int x)
      Description copied from class: RoaringBitmap
      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.
      Specified by:
      rankLong in interface ImmutableBitmapDataProvider
      Overrides:
      rankLong in class RoaringBitmap
      Parameters:
      x - upper limit
      Returns:
      the rank
      See Also:
      Ranking in statistics

    • select

      public int select​(int j)
      Description copied from class: RoaringBitmap
      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.
      Specified by:
      select in interface ImmutableBitmapDataProvider
      Overrides:
      select in class RoaringBitmap
      Parameters:
      j - index of the value
      Returns:
      the value
      See Also:
      Selection algorithm

    • getLongSizeInBytes

      public long getLongSizeInBytes()
      Description copied from class: RoaringBitmap
      Estimate of the memory usage of this data structure. This can be expected to be within 1% of the true memory usage in common usage scenarios. If exact measures are needed, we recommend using dedicated libraries such as ehcache-sizeofengine. In adversarial cases, this estimate may be 10x the actual memory usage. For example, if you insert a single random value in a bitmap, then over a 100 bytes may be used by the JVM whereas this function may return an estimate of 32 bytes. The same will be true in the "sparse" scenario where you have a small set of random-looking integers spanning a wide range of values. These are considered adversarial cases because, as a general rule, if your data looks like a set of random integers, Roaring bitmaps are probably not the right data structure. Note that you can serialize your Roaring Bitmaps to disk and then construct ImmutableRoaringBitmap instances from a ByteBuffer. In such cases, the Java heap usage will be significantly less than what is reported. If your main goal is to compress arrays of integers, there are other libraries that are maybe more appropriate such as JavaFastPFOR. Note, however, that in general, random integers (as produced by random number generators or hash functions) are not compressible. Trying to compress random data is an adversarial use case.
      Specified by:
      getLongSizeInBytes in interface ImmutableBitmapDataProvider
      Overrides:
      getLongSizeInBytes in class RoaringBitmap
      Returns:
      estimated memory usage.
      See Also:
      JavaFastPFOR

    • getIntRankIterator

      public PeekableIntRankIterator getIntRankIterator()
      Get a special iterator that allows .peekNextRank efficiently
      Returns:
      iterator with fast rank access