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

Author:

Benoit Lacelle

See Also:

Serialized Form

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, bitmapOfUnordered, clone, contains, contains, contains, deserialize, deserialize, deserialize, equals, first, flip, flip, forEach, getBatchIterator, getCardinality, getContainerPointer, getIntIterator, getLongCardinality, getReverseIntIterator, getSizeInBytes, hashCode, hasRunCompression, intersects, intersects, isEmpty, isHammingSimilar, iterator, last, lazyor, lazyor, lazyorfromlazyinputs, limit, maximumSerializedSize, naivelazyor, nextAbsentValue, nextValue, or, or, or, or, or, orCardinality, previousAbsentValue, previousValue, rangeCardinality, rank, readExternal, remove, remove, removeRunCompression, repairAfterLazy, runOptimize, 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 java.lang.Iterable

forEach, spliterator

Constructor Detail

FastRankRoaringBitmap

public FastRankRoaringBitmap()

FastRankRoaringBitmap

public FastRankRoaringBitmap(RoaringArray array)

Method Detail

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()).

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.

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