org.roaringbitmap

Class RoaringBitmap

java.lang.Object

org.roaringbitmap.RoaringBitmap

All Implemented Interfaces:

Externalizable, Serializable, Cloneable, Iterable<Integer>, ImmutableBitmapDataProvider

public class RoaringBitmap
extends Object
implements Cloneable, Serializable, Iterable<Integer>, Externalizable, ImmutableBitmapDataProvider

RoaringBitmap, a compressed alternative to the BitSet.

 
      import org.roaringbitmap.*;
       
      //...
      
      RoaringBitmap rr = RoaringBitmap.bitmapOf(1,2,3,1000);
      RoaringBitmap rr2 = new RoaringBitmap();
      for(int k = 4000; k<4255;++k) rr2.add(k);
      RoaringBitmap rror = RoaringBitmap.or(rr, rr2);
 
 

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
RoaringBitmap() Create an empty bitmap

Method Summary

Modifier and Type	Method and Description
void	add(int x) set the value to "true", whether it already appears or not.
void	and(RoaringBitmap x2) In-place bitwise AND (intersection) operation.
static RoaringBitmap	and(RoaringBitmap x1, RoaringBitmap x2) Bitwise AND (intersection) operation.
void	andNot(RoaringBitmap x2) In-place bitwise ANDNOT (difference) operation.
static RoaringBitmap	andNot(RoaringBitmap x1, RoaringBitmap x2) Bitwise ANDNOT (difference) operation.
static RoaringBitmap	bitmapOf(int... dat) Generate a bitmap with the specified values set to true.
void	clear() reset to an empty bitmap; result occupies as much space a newly created bitmap.
RoaringBitmap	clone()
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).
void	deserialize(DataInput in) Deserialize (retrieve) this bitmap.
boolean	equals(Object o)
void	flip(int rangeStart, int rangeEnd) Modifies the current bitmap by complementing the bits in the given range, from rangeStart (inclusive) rangeEnd (exclusive).
static RoaringBitmap	flip(RoaringBitmap bm, int rangeStart, int rangeEnd) Complements the bits in the given range, from rangeStart (inclusive) rangeEnd (exclusive).
int	getCardinality() Returns the number of distinct integers added to the bitmap (e.g., number of bits set).
IntIterator	getIntIterator()
IntIterator	getReverseIntIterator()
int	getSizeInBytes() Estimate of the memory usage of this data structure.
int	hashCode()
boolean	isEmpty() Checks whether the bitmap is empty.
Iterator<Integer>	iterator() iterate over the positions of the true values.
RoaringBitmap	limit(int maxcardinality) Create a new Roaring bitmap containing at most maxcardinality integers.
void	or(RoaringBitmap x2) In-place bitwise OR (union) operation.
static RoaringBitmap	or(RoaringBitmap x1, RoaringBitmap x2) Bitwise OR (union) operation.
int	rank(int x) Rank returns the number of integers that are smaller or equal to x (Rank(infinity) would be GetCardinality()).
void	readExternal(ObjectInput in)
void	remove(int x) If present remove the specified integers (effectively, sets its bit value to false)
int	select(int j) Return the jth value stored in this bitmap.
void	serialize(DataOutput out) Serialize this bitmap.
int	serializedSizeInBytes() Report the number of bytes required to serialize this bitmap.
int[]	toArray() Return the set values as an array.
String	toString() A string describing the bitmap.
void	trim() Recover allocated but unused memory.
void	writeExternal(ObjectOutput out)
void	xor(RoaringBitmap x2) In-place bitwise XOR (symmetric difference) operation.
static RoaringBitmap	xor(RoaringBitmap x1, RoaringBitmap x2) Bitwise XOR (symmetric difference) operation.

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

RoaringBitmap

public RoaringBitmap()

Create an empty bitmap

Method Detail

and

public static RoaringBitmap and(RoaringBitmap x1,
                                RoaringBitmap x2)

Bitwise AND (intersection) operation. The provided bitmaps are *not* modified. This operation is thread-safe as long as the provided bitmaps remain unchanged. If you have more than 2 bitmaps, consider using the FastAggregation class.

Parameters:

x1 - first bitmap

x2 - other bitmap

Returns:

result of the operation

See Also:

FastAggregation.and(RoaringBitmap...)

andNot

public static RoaringBitmap andNot(RoaringBitmap x1,
                                   RoaringBitmap x2)

Bitwise ANDNOT (difference) operation. The provided bitmaps are *not* modified. This operation is thread-safe as long as the provided bitmaps remain unchanged.

Parameters:

x1 - first bitmap

x2 - other bitmap

Returns:

result of the operation

bitmapOf

public static RoaringBitmap bitmapOf(int... dat)

Generate a bitmap with the specified values set to true. 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.

Parameters:

dat - set values

Returns:

a new bitmap

flip

public static RoaringBitmap flip(RoaringBitmap bm,
                                 int rangeStart,
                                 int rangeEnd)

Complements the bits in the given range, from rangeStart (inclusive) rangeEnd (exclusive). The given bitmap is unchanged.

Parameters:

bm - bitmap being negated

rangeStart - inclusive beginning of range

rangeEnd - exclusive ending of range

Returns:

a new Bitmap

or

public static RoaringBitmap or(RoaringBitmap x1,
                               RoaringBitmap x2)

Bitwise OR (union) operation. The provided bitmaps are *not* modified. This operation is thread-safe as long as the provided bitmaps remain unchanged. If you have more than 2 bitmaps, consider using the FastAggregation class.

Parameters:

x1 - first bitmap

x2 - other bitmap

Returns:

result of the operation

See Also:

FastAggregation.or(RoaringBitmap...), FastAggregation.horizontal_or(RoaringBitmap...)

rank

public int rank(int x)

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

Specified by:

rank in interface ImmutableBitmapDataProvider

Parameters:

x - upper limit

Returns:

the rank

select

public int select(int j)

Return the jth value stored in this bitmap.

Specified by:

select in interface ImmutableBitmapDataProvider

Parameters:

j - index of the value

Returns:

the value

xor

public static RoaringBitmap xor(RoaringBitmap x1,
                                RoaringBitmap x2)

Bitwise XOR (symmetric difference) operation. The provided bitmaps are *not* modified. This operation is thread-safe as long as the provided bitmaps remain unchanged. If you have more than 2 bitmaps, consider using the FastAggregation class.

Parameters:

x1 - first bitmap

x2 - other bitmap

Returns:

result of the operation

See Also:

FastAggregation.xor(RoaringBitmap...), FastAggregation.horizontal_xor(RoaringBitmap...)

add

public void add(int x)

set the value to "true", whether it already appears or not.

Parameters:

x - integer value

and

public void and(RoaringBitmap x2)

In-place bitwise AND (intersection) operation. The current bitmap is modified.

Parameters:

x2 - other bitmap

andNot

public void andNot(RoaringBitmap x2)

In-place bitwise ANDNOT (difference) operation. The current bitmap is modified.

Parameters:

x2 - other bitmap

clear

public void clear()

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

clone

public RoaringBitmap clone()

Overrides:

clone in class Object

contains

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

Specified by:

contains in interface ImmutableBitmapDataProvider

Parameters:

x - integer value

Returns:

whether the integer value is included.

deserialize

public void deserialize(DataInput in)
                 throws IOException

Deserialize (retrieve) this bitmap. The current bitmap is overwritten.

Parameters:

in - the DataInput stream

Throws:

IOException - Signals that an I/O exception has occurred.

equals

public boolean equals(Object o)

Overrides:

equals in class Object

flip

public void flip(int rangeStart,
                 int rangeEnd)

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

Parameters:

rangeStart - inclusive beginning of range

rangeEnd - exclusive ending of range

getCardinality

public int getCardinality()

Returns the number of distinct integers added to the bitmap (e.g., number of bits set).

Specified by:

getCardinality in interface ImmutableBitmapDataProvider

Returns:

the cardinality

getIntIterator

public IntIterator getIntIterator()

Specified by:

getIntIterator in interface ImmutableBitmapDataProvider

Returns:

a custom iterator over set bits, the bits are traversed in ascending sorted order

getReverseIntIterator

public IntIterator getReverseIntIterator()

Specified by:

getReverseIntIterator in interface ImmutableBitmapDataProvider

Returns:

a custom iterator over set bits, the bits are traversed in descending sorted order

getSizeInBytes

public int getSizeInBytes()

Estimate of the memory usage of this data structure. This can be expected to be within 1% of the true memory usage.

Specified by:

getSizeInBytes in interface ImmutableBitmapDataProvider

Returns:

estimated memory usage.

hashCode

public int hashCode()

Overrides:

hashCode in class Object

iterator

public Iterator<Integer> iterator()

iterate over the positions of the true values.

Specified by:

iterator in interface Iterable<Integer>

Returns:

the iterator

isEmpty

public boolean isEmpty()

Checks whether the bitmap is empty.

Specified by:

isEmpty in interface ImmutableBitmapDataProvider

Returns:

true if this bitmap contains no set bit

or

public void or(RoaringBitmap x2)

In-place bitwise OR (union) operation. The current bitmap is modified.

Parameters:

x2 - other bitmap

readExternal

public void readExternal(ObjectInput in)
                  throws IOException,
                         ClassNotFoundException

Specified by:

readExternal in interface Externalizable

Throws:

IOException

ClassNotFoundException

remove

public void remove(int x)

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

Parameters:

x - integer value representing the index in a bitmap

serialize

public void serialize(DataOutput out)
               throws IOException

Serialize this bitmap. The current bitmap is not modified.

Specified by:

serialize in interface ImmutableBitmapDataProvider

Parameters:

out - the DataOutput stream

Throws:

IOException - Signals that an I/O exception has occurred.

serializedSizeInBytes

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

Specified by:

serializedSizeInBytes in interface ImmutableBitmapDataProvider

Returns:

the size in bytes

limit

public RoaringBitmap limit(int maxcardinality)

Create a new Roaring bitmap containing at most maxcardinality integers.

Specified by:

limit in interface ImmutableBitmapDataProvider

Parameters:

maxcardinality - maximal cardinality

Returns:

a new bitmap with cardinality no more than maxcardinality

toArray

public int[] toArray()

Return the set values as an array. The integer values are in sorted order.

Specified by:

toArray in interface ImmutableBitmapDataProvider

Returns:

array representing the set values.

toString

public String toString()

A string describing the bitmap.

Overrides:

toString in class Object

Returns:

the string

trim

public void trim()

Recover allocated but unused memory.

writeExternal

public void writeExternal(ObjectOutput out)
                   throws IOException

Specified by:

writeExternal in interface Externalizable

Throws:

IOException

xor

public void xor(RoaringBitmap x2)

In-place bitwise XOR (symmetric difference) operation. The current bitmap is modified.

Parameters:

x2 - other bitmap