org.roaringbitmap.buffer

Class ImmutableRoaringBitmap

java.lang.Object

org.roaringbitmap.buffer.ImmutableRoaringBitmap

All Implemented Interfaces:

Cloneable, Iterable<Integer>

Direct Known Subclasses:

MutableRoaringBitmap

public class ImmutableRoaringBitmap
extends Object
implements Iterable<Integer>, Cloneable

ImmutableRoaringBitmap provides a compressed immutable (cannot be modified) bitmap. It is meant to be used with org.roaringbitmap.buffer.MutableRoaringBitmap.

 
       import org.roaringbitmap.buffer.*;
       
       //...
       
       MutableRoaringBitmap rr1 = MutableRoaringBitmap.bitmapOf(1, 2, 3, 1000);
       MutableRoaringBitmap rr2 = MutableRoaringBitmap.bitmapOf( 2, 3, 1010);
       ByteArrayOutputStream bos = new ByteArrayOutputStream();
       DataOutputStream dos = new DataOutputStream(bos);
       rr1.serialize(dos);
       rr2.serialize(dos);
       dos.close();
       ByteBuffer bb = ByteBuffer.wrap(bos.toByteArray());
       ImmutableRoaringBitmap rrback1 = new ImmutableRoaringBitmap(bb);
       bb.position(bb.position() + rrback1.serializedSizeInBytes());
       ImmutableRoaringBitmap rrback2 = new ImmutableRoaringBitmap(bb);
 
 

It can also be constructed from a ByteBuffer (useful for memory mapping). Objects of this class may reside almost entirely in memory-map files.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	ImmutableRoaringBitmap()
	ImmutableRoaringBitmap(ByteBuffer b) Constructs a new ImmutableRoaringBitmap.

Method Summary

Modifier and Type	Method and Description
static MutableRoaringBitmap	and(ImmutableRoaringBitmap x1, ImmutableRoaringBitmap x2) Bitwise AND (intersection) operation.
static MutableRoaringBitmap	andNot(ImmutableRoaringBitmap x1, ImmutableRoaringBitmap x2) Bitwise ANDNOT (difference) operation.
ImmutableRoaringBitmap	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).
boolean	equals(Object o)
static MutableRoaringBitmap	flip(ImmutableRoaringBitmap 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()
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.
MutableRoaringBitmap	limit(int maxcardinality) Create a new Roaring bitmap containing at most maxcardinality integers.
static MutableRoaringBitmap	or(ImmutableRoaringBitmap x1, ImmutableRoaringBitmap 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()).
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 for serialization.
int[]	toArray() Return the set values as an array.
MutableRoaringBitmap	toMutableRoaringBitmap() Copies the content of this bitmap to a bitmap that can be modified.
String	toString() A string describing the bitmap.
static MutableRoaringBitmap	xor(ImmutableRoaringBitmap x1, ImmutableRoaringBitmap 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

ImmutableRoaringBitmap

protected ImmutableRoaringBitmap()

ImmutableRoaringBitmap

public ImmutableRoaringBitmap(ByteBuffer b)

Constructs a new ImmutableRoaringBitmap. Only meta-data is loaded to RAM. The rest is mapped to the ByteBuffer. It is not necessary that limit() on the input ByteBuffer indicates the end of the serialized data. After creating this ImmutableRoaringBitmap, you can advance to the rest of the data (if there is more) by setting b.position(b.position() + bitmap.serializedSizeInBytes()); Note that the input ByteBuffer is effectively copied (with the slice operation) so you should expect the provided ByteBuffer to remain unchanged.

Parameters:

b - data source

Method Detail

and

public static MutableRoaringBitmap and(ImmutableRoaringBitmap x1,
                                       ImmutableRoaringBitmap 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:

BufferFastAggregation.and(ImmutableRoaringBitmap...)

andNot

public static MutableRoaringBitmap andNot(ImmutableRoaringBitmap x1,
                                          ImmutableRoaringBitmap 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

flip

public static MutableRoaringBitmap flip(ImmutableRoaringBitmap 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 MutableRoaringBitmap or(ImmutableRoaringBitmap x1,
                                      ImmutableRoaringBitmap 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:

BufferFastAggregation.or(ImmutableRoaringBitmap...), BufferFastAggregation.horizontal_or(ImmutableRoaringBitmap...)

xor

public static MutableRoaringBitmap xor(ImmutableRoaringBitmap x1,
                                       ImmutableRoaringBitmap 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:

BufferFastAggregation.xor(ImmutableRoaringBitmap...), BufferFastAggregation.horizontal_xor(ImmutableRoaringBitmap...)

clone

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

Parameters:

x - integer value

Returns:

whether the integer value is included.

equals

public boolean equals(Object o)

Overrides:

equals in class Object

getCardinality

public int getCardinality()

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

Returns:

the cardinality

isEmpty

public boolean isEmpty()

Checks whether the bitmap is empty.

Returns:

true if this bitmap contains no set bit

getIntIterator

public IntIterator getIntIterator()

Returns:

a custom iterator over set bits, the bits are traversed in 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. If exact measures are needed, we recommend using dedicated libraries such as SizeOf. When the bitmap is constructed from a ByteBuffer from a memory-mapped file, this estimate is invalid: we can expect the actual memory usage to be significantly (e.g., 10x) less.

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

serialize

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

serializedSizeInBytes

public int serializedSizeInBytes()

Report the number of bytes required for serialization. This count will match the bytes written when calling the serialize method.

Returns:

the size in bytes

toArray

public int[] toArray()

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

Returns:

array representing the set values.

toMutableRoaringBitmap

public MutableRoaringBitmap toMutableRoaringBitmap()

Copies the content of this bitmap to a bitmap that can be modified.

Returns:

a mutable bitmap.

toString

public String toString()

A string describing the bitmap.

Overrides:

toString in class Object

Returns:

the string

rank

public int rank(int x)

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

Parameters:

x - upper limit

Returns:

the rank

select

public int select(int j)

Return the jth value stored in this bitmap.

Parameters:

j - index of the value

Returns:

the value

limit

public MutableRoaringBitmap limit(int maxcardinality)

Create a new Roaring bitmap containing at most maxcardinality integers.

Parameters:

maxcardinality - maximal cardinality

Returns:

a new bitmap with cardinality no more than maxcardinality