RoaringBitmap (RoaringBitmap 0.5.11 API)

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);
      
      //...
      DataOutputStream wheretoserialize = ...
      rr.runOptimize(); // can help compression 
      rr.serialize(wheretoserialize);

Integers are added in unsigned sorted order. That is, they are treated as unsigned integers (see Java 8's Integer.toUnsignedLong function). Bitmaps are limited to a maximum of Integer.MAX_VALUE entries. Trying to create larger bitmaps could result in undefined behaviors.

See Also:: Serialized Form

Constructor Summary

Constructors
Constructor and Description

RoaringBitmap()
Create an empty bitmap

Constructors
Constructor and Description
`RoaringBitmap()` Create an empty bitmap

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and 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 rangeStart, int rangeEnd)` Add to the current bitmap all integers in [rangeStart,rangeEnd).
`static RoaringBitmap`	`add(RoaringBitmap rb, int rangeStart, int rangeEnd)` Generate a new bitmap with all integers in [rangeStart,rangeEnd) added.
`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.
`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.
`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 x)` Add the value if it is not already present, otherwise remove it.
`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`	`hasRunCompression()` Check whether this bitmap has had its runs compressed.
`static boolean`	`intersects(RoaringBitmap x1, RoaringBitmap 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 void`	`lazyor(RoaringBitmap x2)`
`protected static RoaringBitmap`	`lazyor(RoaringBitmap x1, RoaringBitmap x2)`
`protected static RoaringBitmap`	`lazyorfromlazyinputs(RoaringBitmap x1, RoaringBitmap x2)`
`RoaringBitmap`	`limit(int maxcardinality)` Create a new Roaring bitmap containing at most maxcardinality integers.
`static RoaringBitmap`	`or(Iterator<RoaringBitmap> bitmaps)` Compute overall AND between bitmaps.
`static RoaringBitmap`	`or(RoaringBitmap... bitmaps)` Compute overall OR between bitmaps.
`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 integer (effectively, sets its bit value to false)
`void`	`remove(int rangeStart, int rangeEnd)` Remove from the current bitmap all integers in [rangeStart,rangeEnd).
`static RoaringBitmap`	`remove(RoaringBitmap rb, int rangeStart, int rangeEnd)` Generate a new bitmap with all integers in [rangeStart,rangeEnd) removed.
`boolean`	`removeRunCompression()` Remove run-length encoding even when it is more space efficient
`protected void`	`repairAfterLazy()`
`boolean`	`runOptimize()` Use a run-length encoding where it is more space efficient
`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...)
  - lazyor
```
protected static RoaringBitmap lazyor(RoaringBitmap x1,
                                      RoaringBitmap x2)
```
  - lazyorfromlazyinputs
```
protected static RoaringBitmap lazyorfromlazyinputs(RoaringBitmap x1,
                                                    RoaringBitmap x2)
```
  - 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...)
  - checkedAdd
```
public boolean checkedAdd(int x)
```
    Add the value to the container (set the value to "true"), whether it already appears or not.
    
    Parameters:
    
    x - integer value
    
    Returns:
    
    true if the added int wasn't already contained in the bitmap. False otherwise.
  - add
```
public void add(int x)
```
    Add the value to the container (set the value to "true"), whether it already appears or not.
    
    Parameters:
    
    x - integer value
  - flip
```
public void flip(int x)
```
    Add the value if it is not already present, otherwise remove it.
    
    Parameters:
    
    x - integer value
  - add
```
public void add(int rangeStart,
                int rangeEnd)
```
    Add to the current bitmap all integers in [rangeStart,rangeEnd).
    
    Parameters:
    
    rangeStart - inclusive beginning of range
    
    rangeEnd - exclusive ending of range
  - add
```
public static RoaringBitmap add(RoaringBitmap rb,
                                int rangeStart,
                                int rangeEnd)
```
    Generate a new bitmap with all integers in [rangeStart,rangeEnd) added.
    
    Parameters:
    
    rb - initial bitmap (will not be modified)
    
    rangeStart - inclusive beginning of range
    
    rangeEnd - exclusive ending of range
    
    Returns:
    
    new bitmap
  - remove
```
public void remove(int rangeStart,
                   int rangeEnd)
```
    Remove from the current bitmap all integers in [rangeStart,rangeEnd).
    
    Parameters:
    
    rangeStart - inclusive beginning of range
    
    rangeEnd - exclusive ending of range
  - remove
```
public static RoaringBitmap remove(RoaringBitmap rb,
                                   int rangeStart,
                                   int rangeEnd)
```
    Generate a new bitmap with all integers in [rangeStart,rangeEnd) removed.
    
    Parameters:
    
    rb - initial bitmap (will not be modified)
    
    rangeStart - inclusive beginning of range
    
    rangeEnd - exclusive ending of range
    
    Returns:
    
    new bitmap
  - 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.
  - or
```
public static RoaringBitmap or(RoaringBitmap... bitmaps)
```
    Compute overall OR between bitmaps. (Effectively calls FastAggregation.or(org.roaringbitmap.RoaringBitmap...))
    
    Parameters:
    
    bitmaps - input bitmaps
    
    Returns:
    
    aggregated bitmap
  - or
```
public static RoaringBitmap or(Iterator<RoaringBitmap> bitmaps)
```
    Compute overall AND between bitmaps. (Effectively calls FastAggregation.or(org.roaringbitmap.RoaringBitmap...))
    
    Parameters:
    
    bitmaps - input bitmaps
    
    Returns:
    
    aggregated bitmap
  - 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
  - repairAfterLazy
```
protected void repairAfterLazy()
```
  - lazyor
```
protected void lazyor(RoaringBitmap x2)
```
  - readExternal
```
public void readExternal(ObjectInput in)
                  throws IOException,
                         ClassNotFoundException
```
    Specified by:
    
    readExternal in interface Externalizable
    
    Throws:
    
    IOException
    
    ClassNotFoundException
  - checkedRemove
```
public boolean checkedRemove(int x)
```
    If present remove the specified integer (effectively, sets its bit value to false)
    
    Parameters:
    
    x - integer value representing the index in a bitmap
    
    Returns:
    
    true if the unset bit was already in the bitmap
  - remove
```
public void remove(int x)
```
    If present remove the specified integer (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. Consider calling runOptimize() before serialization to improve compression. 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
   // 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.
  - 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.
  - runOptimize
```
public boolean runOptimize()
```
    Use a run-length encoding where it is more space efficient
    
    Returns:
    
    whether a change was applied
  - removeRunCompression
```
public boolean removeRunCompression()
```
    Remove run-length encoding even when it is more space efficient
    
    Returns:
    
    whether a change was applied
  - intersects
```
public static boolean intersects(RoaringBitmap x1,
                                 RoaringBitmap 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
  - hasRunCompression
```
public boolean hasRunCompression()
```
    Check whether this bitmap has had its runs compressed.
    
    Returns:
    
    whether this bitmap has run compression
  - 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

Class RoaringBitmap

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface java.lang.Iterable

Constructor Detail

RoaringBitmap

Method Detail

and

andNot

bitmapOf

flip

or

lazyor

lazyorfromlazyinputs

rank

select

xor

checkedAdd

add

flip

add

add

remove

remove

and

andNot

clear

clone

contains

deserialize

equals

flip

getCardinality

getIntIterator

getReverseIntIterator

getSizeInBytes

or

or

hashCode

iterator

isEmpty

or

repairAfterLazy

lazyor

readExternal

checkedRemove

remove

serialize

serializedSizeInBytes

limit

toArray

toString

trim

runOptimize

removeRunCompression

intersects

hasRunCompression

writeExternal

xor