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:

Nested Class Summary

Nested classes/interfaces inherited from interface org.roaringbitmap.ImmutableBitmapDataProvider
ImmutableBitmapDataProvider.RoaringOfInt
Constructor Summary

Constructors

Constructor

Description

FastRankRoaringBitmap()

FastRankRoaringBitmap(RoaringArray array)
Method Summary

Modifier and Type

Method

Description

void

add(int x)

Add the value to the container (set the value to "true"), whether it already appears or not.

void

add(int... dat)

Set all the specified values to true.

void

add(int rangeStart, int rangeEnd)

Deprecated.

void

add(long rangeStart, long rangeEnd)

Add to the current bitmap all integers in [rangeStart,rangeEnd).

void

and(RoaringBitmap x2)

In-place bitwise AND (intersection) operation.

void

andNot(RoaringBitmap x2)

In-place bitwise ANDNOT (difference) operation.

boolean

checkedAdd(int x)

Add the value to the container (set the value to "true"), whether it already appears or not.

boolean

checkedRemove(int x)

If present remove the specified integer (effectively, sets its bit value to false)

void

clear()

reset to an empty bitmap; result occupies as much space a newly created bitmap.

void

flip(int x)

Add the value if it is not already present, otherwise remove it.

void

flip(int rangeStart, int rangeEnd)

Deprecated.

void

flip(long rangeStart, long rangeEnd)

Modifies the current bitmap by complementing the bits in the given range, from rangeStart (inclusive) rangeEnd (exclusive).

PeekableIntRankIterator

getIntRankIterator()

Get a special iterator that allows .peekNextRank efficiently

long

getLongSizeInBytes()

Estimate of the memory usage of this data structure.

void

or(RoaringBitmap x2)

In-place bitwise OR (union) operation.

long

rankLong(int x)

Rank returns the number of integers that are smaller or equal to x (Rank(infinity) would be GetCardinality()).

void

remove(int x)

If present remove the specified integer (effectively, sets its bit value to false)

void

remove(int rangeStart, int rangeEnd)

Deprecated.

void

remove(long rangeStart, long rangeEnd)

Remove from the current bitmap all integers in [rangeStart,rangeEnd).

int

select(int j)

Return the jth value stored in this bitmap.

void

xor(RoaringBitmap x2)

In-place bitwise XOR (symmetric difference) operation.

Methods inherited from class org.roaringbitmap.RoaringBitmap
add, add, addN, addOffset, and, and, and, andCardinality, andNot, andNot, andNot, andNotCardinality, append, bitmapOf, bitmapOfRange, bitmapOfUnordered, cardinalityExceeds, clone, contains, contains, contains, deserialize, deserialize, deserialize, equals, first, firstSigned, flip, flip, forAllInRange, forEach, forEachInRange, getBatchIterator, getCardinality, getContainerCount, getContainerPointer, getIntIterator, getLongCardinality, getReverseIntIterator, getSignedIntIterator, getSizeInBytes, hashCode, hasRunCompression, intersects, intersects, isEmpty, isHammingSimilar, iterator, last, lastSigned, lazyor, lazyor, lazyorfromlazyinputs, limit, maximumSerializedSize, naivelazyor, nextAbsentValue, nextValue, or, or, or, or, or, orCardinality, orNot, orNot, previousAbsentValue, previousValue, rangeCardinality, rank, readExternal, remove, remove, removeRunCompression, repairAfterLazy, runOptimize, selectRange, serialize, serialize, serializedSizeInBytes, toArray, toMutableRoaringBitmap, toString, trim, writeExternal, xor, xor, xor, xorCardinality

Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.roaringbitmap.ImmutableBitmapDataProvider
reverseStream, stream

Methods inherited from interface java.lang.Iterable
forEach, spliterator

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 toInteger.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

Class FastRankRoaringBitmap

Nested Class Summary

Nested classes/interfaces inherited from interface org.roaringbitmap.ImmutableBitmapDataProvider

Constructor Summary

Method Summary

Methods inherited from class org.roaringbitmap.RoaringBitmap

Methods inherited from class java.lang.Object

Methods inherited from interface org.roaringbitmap.ImmutableBitmapDataProvider

Methods inherited from interface java.lang.Iterable

Constructor Details

FastRankRoaringBitmap

FastRankRoaringBitmap

Method Details

add

add

add

add

clear

flip

flip

flip

and

andNot

remove

remove

remove

checkedAdd

checkedRemove

or

xor

rankLong

select

getLongSizeInBytes

getIntRankIterator