org.roaringbitmap.buffer

Class MutableRoaringBitmap

java.lang.Object

org.roaringbitmap.buffer.ImmutableRoaringBitmap

org.roaringbitmap.buffer.MutableRoaringBitmap

All Implemented Interfaces:

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

public class MutableRoaringBitmap
extends ImmutableRoaringBitmap
implements Cloneable, Serializable, Iterable<Integer>, Externalizable, BitmapDataProvider

MutableRoaringBitmap, a compressed alternative to the BitSet. It is similar to org.roaringbitmap.RoaringBitmap, but it differs in that it can interact with ImmutableRoaringBitmap objects. A MutableRoaringBitmap is an instance of an ImmutableRoaringBitmap (where methods like "serialize" are implemented). That is, they both share the same core (immutable) methods, but a MutableRoaringBitmap adds methods that allow you to modify the object. This design allows us to use MutableRoaringBitmap as ImmutableRoaringBitmap instances when needed. A MutableRoaringBitmap can be used much like an org.roaringbitmap.RoaringBitmap instance, and they serialize to the same output. The RoaringBitmap instance will be faster since it does not carry the overhead of a ByteBuffer back-end, but the MutableRoaringBitmap can be used as an ImmutableRoaringBitmap instance. Thus, if you use ImmutableRoaringBitmap, you probably need to use MutableRoaringBitmap instances as well; if you do not use ImmutableRoaringBitmap, you probably want to use only RoaringBitmap instances.

 
      import org.roaringbitmap.buffer.*;
       
      //...
      
      MutableRoaringBitmap rr = MutableRoaringBitmap.bitmapOf(1,2,3,1000);
      MutableRoaringBitmap rr2 = new MutableRoaringBitmap();
      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);
 
 

See Also:

ImmutableRoaringBitmap, RoaringBitmap, Serialized Form

Constructor Summary

Constructors

Constructor and Description
MutableRoaringBitmap() Create an empty bitmap
MutableRoaringBitmap(RoaringBitmap rb) Create a MutableRoaringBitmap from a RoaringBitmap.

Method Summary

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 MutableRoaringBitmap	add(MutableRoaringBitmap rb, int rangeStart, int rangeEnd) Generate a new bitmap with all integers in [rangeStart,rangeEnd) added.
void	and(ImmutableRoaringBitmap array) In-place bitwise AND (intersection) operation.
static MutableRoaringBitmap	and(MutableRoaringBitmap x1, MutableRoaringBitmap x2) Bitwise AND (intersection) operation.
void	andNot(ImmutableRoaringBitmap x2) In-place bitwise ANDNOT (difference) operation.
static MutableRoaringBitmap	andNot(MutableRoaringBitmap x1, MutableRoaringBitmap x2) Bitwise ANDNOT (difference) operation.
static MutableRoaringBitmap	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.
MutableRoaringBitmap	clone()
void	deserialize(DataInput in) Deserialize the bitmap (retrieve from the input stream).
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 MutableRoaringBitmap	flip(MutableRoaringBitmap bm, int rangeStart, int rangeEnd) Complements the bits in the given range, from rangeStart (inclusive) rangeEnd (exclusive).
MutableRoaringArray	getMappeableRoaringArray()
int	hashCode()
Iterator<Integer>	iterator() iterate over the positions of the true values.
protected void	lazyor(ImmutableRoaringBitmap x2)
protected static MutableRoaringBitmap	lazyorfromlazyinputs(MutableRoaringBitmap x1, MutableRoaringBitmap x2)
static MutableRoaringBitmap	or(ImmutableRoaringBitmap... bitmaps) Compute overall OR between bitmaps.
void	or(ImmutableRoaringBitmap x2) In-place bitwise OR (union) operation.
static MutableRoaringBitmap	or(MutableRoaringBitmap x1, MutableRoaringBitmap x2) Bitwise OR (union) operation.
void	readExternal(ObjectInput in)
void	remove(int x) If present remove the specified integers (effectively, sets its bit value to false)
void	remove(int rangeStart, int rangeEnd) Remove from the current bitmap all integers in [rangeStart,rangeEnd).
static MutableRoaringBitmap	remove(MutableRoaringBitmap 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 estimated as more space efficient
String	toString() A string describing the bitmap.
void	trim() Recover allocated but unused memory.
void	writeExternal(ObjectOutput out)
void	xor(ImmutableRoaringBitmap x2) In-place bitwise XOR (symmetric difference) operation.
static MutableRoaringBitmap	xor(MutableRoaringBitmap x1, MutableRoaringBitmap x2) Bitwise XOR (symmetric difference) operation.

Methods inherited from class org.roaringbitmap.buffer.ImmutableRoaringBitmap

and, andCardinality, andNot, contains, equals, flip, getCardinality, getContainerPointer, getIntIterator, getReverseIntIterator, getSizeInBytes, hasRunCompression, intersects, isEmpty, lazyor, limit, or, or, orCardinality, rank, select, serialize, serializedSizeInBytes, toArray, toMutableRoaringBitmap, toRoaringBitmap, xor

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Methods inherited from interface org.roaringbitmap.BitmapDataProvider

select

Methods inherited from interface org.roaringbitmap.ImmutableBitmapDataProvider

contains, getCardinality, getIntIterator, getReverseIntIterator, getSizeInBytes, isEmpty, limit, rank, serialize, serializedSizeInBytes, toArray

Constructor Detail

MutableRoaringBitmap

public MutableRoaringBitmap()

Create an empty bitmap

MutableRoaringBitmap

public MutableRoaringBitmap(RoaringBitmap rb)

Create a MutableRoaringBitmap from a RoaringBitmap. The RoaringBitmap is not modified.

Parameters:

rb - the original bitmap

Method Detail

and

public static MutableRoaringBitmap and(MutableRoaringBitmap x1,
                                       MutableRoaringBitmap x2)

Bitwise AND (intersection) 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

andNot

public static MutableRoaringBitmap andNot(MutableRoaringBitmap x1,
                                          MutableRoaringBitmap 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 MutableRoaringBitmap 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 MutableRoaringBitmap flip(MutableRoaringBitmap 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(MutableRoaringBitmap x1,
                                      MutableRoaringBitmap x2)

Bitwise OR (union) 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

xor

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

Parameters:

x1 - first bitmap

x2 - other bitmap

Returns:

result of the operation

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.

Specified by:

add in interface BitmapDataProvider

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 MutableRoaringBitmap add(MutableRoaringBitmap 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 MutableRoaringBitmap remove(MutableRoaringBitmap 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(ImmutableRoaringBitmap array)

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

Parameters:

array - other bitmap

andNot

public void andNot(ImmutableRoaringBitmap 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 MutableRoaringBitmap clone()

Overrides:

clone in class ImmutableRoaringBitmap

deserialize

public void deserialize(DataInput in)
                 throws IOException

Deserialize the bitmap (retrieve from the input stream). The current bitmap is overwritten.

Parameters:

in - the DataInput stream

Throws:

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

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

getMappeableRoaringArray

public MutableRoaringArray getMappeableRoaringArray()

Returns:

a mutable copy of this bitmap

hashCode

public int hashCode()

Overrides:

hashCode in class ImmutableRoaringBitmap

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

iterator

public Iterator<Integer> iterator()

iterate over the positions of the true values.

Specified by:

iterator in interface Iterable<Integer>

Overrides:

iterator in class ImmutableRoaringBitmap

Returns:

the iterator

or

public void or(ImmutableRoaringBitmap x2)

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

Parameters:

x2 - other bitmap

repairAfterLazy

protected void repairAfterLazy()

lazyorfromlazyinputs

protected static MutableRoaringBitmap lazyorfromlazyinputs(MutableRoaringBitmap x1,
                                                           MutableRoaringBitmap x2)

lazyor

protected void lazyor(ImmutableRoaringBitmap 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 integers (effectively, sets its bit value to false)

Specified by:

remove in interface BitmapDataProvider

Parameters:

x - integer value representing the index in a bitmap

toString

public String toString()

A string describing the bitmap.

Overrides:

toString in class ImmutableRoaringBitmap

Returns:

the string

trim

public void trim()

Recover allocated but unused memory.

Specified by:

trim in interface BitmapDataProvider

writeExternal

public void writeExternal(ObjectOutput out)
                   throws IOException

Specified by:

writeExternal in interface Externalizable

Throws:

IOException

runOptimize

public boolean runOptimize()

Use a run-length encoding where it is estimated as 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

xor

public void xor(ImmutableRoaringBitmap x2)

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

Parameters:

x2 - other bitmap