public class RoaringBitmap extends Object implements Cloneable, Serializable, Iterable<Integer>, Externalizable, ImmutableBitmapDataProvider, BitmapDataProvider
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).
Up to 4294967296 integers
can be stored.Constructor and Description |
---|
RoaringBitmap()
Create an empty bitmap
|
RoaringBitmap(ImmutableRoaringBitmap rb)
Create a RoaringBitmap from a MutableRoaringBitmap or ImmutableRoaringBitmap.
|
Modifier and Type | Method and Description |
---|---|
void |
add(int... dat)
Set all the specified values to true.
|
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 RoaringBitmap |
add(RoaringBitmap rb,
int rangeStart,
int rangeEnd)
Deprecated.
use the version where longs specify the range
|
static RoaringBitmap |
add(RoaringBitmap rb,
long rangeStart,
long rangeEnd)
Generate a new bitmap with all integers in [rangeStart,rangeEnd) added.
|
static RoaringBitmap |
and(Iterator bitmaps,
int rangeStart,
int rangeEnd)
Deprecated.
use the version where longs specify the range. Negative range end are illegal.
|
static RoaringBitmap |
and(Iterator bitmaps,
long rangeStart,
long rangeEnd)
Computes AND between input bitmaps in the given range, from rangeStart (inclusive) to rangeEnd
(exclusive)
|
void |
and(RoaringBitmap x2)
In-place bitwise AND (intersection) operation.
|
static RoaringBitmap |
and(RoaringBitmap x1,
RoaringBitmap x2)
Bitwise AND (intersection) operation.
|
static int |
andCardinality(RoaringBitmap x1,
RoaringBitmap x2)
Cardinality of 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 |
andNot(RoaringBitmap x1,
RoaringBitmap x2,
int rangeStart,
int rangeEnd)
Deprecated.
use the version where longs specify the range. Negative values for range
endpoints are not allowed.
|
static RoaringBitmap |
andNot(RoaringBitmap x1,
RoaringBitmap x2,
long rangeStart,
long rangeEnd)
Bitwise ANDNOT (difference) operation for the given range, rangeStart (inclusive) and rangeEnd
(exclusive).
|
static int |
andNotCardinality(RoaringBitmap x1,
RoaringBitmap x2)
Cardinality of the bitwise ANDNOT (left difference) operation.
|
static RoaringBitmap |
bitmapOf(int... dat)
Generate a bitmap with the specified values set to true.
|
static RoaringBitmap |
bitmapOfUnordered(int... data)
Efficiently builds a RoaringBitmap from unordered data
|
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).
|
boolean |
contains(RoaringBitmap subset)
Checks whether the parameter is a subset of this RoaringBitmap or not
|
void |
deserialize(DataInput in)
Deserialize (retrieve) this bitmap.
|
boolean |
equals(Object o) |
int |
first()
Get the first (smallest) integer in this RoaringBitmap,
that is, returns the minimum of the set.
|
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 RoaringBitmap |
flip(RoaringBitmap rb,
int rangeStart,
int rangeEnd)
Deprecated.
use the version where longs specify the range
|
static RoaringBitmap |
flip(RoaringBitmap bm,
long rangeStart,
long rangeEnd)
Complements the bits in the given range, from rangeStart (inclusive) rangeEnd (exclusive).
|
void |
forEach(IntConsumer ic)
Visit all values in the bitmap and pass them to the consumer.
|
int |
getCardinality()
Returns the number of distinct integers added to the bitmap (e.g., number of bits set).
|
ContainerPointer |
getContainerPointer()
Return a low-level container pointer that can be used to access the underlying data structure.
|
PeekableIntIterator |
getIntIterator()
For better performance, consider the Use the
forEach method. |
long |
getLongCardinality()
Returns the number of distinct integers added to the bitmap (e.g., number of bits set).
|
long |
getLongSizeInBytes()
Estimate of the memory usage of this data structure.
|
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.
|
boolean |
isHammingSimilar(RoaringBitmap other,
int tolerance)
Returns true if the other bitmap has no more than tolerance bits
differing from this bitmap.
|
Iterator<Integer> |
iterator()
iterate over the positions of the true values.
|
int |
last()
Get the last (largest) integer in this RoaringBitmap,
that is, returns the maximum of the set.
|
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 long |
maximumSerializedSize(long cardinality,
long 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(RoaringBitmap x2) |
static RoaringBitmap |
or(Iterator<? extends RoaringBitmap> bitmaps)
Compute overall OR between bitmaps.
|
static RoaringBitmap |
or(Iterator bitmaps,
int rangeStart,
int rangeEnd)
Deprecated.
use the version where longs specify the range.
Negative range points are forbidden.
|
static RoaringBitmap |
or(Iterator bitmaps,
long rangeStart,
long rangeEnd)
Computes OR between input bitmaps in the given range, from rangeStart (inclusive) to rangeEnd
(exclusive)
|
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.
|
static int |
orCardinality(RoaringBitmap x1,
RoaringBitmap x2)
Cardinality of the 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()).
|
long |
rankLong(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)
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 RoaringBitmap |
remove(RoaringBitmap rb,
int rangeStart,
int rangeEnd)
Deprecated.
use the version where longs specify the range
|
static RoaringBitmap |
remove(RoaringBitmap 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 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, if the cardinality is smaller than 2147483648.
|
MutableRoaringBitmap |
toMutableRoaringBitmap()
Convert (copies) to a mutable roaring bitmap.
|
String |
toString()
A string describing the bitmap.
|
void |
trim()
Recover allocated but unused memory.
|
void |
writeExternal(ObjectOutput out) |
static RoaringBitmap |
xor(Iterator bitmaps,
int rangeStart,
int rangeEnd)
Deprecated.
use the version where longs specify the range.
Negative values not allowed for rangeStart and rangeEnd
|
static RoaringBitmap |
xor(Iterator bitmaps,
long rangeStart,
long rangeEnd)
Computes XOR between input bitmaps in the given range, from rangeStart (inclusive) to rangeEnd
(exclusive)
|
void |
xor(RoaringBitmap x2)
In-place bitwise XOR (symmetric difference) operation.
|
static RoaringBitmap |
xor(RoaringBitmap x1,
RoaringBitmap x2)
Bitwise XOR (symmetric difference) operation.
|
static int |
xorCardinality(RoaringBitmap x1,
RoaringBitmap x2)
Cardinality of the bitwise XOR (symmetric difference) operation.
|
finalize, getClass, notify, notifyAll, wait, wait, wait
forEach, spliterator
public RoaringBitmap()
public RoaringBitmap(ImmutableRoaringBitmap rb)
rb
- the original bitmappublic static RoaringBitmap add(RoaringBitmap rb, long rangeStart, long rangeEnd)
rb
- initial bitmap (will not be modified)rangeStart
- inclusive beginning of rangerangeEnd
- exclusive ending of range@Deprecated public static RoaringBitmap add(RoaringBitmap rb, int rangeStart, int rangeEnd)
rb
- initial bitmap (will not be modified)rangeStart
- inclusive beginning of rangerangeEnd
- exclusive ending of rangepublic static RoaringBitmap and(RoaringBitmap x1, RoaringBitmap x2)
x1
- first bitmapx2
- other bitmapFastAggregation.and(RoaringBitmap...)
public static int andCardinality(RoaringBitmap x1, RoaringBitmap x2)
x1
- first bitmapx2
- other bitmapFastAggregation.and(RoaringBitmap...)
public static RoaringBitmap andNot(RoaringBitmap x1, RoaringBitmap x2)
x1
- first bitmapx2
- other bitmappublic void add(int... dat)
dat
- set valuespublic static RoaringBitmap bitmapOf(int... dat)
dat
- set valuespublic static RoaringBitmap bitmapOfUnordered(int... data)
data
- unsorted datapublic static RoaringBitmap flip(RoaringBitmap bm, long rangeStart, long rangeEnd)
bm
- bitmap being negatedrangeStart
- inclusive beginning of range, in [0, 0xffffffff]rangeEnd
- exclusive ending of range, in [0, 0xffffffff + 1]@Deprecated public static RoaringBitmap flip(RoaringBitmap rb, int rangeStart, int rangeEnd)
rb
- bitmap being negatedrangeStart
- inclusive beginning of range, in [0, 0xffffffff]rangeEnd
- exclusive ending of range, in [0, 0xffffffff + 1]public static boolean intersects(RoaringBitmap x1, RoaringBitmap x2)
x1
- first bitmapx2
- other bitmapprotected static RoaringBitmap lazyor(RoaringBitmap x1, RoaringBitmap x2)
protected static RoaringBitmap lazyorfromlazyinputs(RoaringBitmap x1, RoaringBitmap x2)
public static RoaringBitmap or(Iterator<? extends RoaringBitmap> bitmaps)
FastAggregation.or(java.util.Iterator<? extends org.roaringbitmap.RoaringBitmap>)
)bitmaps
- input bitmapspublic static RoaringBitmap or(RoaringBitmap... bitmaps)
FastAggregation.or(java.util.Iterator<? extends org.roaringbitmap.RoaringBitmap>)
)bitmaps
- input bitmapspublic static RoaringBitmap or(RoaringBitmap x1, RoaringBitmap x2)
x1
- first bitmapx2
- other bitmapFastAggregation.or(RoaringBitmap...)
,
FastAggregation.horizontal_or(RoaringBitmap...)
public static int orCardinality(RoaringBitmap x1, RoaringBitmap x2)
x1
- first bitmapx2
- other bitmapFastAggregation.or(RoaringBitmap...)
,
FastAggregation.horizontal_or(RoaringBitmap...)
public static int xorCardinality(RoaringBitmap x1, RoaringBitmap x2)
x1
- first bitmapx2
- other bitmappublic static int andNotCardinality(RoaringBitmap x1, RoaringBitmap x2)
x1
- first bitmapx2
- other bitmappublic static RoaringBitmap remove(RoaringBitmap rb, long rangeStart, long rangeEnd)
rb
- initial bitmap (will not be modified)rangeStart
- inclusive beginning of rangerangeEnd
- exclusive ending of range@Deprecated public static RoaringBitmap remove(RoaringBitmap rb, int rangeStart, int rangeEnd)
rb
- initial bitmap (will not be modified)rangeStart
- inclusive beginning of rangerangeEnd
- exclusive ending of rangepublic static RoaringBitmap xor(RoaringBitmap x1, RoaringBitmap x2)
x1
- first bitmapx2
- other bitmapFastAggregation.xor(RoaringBitmap...)
,
FastAggregation.horizontal_xor(RoaringBitmap...)
public void add(int x)
Integer.compareUnsigned(int, int)
.
We order the numbers like 0, 1, ..., 2147483647, -2147483648, -2147483647,..., -1.add
in interface BitmapDataProvider
x
- integer valuepublic void add(long rangeStart, long rangeEnd)
rangeStart
- inclusive beginning of rangerangeEnd
- exclusive ending of range@Deprecated public void add(int rangeStart, int rangeEnd)
rangeStart
- inclusive beginning of rangerangeEnd
- exclusive ending of rangepublic void and(RoaringBitmap x2)
x2
- other bitmappublic static RoaringBitmap and(Iterator bitmaps, long rangeStart, long rangeEnd)
bitmaps
- input bitmaps, these are not modifiedrangeStart
- inclusive beginning of rangerangeEnd
- exclusive ending of range@Deprecated public static RoaringBitmap and(Iterator bitmaps, int rangeStart, int rangeEnd)
bitmaps
- input bitmaps, these are not modifiedrangeStart
- inclusive beginning of rangerangeEnd
- exclusive ending of rangepublic void andNot(RoaringBitmap x2)
x2
- other bitmappublic static RoaringBitmap andNot(RoaringBitmap x1, RoaringBitmap x2, long rangeStart, long rangeEnd)
x1
- first bitmapx2
- other bitmaprangeStart
- starting point of the range (inclusive)rangeEnd
- end point of the range (exclusive)@Deprecated public static RoaringBitmap andNot(RoaringBitmap x1, RoaringBitmap x2, int rangeStart, int rangeEnd)
x1
- first bitmapx2
- other bitmaprangeStart
- starting point of the range (inclusive)rangeEnd
- end point of the range (exclusive)public boolean checkedAdd(int x)
x
- integer valuepublic boolean checkedRemove(int x)
x
- integer value representing the index in a bitmappublic void clear()
public RoaringBitmap clone()
public boolean contains(int x)
contains
in interface ImmutableBitmapDataProvider
x
- integer valuepublic void deserialize(DataInput in) throws IOException
in
- the DataInput streamIOException
- Signals that an I/O exception has occurred.public boolean isHammingSimilar(RoaringBitmap other, int tolerance)
other
- the bitmap to compare totolerance
- the maximum number of bits that may differpublic void flip(int x)
x
- integer valuepublic void flip(long rangeStart, long rangeEnd)
rangeStart
- inclusive beginning of rangerangeEnd
- exclusive ending of range@Deprecated public void flip(int rangeStart, int rangeEnd)
rangeStart
- inclusive beginning of rangerangeEnd
- exclusive ending of rangepublic long getLongCardinality()
getLongCardinality
in interface ImmutableBitmapDataProvider
public int getCardinality()
ImmutableBitmapDataProvider
getCardinality
in interface ImmutableBitmapDataProvider
public void forEach(IntConsumer ic)
ImmutableBitmapDataProvider
bitmap.forEach(new IntConsumer() {
{@literal @}Override
public void accept(int value) {
// do something here
}});
}
forEach
in interface ImmutableBitmapDataProvider
ic
- the consumerpublic ContainerPointer getContainerPointer()
public PeekableIntIterator getIntIterator()
forEach
method.getIntIterator
in interface ImmutableBitmapDataProvider
public IntIterator getReverseIntIterator()
getReverseIntIterator
in interface ImmutableBitmapDataProvider
public long getLongSizeInBytes()
getLongSizeInBytes
in interface ImmutableBitmapDataProvider
public int getSizeInBytes()
ImmutableBitmapDataProvider
getSizeInBytes
in interface ImmutableBitmapDataProvider
public boolean hasRunCompression()
public boolean isEmpty()
isEmpty
in interface ImmutableBitmapDataProvider
protected void lazyor(RoaringBitmap x2)
protected void naivelazyor(RoaringBitmap x2)
public RoaringBitmap limit(int maxcardinality)
limit
in interface ImmutableBitmapDataProvider
maxcardinality
- maximal cardinalitypublic void or(RoaringBitmap x2)
x2
- other bitmappublic static RoaringBitmap or(Iterator bitmaps, long rangeStart, long rangeEnd)
bitmaps
- input bitmaps, these are not modifiedrangeStart
- inclusive beginning of rangerangeEnd
- exclusive ending of range@Deprecated public static RoaringBitmap or(Iterator bitmaps, int rangeStart, int rangeEnd)
bitmaps
- input bitmaps, these are not modifiedrangeStart
- inclusive beginning of rangerangeEnd
- exclusive ending of rangepublic long rankLong(int x)
rankLong
in interface ImmutableBitmapDataProvider
x
- upper limitpublic int rank(int x)
ImmutableBitmapDataProvider
rank
in interface ImmutableBitmapDataProvider
x
- upper limitpublic void readExternal(ObjectInput in) throws IOException, ClassNotFoundException
readExternal
in interface Externalizable
IOException
ClassNotFoundException
public void remove(int x)
remove
in interface BitmapDataProvider
x
- integer value representing the index in a bitmappublic void remove(long rangeStart, long rangeEnd)
rangeStart
- inclusive beginning of rangerangeEnd
- exclusive ending of range@Deprecated public void remove(int rangeStart, int rangeEnd)
rangeStart
- inclusive beginning of rangerangeEnd
- exclusive ending of rangepublic boolean removeRunCompression()
protected void repairAfterLazy()
public boolean runOptimize()
public boolean contains(RoaringBitmap subset)
subset
- the potential subsetpublic int select(int j)
select
in interface ImmutableBitmapDataProvider
j
- index of the valuepublic int first()
first
in interface ImmutableBitmapDataProvider
NoSuchElementException
- if emptypublic int last()
last
in interface ImmutableBitmapDataProvider
NoSuchElementException
- if emptypublic void serialize(DataOutput out) throws IOException
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.serialize
in interface ImmutableBitmapDataProvider
out
- the DataOutput streamIOException
- Signals that an I/O exception has occurred.public static long maximumSerializedSize(long cardinality, long universe_size)
cardinality
- maximal cardinalityuniverse_size
- maximal valuepublic int serializedSizeInBytes()
serializedSizeInBytes
in interface ImmutableBitmapDataProvider
public int[] toArray()
toArray
in interface ImmutableBitmapDataProvider
public MutableRoaringBitmap toMutableRoaringBitmap()
public String toString()
public void trim()
trim
in interface BitmapDataProvider
public void writeExternal(ObjectOutput out) throws IOException
writeExternal
in interface Externalizable
IOException
public void xor(RoaringBitmap x2)
x2
- other bitmappublic static RoaringBitmap xor(Iterator bitmaps, long rangeStart, long rangeEnd)
bitmaps
- input bitmaps, these are not modifiedrangeStart
- inclusive beginning of rangerangeEnd
- exclusive ending of range@Deprecated public static RoaringBitmap xor(Iterator bitmaps, int rangeStart, int rangeEnd)
bitmaps
- input bitmaps, these are not modifiedrangeStart
- inclusive beginning of rangerangeEnd
- exclusive ending of rangeCopyright © 2018. All rights reserved.