org.roaringbitmap.buffer

Class ImmutableRoaringBitmap

java.lang.Object

org.roaringbitmap.buffer.ImmutableRoaringBitmap

All Implemented Interfaces:

Cloneable, Iterable<Integer>, ImmutableBitmapDataProvider

Direct Known Subclasses:

MutableRoaringBitmap

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

ImmutableRoaringBitmap provides a compressed immutable (cannot be modified) bitmap. It is meant to be used with org.roaringbitmap.buffer.MutableRoaringBitmap, a derived class that adds methods to modify the bitmap.

 
       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);
       // could call "rr1.runOptimize()" and "rr2.runOptimize" if there 
       // there were runs to compress
       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.

See Also:

MutableRoaringBitmap

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	ImmutableRoaringBitmap()
	ImmutableRoaringBitmap(ByteBuffer b) Constructs a new ImmutableRoaringBitmap starting at this ByteBuffer's position().

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()
IntIterator	getReverseIntIterator()
int	getSizeInBytes() Estimate of the memory usage of this data structure.
int	hashCode()
boolean	hasRunCompression() Check whether this bitmap has had its runs compressed.
static boolean	intersects(ImmutableRoaringBitmap x1, ImmutableRoaringBitmap x2) Checks whether the two bitmaps intersect.
boolean	isEmpty() Checks whether the bitmap is empty.
Iterator<Integer>	iterator() iterate over the positions of the true values.
protected static MutableRoaringBitmap	lazyor(ImmutableRoaringBitmap x1, ImmutableRoaringBitmap x2)
MutableRoaringBitmap	limit(int maxcardinality) Create a new Roaring bitmap containing at most maxcardinality integers.
static MutableRoaringBitmap	or(ImmutableRoaringBitmap... bitmaps) Compute overall OR between bitmaps.
static MutableRoaringBitmap	or(ImmutableRoaringBitmap x1, ImmutableRoaringBitmap x2) Bitwise OR (union) operation.
static MutableRoaringBitmap	or(Iterator bitmaps) Compute overall AND between bitmaps.
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 starting at this ByteBuffer's position(). 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...)

lazyor

protected static MutableRoaringBitmap lazyor(ImmutableRoaringBitmap x1,
                                             ImmutableRoaringBitmap x2)

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

Specified by:

contains in interface ImmutableBitmapDataProvider

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

Specified by:

getCardinality in interface ImmutableBitmapDataProvider

Returns:

the cardinality

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

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

Specified by:

getSizeInBytes in interface ImmutableBitmapDataProvider

Returns:

estimated memory usage.

hashCode

public int hashCode()

Overrides:

hashCode in class Object

or

public static MutableRoaringBitmap or(ImmutableRoaringBitmap... bitmaps)

Compute overall OR between bitmaps. (Effectively calls BufferFastAggregation.or(org.roaringbitmap.buffer.MutableRoaringBitmap...))

Parameters:

bitmaps - input bitmaps

Returns:

aggregated bitmap

or

public static MutableRoaringBitmap or(Iterator bitmaps)

Compute overall AND between bitmaps. (Effectively calls BufferFastAggregation.or(org.roaringbitmap.buffer.MutableRoaringBitmap...))

Parameters:

bitmaps - input bitmaps

Returns:

aggregated bitmap

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. Consider calling MutableRoaringBitmap.runOptimize() before serialization to improve compression if this is a MutableRoaringBitmap instance. The current bitmap is not modified. Advanced example: To serialize your bitmap to a ByteBuffer, you can do the following.

 
   //r is your bitmap

   // r.runOptimize(); // might improve compression, only if you have a 
                       // MutableRoaringBitmap instance.
   // next we create the ByteBuffer where the data will be stored
   ByteBuffer outbb = ByteBuffer.allocate(r.serializedSizeInBytes());
   // then we can serialize on a custom OutputStream
   mrb.serialize(new DataOutputStream(new OutputStream(){
       ByteBuffer mBB;
       OutputStream init(ByteBuffer mbb) {mBB=mbb; return this;}
       public void close() {}
       public void flush() {}
       public void write(int b) {
         mBB.put((byte) b);}
       public void write(byte[] b) {mBB.put(b);}
       public void write(byte[] b, int off, int l) {mBB.put(b,off,l);}
   }.init(outbb)));
   // outbuff will now contain a serialized version of your bitmap
 
 

Note: Java's data structures are in big endian format. Roaring serializes to a little endian format, so the bytes are flipped by the library during serialization to ensure that what is stored is in little endian---despite Java's big endianness. You can defeat this process by reflipping the bytes again in a custom DataOutput which could lead to serialized Roaring objects with an incorrect byte order.

Specified by:

serialize in interface ImmutableBitmapDataProvider

Parameters:

out - the DataOutput stream

Throws:

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

hasRunCompression

public boolean hasRunCompression()

Check whether this bitmap has had its runs compressed.

Returns:

whether this bitmap has run compression

intersects

public static boolean intersects(ImmutableRoaringBitmap x1,
                                 ImmutableRoaringBitmap x2)

Checks whether the two bitmaps intersect. This can be much faster than calling "and" and checking the cardinality of the result.

Parameters:

x1 - first bitmap

x2 - other bitmap

Returns:

true if they intersect

serializedSizeInBytes

public int serializedSizeInBytes()

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

Specified by:

serializedSizeInBytes in interface ImmutableBitmapDataProvider

Returns:

the size in bytes

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.

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

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

limit

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