Module roaringbitmap
Package 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. Because the class ImmutableRoaringBitmap is not final and because there exists one derived class (org.roaringbitmap.buffer.MutableRoaringBitmap), then it is possible for the programmer to modify some ImmutableRoaringBitmap instances, but this invariably involves casting to other classes: if your code is written in terms of ImmutableRoaringBitmap instances, then your objects will be truly immutable, and thus easy to reason about. Pure (non-derived) instances of ImmutableRoaringBitmap have their data backed by a ByteBuffer. This has the benefit that they may be constructed from a ByteBuffer (useful for memory mapping). Objects of this class may reside almost entirely in memory-map files. That is the primary reason for them to be considered immutable, since no reallocation is possible when using memory-mapped files. From a language design point of view, instances of this class are immutable only when used as per the interface of the ImmutableRoaringBitmap class. Given that the class is not final, it is possible to modify instances, through other interfaces. Thus we do not take the term "immutable" in a purist manner, but rather in a practical one. One of our motivations for this design where MutableRoaringBitmap instances can be casted down to ImmutableRoaringBitmap instances is that bitmaps are often large, or used in a context where memory allocations are to be avoided, so we avoid forcing copies. Copies could be expected if one needs to mix and match ImmutableRoaringBitmap and MutableRoaringBitmap instances. 
 
       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 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);
See Also: