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) Deprecated. use the version where longs specify the range
void	add(long rangeStart, long rangeEnd) Add to the current bitmap all integers in [rangeStart,rangeEnd).
static MutableRoaringBitmap	add(MutableRoaringBitmap rb, int rangeStart, int rangeEnd) Deprecated. use the version where longs specify the range
static MutableRoaringBitmap	add(MutableRoaringBitmap rb, long rangeStart, long 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) Deprecated. use the version where longs specify the range
void	flip(long rangeStart, long rangeEnd) Modifies the current bitmap by complementing the bits in the given range, from rangeStart (inclusive) rangeEnd (exclusive).
static MutableRoaringBitmap	flip(MutableRoaringBitmap rb, int rangeStart, int rangeEnd) Deprecated. use the version where longs specify the range
static MutableRoaringBitmap	flip(MutableRoaringBitmap bm, long rangeStart, long 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 long	maximumSerializedSize(int cardinality, int universe_size) Assume that one wants to store "cardinality" integers in [0, universe_size), this function returns an upper bound on the serialized size in bytes.
protected void	naivelazyor(ImmutableRoaringBitmap 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.
protected static void	rangeSanityCheck(long rangeStart, long rangeEnd)
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) Deprecated. use the version where longs specify the range
void	remove(long rangeStart, long rangeEnd) Remove from the current bitmap all integers in [rangeStart,rangeEnd).
static MutableRoaringBitmap	remove(MutableRoaringBitmap rb, int rangeStart, int rangeEnd) Deprecated. use the version where longs specify the range
static MutableRoaringBitmap	remove(MutableRoaringBitmap rb, long rangeStart, long 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
ImmutableRoaringBitmap	toImmutableRoaringBitmap() Convenience method, effectively casts the object to an object of class ImmutableRoaringBitmap.
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, and, and, andCardinality, andNot, andNot, andNot, contains, equals, flip, flip, forEach, getCardinality, getContainerPointer, getIntIterator, getLongCardinality, getLongSizeInBytes, getReverseIntIterator, getSizeInBytes, hasRunCompression, intersects, isEmpty, lazyor, limit, or, or, or, or, orCardinality, rank, rankLong, select, serialize, serializedSizeInBytes, toArray, toMutableRoaringBitmap, toRoaringBitmap, toString, xor, xor, 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, forEach, getCardinality, getIntIterator, getLongCardinality, getLongSizeInBytes, getReverseIntIterator, getSizeInBytes, isEmpty, limit, rank, rankLong, 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

add

public static MutableRoaringBitmap add(MutableRoaringBitmap rb,
                                       long rangeStart,
                                       long 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

add

@Deprecated
public static MutableRoaringBitmap add(MutableRoaringBitmap rb,
                                                   int rangeStart,
                                                   int rangeEnd)

Deprecated. use the version where longs specify the range

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

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

rangeSanityCheck

protected static void rangeSanityCheck(long rangeStart,
                                       long rangeEnd)

flip

public static MutableRoaringBitmap flip(MutableRoaringBitmap bm,
                                        long rangeStart,
                                        long 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

flip

@Deprecated
public static MutableRoaringBitmap flip(MutableRoaringBitmap rb,
                                                    int rangeStart,
                                                    int rangeEnd)

Deprecated. use the version where longs specify the range

Complements the bits in the given range, from rangeStart (inclusive) rangeEnd (exclusive). The given bitmap is unchanged.

Parameters:

rb - bitmap being negated

rangeStart - inclusive beginning of range

rangeEnd - exclusive ending of range

Returns:

a new Bitmap

lazyorfromlazyinputs

protected static MutableRoaringBitmap lazyorfromlazyinputs(MutableRoaringBitmap x1,
                                                           MutableRoaringBitmap x2)

or

public static MutableRoaringBitmap or(ImmutableRoaringBitmap... bitmaps)

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

Parameters:

bitmaps - input bitmaps

Returns:

aggregated 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

remove

public static MutableRoaringBitmap remove(MutableRoaringBitmap rb,
                                          long rangeStart,
                                          long 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

remove

@Deprecated
public static MutableRoaringBitmap remove(MutableRoaringBitmap rb,
                                                      int rangeStart,
                                                      int rangeEnd)

Deprecated. use the version where longs specify the range

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

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

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

add

public void add(long rangeStart,
                long rangeEnd)

Add to the current bitmap all integers in [rangeStart,rangeEnd).

Parameters:

rangeStart - inclusive beginning of range

rangeEnd - exclusive ending of range

add

@Deprecated
public void add(int rangeStart,
                            int rangeEnd)

Deprecated. use the version where longs specify the range

Add to the current bitmap all integers in [rangeStart,rangeEnd).

Parameters:

rangeStart - inclusive beginning of range

rangeEnd - exclusive ending of range

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

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.

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

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

Add the value if it is not already present, otherwise remove it.

Parameters:

x - integer value

flip

public void flip(long rangeStart,
                 long 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

flip

@Deprecated
public void flip(int rangeStart,
                             int rangeEnd)

Deprecated. use the version where longs specify the range

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

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

lazyor

protected void lazyor(ImmutableRoaringBitmap x2)

naivelazyor

protected void naivelazyor(ImmutableRoaringBitmap x2)

or

public void or(ImmutableRoaringBitmap x2)

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

Parameters:

x2 - other bitmap

readExternal

public void readExternal(ObjectInput in)
                  throws IOException,
                         ClassNotFoundException

Specified by:

readExternal in interface Externalizable

Throws:

IOException

ClassNotFoundException

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

remove

public void remove(long rangeStart,
                   long rangeEnd)

Remove from the current bitmap all integers in [rangeStart,rangeEnd).

Parameters:

rangeStart - inclusive beginning of range

rangeEnd - exclusive ending of range

remove

@Deprecated
public void remove(int rangeStart,
                               int rangeEnd)

Deprecated. use the version where longs specify the range

Remove from the current bitmap all integers in [rangeStart,rangeEnd).

Parameters:

rangeStart - inclusive beginning of range

rangeEnd - exclusive ending of range

removeRunCompression

public boolean removeRunCompression()

Remove run-length encoding even when it is more space efficient

Returns:

whether a change was applied

repairAfterLazy

protected void repairAfterLazy()

runOptimize

public boolean runOptimize()

Use a run-length encoding where it is estimated as more space efficient

Returns:

whether a change was applied

toImmutableRoaringBitmap

public ImmutableRoaringBitmap toImmutableRoaringBitmap()

Convenience method, effectively casts the object to an object of class ImmutableRoaringBitmap. This function is equivalent to :

 
       (ImmutableRoaringBitmap) bitmap
 
 

Returns:

a cast of this object

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

xor

public void xor(ImmutableRoaringBitmap x2)

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

Parameters:

x2 - other bitmap

maximumSerializedSize

public static long maximumSerializedSize(int cardinality,
                                         int universe_size)

Assume that one wants to store "cardinality" integers in [0, universe_size), this function returns an upper bound on the serialized size in bytes. This function is identical to RoaringBitmap.maximumSerializedSize.

Parameters:

cardinality - maximal cardinality

universe_size - maximal value

Returns:

upper bound on the serialized size in bytes of the bitmap