Package org.roaringbitmap.buffer
Class MutableRoaringBitmap
java.lang.Object
org.roaringbitmap.buffer.ImmutableRoaringBitmap
org.roaringbitmap.buffer.MutableRoaringBitmap
- All Implemented Interfaces:
Externalizable
,Serializable
,Cloneable
,Iterable<Integer>
,AppendableStorage<MappeableContainer>
,BitmapDataProvider
,ImmutableBitmapDataProvider
public class MutableRoaringBitmap
extends ImmutableRoaringBitmap
implements Cloneable, Serializable, Iterable<Integer>, Externalizable, BitmapDataProvider, AppendableStorage<MappeableContainer>
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 in the sense that MutableRoaringBitmap is
derived from MutableRoaringBitmap.
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.
MutableRoaringBitmap instances can be casted to an ImmutableRoaringBitmap instance
in constant time which means that code written for ImmutableRoaringBitmap instances
run at full speed (without copies) on MutableRoaringBitmap
instances.
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);
Integers are added in unsigned sorted order. That is, they
are treated as unsigned integers (see
Java 8's Integer.toUnsignedLong function). Up to 4294967296 integers
can be stored.-
Nested Class Summary
Nested classes/interfaces inherited from interface org.roaringbitmap.ImmutableBitmapDataProvider
ImmutableBitmapDataProvider.RoaringOfInt
-
Constructor Summary
ConstructorDescriptionCreate an empty bitmapMutableRoaringBitmap
(MutableRoaringArray highLowContainer) Create a MutableRoaringBitmap from a RoaringBitmap. -
Method Summary
Modifier and TypeMethodDescriptionvoid
add
(int x) Add the value to the container (set the value to "true"), whether it already appears or not.void
add
(int... dat) Set all the specified values to true.void
add
(int rangeStart, int rangeEnd) Deprecated.use the version where longs specify the rangevoid
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 rangestatic MutableRoaringBitmap
add
(MutableRoaringBitmap rb, long rangeStart, long rangeEnd) Generate a new bitmap with all integers in [rangeStart,rangeEnd) added.void
addN
(int[] dat, int offset, int n) Set the specified values to true, within given boundaries.static MutableRoaringBitmap
addOffset
(ImmutableRoaringBitmap x, long offset) Generate a copy of the provided bitmap, but with all its values incremented by offset.void
and
(ImmutableRoaringBitmap array) In-place bitwise AND (intersection) operation.static MutableRoaringBitmap
Bitwise AND (intersection) operation.void
In-place bitwise ANDNOT (difference) operation.static MutableRoaringBitmap
Bitwise ANDNOT (difference) operation.void
append
(char key, MappeableContainer container) Appends the key and container to the storage, throws if the key is less than the current mark.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.clone()
void
deserialize
(DataInput in) Deserialize the bitmap (retrieve from the input stream).void
deserialize
(ByteBuffer buffer) Deserialize (retrieve) this bitmap.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 rangevoid
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 rangestatic MutableRoaringBitmap
flip
(MutableRoaringBitmap bm, long rangeStart, long rangeEnd) Complements the bits in the given range, from rangeStart (inclusive) rangeEnd (exclusive).iterator()
iterate over the positions of the true values.protected void
protected static MutableRoaringBitmap
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
void
In-place bitwise OR (union) operation.static MutableRoaringBitmap
or
(ImmutableRoaringBitmap... bitmaps) Compute overall OR between bitmaps.static MutableRoaringBitmap
Bitwise OR (union) operation.void
orNot
(ImmutableRoaringBitmap other, long rangeEnd) In-place bitwise ORNOT operation.protected static void
rangeSanityCheck
(long rangeStart, long rangeEnd) void
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 rangevoid
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 rangestatic MutableRoaringBitmap
remove
(MutableRoaringBitmap rb, long rangeStart, long rangeEnd) Generate a new bitmap with all integers in [rangeStart,rangeEnd) removed.boolean
Remove run-length encoding even when it is more space efficientprotected void
boolean
Use a run-length encoding where it is estimated as more space efficientConvenience method, effectively casts the object to an object of class ImmutableRoaringBitmap.void
trim()
Recover allocated but unused memory.void
void
In-place bitwise XOR (symmetric difference) operation.static MutableRoaringBitmap
Bitwise XOR (symmetric difference) operation.Methods inherited from class org.roaringbitmap.buffer.ImmutableRoaringBitmap
and, and, and, andCardinality, andNot, andNot, andNot, andNotCardinality, cardinalityExceeds, contains, contains, contains, equals, first, flip, flip, forEach, getBatchIterator, getCardinality, getContainerPointer, getIntIterator, getLongCardinality, getLongSizeInBytes, getReverseIntIterator, getSizeInBytes, hashCode, hasRunCompression, intersects, intersects, isEmpty, isHammingSimilar, last, lazyor, limit, nextAbsentValue, nextValue, or, or, or, or, orCardinality, orNot, previousAbsentValue, previousValue, rangeCardinality, rank, rankLong, select, serialize, serialize, serializedSizeInBytes, toArray, toMutableRoaringBitmap, toRoaringBitmap, toString, xor, xor, xor, xorCardinality
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
Methods inherited from interface org.roaringbitmap.ImmutableBitmapDataProvider
contains, first, forEach, getBatchIterator, getCardinality, getIntIterator, getLongCardinality, getLongSizeInBytes, getReverseIntIterator, getSizeInBytes, isEmpty, last, limit, nextAbsentValue, nextValue, previousAbsentValue, previousValue, rangeCardinality, rank, rankLong, reverseStream, select, serialize, serialize, serializedSizeInBytes, stream, toArray
Methods inherited from interface java.lang.Iterable
forEach, spliterator
-
Constructor Details
-
MutableRoaringBitmap
public MutableRoaringBitmap()Create an empty bitmap -
MutableRoaringBitmap
-
MutableRoaringBitmap
Create a MutableRoaringBitmap from a RoaringBitmap. The RoaringBitmap is not modified.- Parameters:
rb
- the original bitmap
-
-
Method Details
-
addOffset
Generate a copy of the provided bitmap, but with all its values incremented by offset. The parameter offset can be negative. Values that would fall outside of the valid 32-bit range are discarded so that the result can have lower cardinality. This method can be relatively expensive when offset is not divisible by 65536. Use sparingly.- Parameters:
x
- source bitmapoffset
- increment (can be negative)- Returns:
- a new bitmap
-
add
Generate a new bitmap with all integers in [rangeStart,rangeEnd) added.- Parameters:
rb
- initial bitmap (will not be modified)rangeStart
- inclusive beginning of rangerangeEnd
- 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 rangeGenerate a new bitmap with all integers in [rangeStart,rangeEnd) added.- Parameters:
rb
- initial bitmap (will not be modified)rangeStart
- inclusive beginning of rangerangeEnd
- exclusive ending of range- Returns:
- new bitmap
-
and
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 bitmapx2
- other bitmap- Returns:
- result of the operation
-
andNot
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 bitmapx2
- other bitmap- Returns:
- result of the operation
-
add
public void add(int... dat) Set all the specified values to true. This can be expected to be slightly faster than calling "add" repeatedly. 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
-
addN
public void addN(int[] dat, int offset, int n) Set the specified values to true, within given boundaries. This can be expected to be slightly faster than calling "add" repeatedly on the values dat[offset], dat[offset+1],..., dat[offset+n-1]. 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 valuesoffset
- from which index the values should be set to truen
- how many values should be set to true
-
bitmapOf
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
Complements the bits in the given range, from rangeStart (inclusive) rangeEnd (exclusive). The given bitmap is unchanged.- Parameters:
bm
- bitmap being negatedrangeStart
- inclusive beginning of rangerangeEnd
- 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 rangeComplements the bits in the given range, from rangeStart (inclusive) rangeEnd (exclusive). The given bitmap is unchanged.- Parameters:
rb
- bitmap being negatedrangeStart
- inclusive beginning of rangerangeEnd
- exclusive ending of range- Returns:
- a new Bitmap
-
lazyorfromlazyinputs
protected static MutableRoaringBitmap lazyorfromlazyinputs(MutableRoaringBitmap x1, MutableRoaringBitmap x2) -
or
Compute overall OR between bitmaps. (Effectively callsBufferFastAggregation.or(org.roaringbitmap.buffer.ImmutableRoaringBitmap...)
)- Parameters:
bitmaps
- input bitmaps- Returns:
- aggregated bitmap
-
or
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 bitmapx2
- other bitmap- Returns:
- result of the operation
-
remove
Generate a new bitmap with all integers in [rangeStart,rangeEnd) removed.- Parameters:
rb
- initial bitmap (will not be modified)rangeStart
- inclusive beginning of rangerangeEnd
- 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 rangeGenerate a new bitmap with all integers in [rangeStart,rangeEnd) removed.- Parameters:
rb
- initial bitmap (will not be modified)rangeStart
- inclusive beginning of rangerangeEnd
- exclusive ending of range- Returns:
- new bitmap
-
xor
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 bitmapx2
- 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. Java lacks native unsigned integers but the x argument is considered to be unsigned. Within bitmaps, numbers are ordered according toInteger.compareUnsigned(int, int)
. We order the numbers like 0, 1, ..., 2147483647, -2147483648, -2147483647,..., -1.- Specified by:
add
in interfaceBitmapDataProvider
- Parameters:
x
- integer value
-
add
public void add(long rangeStart, long rangeEnd) Add to the current bitmap all integers in [rangeStart,rangeEnd).- Specified by:
add
in interfaceBitmapDataProvider
- Parameters:
rangeStart
- inclusive beginning of rangerangeEnd
- exclusive ending of range
-
add
Deprecated.use the version where longs specify the rangeAdd to the current bitmap all integers in [rangeStart,rangeEnd).- Parameters:
rangeStart
- inclusive beginning of rangerangeEnd
- exclusive ending of range
-
and
In-place bitwise AND (intersection) operation. The current bitmap is modified.- Parameters:
array
- other bitmap
-
andNot
In-place bitwise ANDNOT (difference) operation. The current bitmap is modified.- Parameters:
x2
- other bitmap
-
orNot
In-place bitwise ORNOT operation. The current bitmap is modified.- Parameters:
other
- the other bitmaprangeEnd
- end point of the range (exclusive).
-
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
- Overrides:
clone
in classImmutableRoaringBitmap
-
deserialize
Deserialize the bitmap (retrieve from the input stream). The current bitmap is overwritten. See format specification at https://github.com/RoaringBitmap/RoaringFormatSpec- Parameters:
in
- the DataInput stream- Throws:
IOException
- Signals that an I/O exception has occurred.
-
deserialize
Deserialize (retrieve) this bitmap. See format specification at https://github.com/RoaringBitmap/RoaringFormatSpec The current bitmap is overwritten. It is not necessary that limit() on the input ByteBuffer indicates the end of the serialized data. After loading this RoaringBitmap, you can advance to the rest of the data (if there is more) by setting bbf.position(bbf.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:
buffer
- the byte buffer (can be mapped, direct, array backed etc.- 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 rangerangeEnd
- exclusive ending of range
-
flip
Deprecated.use the version where longs specify the rangeModifies the current bitmap by complementing the bits in the given range, from rangeStart (inclusive) rangeEnd (exclusive).- Parameters:
rangeStart
- inclusive beginning of rangerangeEnd
- exclusive ending of range
-
getMappeableRoaringArray
- Returns:
- a mutable copy of this bitmap
-
iterator
iterate over the positions of the true values.- Specified by:
iterator
in interfaceIterable<Integer>
- Overrides:
iterator
in classImmutableRoaringBitmap
- Returns:
- the iterator
-
lazyor
-
naivelazyor
-
or
In-place bitwise OR (union) operation. The current bitmap is modified.- Parameters:
x2
- other bitmap
-
readExternal
- Specified by:
readExternal
in interfaceExternalizable
- 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 interfaceBitmapDataProvider
- 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 rangerangeEnd
- exclusive ending of range
-
remove
Deprecated.use the version where longs specify the rangeRemove from the current bitmap all integers in [rangeStart,rangeEnd).- Parameters:
rangeStart
- inclusive beginning of rangerangeEnd
- 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
Convenience method, effectively casts the object to an object of class ImmutableRoaringBitmap. This function is equivalent to :(ImmutableRoaringBitmap) bitmap
///////////// // Code to create a hard copy of MutableRoaringBitmap to an // ImmutableRoaringBitmap. // Usage of this code is discouraged because it is expensive // and it creates a copy that // suffers from more performance overhead than the original. ///////////// import org.roaringbitmap.buffer.*; //... MutableRoaringBitmap rr = ... // some bitmap rr.runOptimize(); // can help compression // we are going to create an immutable copy of rr ByteBuffer outbb = ByteBuffer.allocate(mrb.serializedSizeInBytes()); mrb.serialize(outbb); outbb.flip(); ImmutableRoaringBitmap irb = new ImmutableRoaringBitmap(outbb);
- Returns:
- a cast of this object
-
trim
public void trim()Recover allocated but unused memory.- Specified by:
trim
in interfaceBitmapDataProvider
-
writeExternal
- Specified by:
writeExternal
in interfaceExternalizable
- Throws:
IOException
-
xor
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 cardinalityuniverse_size
- maximal value- Returns:
- upper bound on the serialized size in bytes of the bitmap
-
append
Description copied from interface:AppendableStorage
Appends the key and container to the storage, throws if the key is less than the current mark.- Specified by:
append
in interfaceAppendableStorage<MappeableContainer>
- Parameters:
key
- the key to appendcontainer
- the data to append
-