Package org.roaringbitmap
Class RoaringBitmap
java.lang.Object
org.roaringbitmap.RoaringBitmap
- All Implemented Interfaces:
Externalizable
,Serializable
,Cloneable
,Iterable<Integer>
,AppendableStorage<Container>
,BitmapDataProvider
,ImmutableBitmapDataProvider
- Direct Known Subclasses:
FastRankRoaringBitmap
public class RoaringBitmap
extends Object
implements Cloneable, Serializable, Iterable<Integer>, Externalizable, ImmutableBitmapDataProvider, BitmapDataProvider, AppendableStorage<Container>
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).
Up to 4294967296 integers
can be stored.- See Also:
- Serialized Form
-
Nested Class Summary
Nested classes/interfaces inherited from interface org.roaringbitmap.ImmutableBitmapDataProvider
ImmutableBitmapDataProvider.RoaringOfInt
-
Constructor Summary
ConstructorDescriptionCreate an empty bitmapCreate a RoaringBitmap from a MutableRoaringBitmap or ImmutableRoaringBitmap. -
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 RoaringBitmap
add(RoaringBitmap rb, int rangeStart, int rangeEnd)
Deprecated.use the version where longs specify the rangestatic RoaringBitmap
add(RoaringBitmap 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 RoaringBitmap
addOffset(RoaringBitmap x, long offset)
Generate a copy of the provided bitmap, but with all its values incremented by offset.static RoaringBitmap
and(Iterator<? extends RoaringBitmap> bitmaps, int rangeStart, int rangeEnd)
Deprecated.use the version where longs specify the range.static RoaringBitmap
and(Iterator<? extends RoaringBitmap> 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.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.void
Appends the key and container to the storage, throws if the key is less than the current mark.static RoaringBitmap
bitmapOf(int... dat)
Generate a bitmap with the specified values set to true.static RoaringBitmap
bitmapOfRange(long min, long max)
static RoaringBitmap
bitmapOfUnordered(int... data)
Efficiently builds a RoaringBitmap from unordered databoolean
cardinalityExceeds(long threshold)
Returns true if the bitmap's cardinality exceeds the threshold.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()
boolean
contains(int x)
Checks whether the value is included, which is equivalent to checking if the corresponding bit is set (get in BitSet class).boolean
contains(long minimum, long supremum)
Checks if the bitmap contains the range.boolean
contains(RoaringBitmap subset)
Checks whether the parameter is a subset of this RoaringBitmap or notvoid
deserialize(DataInput in)
Deserialize (retrieve) this bitmap.void
deserialize(DataInput in, byte[] buffer)
Deserialize (retrieve) this bitmap.void
deserialize(ByteBuffer bbf)
Deserialize (retrieve) this bitmap.boolean
int
first()
Get the first (smallest) integer in this RoaringBitmap, that is, return 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 rangevoid
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 rangestatic RoaringBitmap
flip(RoaringBitmap bm, long rangeStart, long rangeEnd)
Complements the bits in the given range, from rangeStart (inclusive) rangeEnd (exclusive).void
forAllInRange(int uStart, int length, RelativeRangeConsumer rrc)
Consume presence information for all values in the range [start, start + length).void
forEach(IntConsumer ic)
Visit all values in the bitmap and pass them to the consumer.void
forEachInRange(int start, int length, IntConsumer ic)
Consume each value present in the range [start, start + length).This iterator may be faster than othersint
Returns the number of distinct integers added to the bitmap (e.g., number of bits set).Return a low-level container pointer that can be used to access the underlying data structure.For better performance, consider the Use theforEach
method.long
Returns the number of distinct integers added to the bitmap (e.g., number of bits set).long
Estimate of the memory usage of this data structure.int
Estimate of the memory usage of this data structure.int
hashCode()
Compute the hashCode() of this bitmap.boolean
Check whether this bitmap has had its runs compressed.boolean
intersects(long minimum, long supremum)
Checks if the range intersects with the bitmap.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()
iterate over the positions of the true values.int
last()
Get the last (largest) integer in this RoaringBitmap, that is, return the maximum of the set.protected void
lazyor(RoaringBitmap x2)
protected static RoaringBitmap
lazyor(RoaringBitmap x1, RoaringBitmap x2)
protected static 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)
long
nextAbsentValue(int fromValue)
Returns the first absent value equal to or larger than the provided value (interpreted as an unsigned integer).long
nextValue(int fromValue)
Returns the first value equal to or larger than the provided value (interpreted as an unsigned integer).static RoaringBitmap
or(Iterator<? extends RoaringBitmap> bitmaps)
Compute overall OR between bitmaps.static RoaringBitmap
or(Iterator<? extends RoaringBitmap> bitmaps, int rangeStart, int rangeEnd)
Deprecated.use the version where longs specify the range.static RoaringBitmap
or(Iterator<? extends RoaringBitmap> bitmaps, long rangeStart, long rangeEnd)
Computes OR between input bitmaps in the given range, from rangeStart (inclusive) to rangeEnd (exclusive)void
or(RoaringBitmap x2)
In-place bitwise OR (union) operation.static RoaringBitmap
or(RoaringBitmap... bitmaps)
Compute overall OR between bitmaps.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.void
orNot(RoaringBitmap other, long rangeEnd)
In-place bitwise ORNOT operation.static RoaringBitmap
orNot(RoaringBitmap x1, RoaringBitmap x2, long rangeEnd)
Bitwise ORNOT operation for the given range, rangeStart (inclusive) and rangeEnd (exclusive).long
previousAbsentValue(int fromValue)
Returns the first absent value less than or equal to the provided value (interpreted as an unsigned integer).long
previousValue(int fromValue)
Returns the first value less than or equal to the provided value (interpreted as an unsigned integer).long
rangeCardinality(long start, long end)
Computes the number of values in the interval [start,end) where start is included and end excluded.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 rangevoid
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 rangestatic RoaringBitmap
remove(RoaringBitmap 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 more space efficientint
select(int j)
Return the jth value stored in this bitmap.void
serialize(DataOutput out)
Serialize this bitmap.void
serialize(ByteBuffer buffer)
Serialize this bitmap to a ByteBuffer.int
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.Convert (copies) to a mutable roaring bitmap.toString()
A string describing the bitmap.void
trim()
Recover allocated but unused memory.void
writeExternal(ObjectOutput out)
static RoaringBitmap
xor(Iterator<? extends RoaringBitmap> bitmaps, int rangeStart, int rangeEnd)
Deprecated.use the version where longs specify the range.static RoaringBitmap
xor(Iterator<? extends RoaringBitmap> 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.Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
Methods inherited from interface org.roaringbitmap.ImmutableBitmapDataProvider
reverseStream, stream
Methods inherited from interface java.lang.Iterable
forEach, spliterator
-
Constructor Details
-
RoaringBitmap
public RoaringBitmap()Create an empty bitmap -
RoaringBitmap
Create a RoaringBitmap from a MutableRoaringBitmap or ImmutableRoaringBitmap. The source 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- 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.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. If you have more than 2 bitmaps, consider using the FastAggregation class.- Parameters:
x1
- first bitmapx2
- other bitmap- Returns:
- result of the operation
- See Also:
FastAggregation.and(RoaringBitmap...)
-
andCardinality
Cardinality of 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:
- as if you did and(x2,x2).getCardinality()
- See Also:
FastAggregation.and(RoaringBitmap...)
-
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
-
bitmapOfUnordered
Efficiently builds a RoaringBitmap from unordered data- Parameters:
data
- unsorted data- Returns:
- a new bitmap
-
bitmapOfRange
- See Also:
add(long, long)
-
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 range, in [0, 0xffffffff]rangeEnd
- exclusive ending of range, in [0, 0xffffffff + 1]- Returns:
- a new Bitmap
-
flip
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 range, in [0, 0xffffffff]rangeEnd
- exclusive ending of range, in [0, 0xffffffff + 1]- Returns:
- a new Bitmap
-
intersects
Checks whether the two bitmaps intersect. This can be much faster than calling "and" and checking the cardinality of the result.- Parameters:
x1
- first bitmapx2
- other bitmap- Returns:
- true if they intersect
-
lazyor
-
lazyorfromlazyinputs
-
or
Compute overall OR between bitmaps. (Effectively callsFastAggregation.or(java.util.Iterator<? extends org.roaringbitmap.RoaringBitmap>)
)- Parameters:
bitmaps
- input bitmaps- Returns:
- aggregated bitmap
-
or
Compute overall OR between bitmaps. (Effectively callsFastAggregation.or(java.util.Iterator<? extends org.roaringbitmap.RoaringBitmap>)
)- 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. If you have more than 2 bitmaps, consider using the FastAggregation class.- Parameters:
x1
- first bitmapx2
- other bitmap- Returns:
- result of the operation
- See Also:
FastAggregation.or(RoaringBitmap...)
,FastAggregation.horizontal_or(RoaringBitmap...)
-
orCardinality
Cardinality of the 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 bitmapx2
- other bitmap- Returns:
- cardinality of the union
- See Also:
FastAggregation.or(RoaringBitmap...)
,FastAggregation.horizontal_or(RoaringBitmap...)
-
xorCardinality
Cardinality of the 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:
- cardinality of the symmetric difference
-
andNotCardinality
Cardinality of the bitwise ANDNOT (left 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:
- cardinality of the left difference
-
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.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. If you have more than 2 bitmaps, consider using the FastAggregation class.- Parameters:
x1
- first bitmapx2
- other bitmap- Returns:
- result of the operation
- See Also:
FastAggregation.xor(RoaringBitmap...)
,FastAggregation.horizontal_xor(RoaringBitmap...)
-
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
-
intersects
public boolean intersects(long minimum, long supremum)Checks if the range intersects with the bitmap.- Parameters:
minimum
- the inclusive unsigned lower bound of the rangesupremum
- the exclusive unsigned upper bound of the range- Returns:
- whether the bitmap intersects with the range
-
and
In-place bitwise AND (intersection) operation. The current bitmap is modified.- Parameters:
x2
- other bitmap
-
and
public static RoaringBitmap and(Iterator<? extends RoaringBitmap> bitmaps, long rangeStart, long rangeEnd)Computes AND between input bitmaps in the given range, from rangeStart (inclusive) to rangeEnd (exclusive)- Parameters:
bitmaps
- input bitmaps, these are not modifiedrangeStart
- inclusive beginning of rangerangeEnd
- exclusive ending of range- Returns:
- new result bitmap
-
and
@Deprecated public static RoaringBitmap and(Iterator<? extends RoaringBitmap> bitmaps, int rangeStart, int rangeEnd)Deprecated.use the version where longs specify the range. Negative range end are illegal.Computes AND between input bitmaps in the given range, from rangeStart (inclusive) to rangeEnd (exclusive)- Parameters:
bitmaps
- input bitmaps, these are not modifiedrangeStart
- inclusive beginning of rangerangeEnd
- exclusive ending of range- Returns:
- new result bitmap
-
andNot
In-place bitwise ANDNOT (difference) operation. The current bitmap is modified.- Parameters:
x2
- other bitmap
-
andNot
public static RoaringBitmap andNot(RoaringBitmap x1, RoaringBitmap x2, long rangeStart, long rangeEnd)Bitwise ANDNOT (difference) operation for the given range, rangeStart (inclusive) and rangeEnd (exclusive). The provided bitmaps are *not* modified. This operation is thread-safe as long as the provided bitmaps remain unchanged.- Parameters:
x1
- first bitmapx2
- other bitmaprangeStart
- starting point of the range (inclusive)rangeEnd
- end point of the range (exclusive)- Returns:
- result of the operation
-
andNot
@Deprecated public 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.Bitwise ANDNOT (difference) operation for the given range, rangeStart (inclusive) and rangeEnd (exclusive). The provided bitmaps are *not* modified. This operation is thread-safe as long as the provided bitmaps remain unchanged.- Parameters:
x1
- first bitmapx2
- other bitmaprangeStart
- starting point of the range (inclusive)rangeEnd
- end point of the range (exclusive)- Returns:
- result of the operation
-
orNot
In-place bitwise ORNOT operation. The current bitmap is modified.- Parameters:
other
- the other bitmaprangeEnd
- end point of the range (exclusive).
-
orNot
Bitwise ORNOT operation for the given range, rangeStart (inclusive) and rangeEnd (exclusive). The provided bitmaps are *not* modified. This operation is thread-safe as long as the provided bitmaps remain unchanged.- Parameters:
x1
- first bitmapx2
- other bitmaprangeEnd
- end point of the range (exclusive)- 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.
-
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
-
contains
public boolean contains(int x)Checks whether the value is included, which is equivalent to checking if the corresponding bit is set (get in BitSet class).- Specified by:
contains
in interfaceImmutableBitmapDataProvider
- Parameters:
x
- integer value- Returns:
- whether the integer value is included.
-
contains
public boolean contains(long minimum, long supremum)Checks if the bitmap contains the range.- Parameters:
minimum
- the inclusive lower bound of the rangesupremum
- the exclusive upper bound of the range- Returns:
- whether the bitmap contains the range
-
deserialize
Deserialize (retrieve) this bitmap. See format specification at https://github.com/RoaringBitmap/RoaringFormatSpec The current bitmap is overwritten.- Parameters:
in
- the DataInput streambuffer
- The buffer gets overwritten with data during deserialization. You can pass a NULL reference as a buffer. A buffer containing at least 8192 bytes might be ideal for performance. It is recommended to reuse the buffer between calls to deserialize (in a single-threaded context) for best performance.- 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.- 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:
bbf
- the byte buffer (can be mapped, direct, array backed etc.- Throws:
IOException
- Signals that an I/O exception has occurred.
-
equals
-
isHammingSimilar
Returns true if the other bitmap has no more than tolerance bits differing from this bitmap. The other may be transformed into a bitmap equal to this bitmap in no more than tolerance bit flips if this method returns true.- Parameters:
other
- the bitmap to compare totolerance
- the maximum number of bits that may differ- Returns:
- true if the number of differing bits is smaller than tolerance
-
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
-
getLongCardinality
public long getLongCardinality()Returns the number of distinct integers added to the bitmap (e.g., number of bits set).- Specified by:
getLongCardinality
in interfaceImmutableBitmapDataProvider
- Returns:
- the cardinality
-
getCardinality
public int getCardinality()Description copied from interface:ImmutableBitmapDataProvider
Returns the number of distinct integers added to the bitmap (e.g., number of bits set). Internally, this is computed as a 64-bit number.- Specified by:
getCardinality
in interfaceImmutableBitmapDataProvider
- Returns:
- the cardinality
-
cardinalityExceeds
public boolean cardinalityExceeds(long threshold)Returns true if the bitmap's cardinality exceeds the threshold.- Parameters:
threshold
- threshold- Returns:
- true if the cardinality exceeds the threshold.
-
forEach
Description copied from interface:ImmutableBitmapDataProvider
Visit all values in the bitmap and pass them to the consumer. * Usage:bitmap.forEach(new IntConsumer() { {@literal @}Override public void accept(int value) { // do something here }});
}- Specified by:
forEach
in interfaceImmutableBitmapDataProvider
- Parameters:
ic
- the consumer
-
forAllInRange
Consume presence information for all values in the range [start, start + length).- Parameters:
uStart
- Lower bound of values to consume.length
- Maximum number of values to consume.rrc
- Code to be executed for each present or absent value.
-
forEachInRange
Consume each value present in the range [start, start + length).- Parameters:
start
- Lower bound of values to consume.length
- Maximum number of values to consume.ic
- Code to be executed for each present value.
-
getContainerPointer
Return a low-level container pointer that can be used to access the underlying data structure.- Returns:
- container pointer
-
getIntIterator
For better performance, consider the Use theforEach
method.- Specified by:
getIntIterator
in interfaceImmutableBitmapDataProvider
- Returns:
- a custom iterator over set bits, the bits are traversed in ascending sorted order
-
getReverseIntIterator
- Specified by:
getReverseIntIterator
in interfaceImmutableBitmapDataProvider
- Returns:
- a custom iterator over set bits, the bits are traversed in descending sorted order
-
getBatchIterator
Description copied from interface:ImmutableBitmapDataProvider
This iterator may be faster than others- Specified by:
getBatchIterator
in interfaceImmutableBitmapDataProvider
- Returns:
- iterator which works on batches of data.
-
getLongSizeInBytes
public long getLongSizeInBytes()Estimate of the memory usage of this data structure. This can be expected to be within 1% of the true memory usage in common usage scenarios. If exact measures are needed, we recommend using dedicated libraries such as ehcache-sizeofengine. In adversarial cases, this estimate may be 10x the actual memory usage. For example, if you insert a single random value in a bitmap, then over a 100 bytes may be used by the JVM whereas this function may return an estimate of 32 bytes. The same will be true in the "sparse" scenario where you have a small set of random-looking integers spanning a wide range of values. These are considered adversarial cases because, as a general rule, if your data looks like a set of random integers, Roaring bitmaps are probably not the right data structure. Note that you can serialize your Roaring Bitmaps to disk and then construct ImmutableRoaringBitmap instances from a ByteBuffer. In such cases, the Java heap usage will be significantly less than what is reported. If your main goal is to compress arrays of integers, there are other libraries that are maybe more appropriate such as JavaFastPFOR. Note, however, that in general, random integers (as produced by random number generators or hash functions) are not compressible. Trying to compress random data is an adversarial use case.- Specified by:
getLongSizeInBytes
in interfaceImmutableBitmapDataProvider
- Returns:
- estimated memory usage.
- See Also:
- JavaFastPFOR
-
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 in common usage scenarios. If exact measures are needed, we recommend using dedicated libraries such as ehcache-sizeofengine. In adversarial cases, this estimate may be 10x the actual memory usage. For example, if you insert a single random value in a bitmap, then over a 100 bytes may be used by the JVM whereas this function may return an estimate of 32 bytes. The same will be true in the "sparse" scenario where you have a small set of random-looking integers spanning a wide range of values. These are considered adversarial cases because, as a general rule, if your data looks like a set of random integers, Roaring bitmaps are probably not the right data structure. Note that you can serialize your Roaring Bitmaps to disk and then construct ImmutableRoaringBitmap instances from a ByteBuffer. In such cases, the Java heap usage will be significantly less than what is reported. If your main goal is to compress arrays of integers, there are other libraries that are maybe more appropriate such as JavaFastPFOR. Note, however, that in general, random integers (as produced by random number generators or hash functions) are not compressible. Trying to compress random data is an adversarial use case.- Specified by:
getSizeInBytes
in interfaceImmutableBitmapDataProvider
- Returns:
- estimated memory usage.
- See Also:
- JavaFastPFOR
-
hashCode
public int hashCode()Compute the hashCode() of this bitmap. For performance reasons, this method deliberately violates the Java contract regarding hashCode/equals in the following manner: If the two bitmaps are equal *and* they have the same hasRunCompression() result, then they have the same hashCode(). Thus, for the Java contract to be satisfied, you should either call runOptimize() on all your bitmaps, or on none of your bitmaps. -
hasRunCompression
public boolean hasRunCompression()Check whether this bitmap has had its runs compressed.- Returns:
- whether this bitmap has run compression
-
isEmpty
public boolean isEmpty()Checks whether the bitmap is empty.- Specified by:
isEmpty
in interfaceImmutableBitmapDataProvider
- Returns:
- true if this bitmap contains no set bit
-
iterator
iterate over the positions of the true values. -
lazyor
-
naivelazyor
-
limit
Create a new Roaring bitmap containing at most maxcardinality integers.- Specified by:
limit
in interfaceImmutableBitmapDataProvider
- Parameters:
maxcardinality
- maximal cardinality- Returns:
- a new bitmap with cardinality no more than maxcardinality
-
or
In-place bitwise OR (union) operation. The current bitmap is modified.- Parameters:
x2
- other bitmap
-
or
public static RoaringBitmap or(Iterator<? extends RoaringBitmap> bitmaps, long rangeStart, long rangeEnd)Computes OR between input bitmaps in the given range, from rangeStart (inclusive) to rangeEnd (exclusive)- Parameters:
bitmaps
- input bitmaps, these are not modifiedrangeStart
- inclusive beginning of rangerangeEnd
- exclusive ending of range- Returns:
- new result bitmap
-
or
@Deprecated public static RoaringBitmap or(Iterator<? extends RoaringBitmap> bitmaps, int rangeStart, int rangeEnd)Deprecated.use the version where longs specify the range. Negative range points are forbidden.Computes OR between input bitmaps in the given range, from rangeStart (inclusive) to rangeEnd (exclusive)- Parameters:
bitmaps
- input bitmaps, these are not modifiedrangeStart
- inclusive beginning of rangerangeEnd
- exclusive ending of range- Returns:
- new result bitmap
-
rankLong
public long rankLong(int x)Rank returns the number of integers that are smaller or equal to x (Rank(infinity) would be GetCardinality()). If you provide the smallest value as a parameter, this function will return 1. If provide a value smaller than the smallest value, it will return 0.- Specified by:
rankLong
in interfaceImmutableBitmapDataProvider
- Parameters:
x
- upper limit- Returns:
- the rank
- See Also:
- Ranking in statistics
-
rangeCardinality
public long rangeCardinality(long start, long end)Description copied from interface:ImmutableBitmapDataProvider
Computes the number of values in the interval [start,end) where start is included and end excluded. rangeCardinality(0,0x100000000) provides the total cardinality (getLongCardinality). The answer is a 64-bit value between 1 and 0x100000000.- Specified by:
rangeCardinality
in interfaceImmutableBitmapDataProvider
- Parameters:
start
- lower limit (included)end
- upper limit (excluded)- Returns:
- the number of elements in [start,end), between 0 and 0x100000000.
-
rank
public int rank(int x)Description copied from interface:ImmutableBitmapDataProvider
Rank returns the number of integers that are smaller or equal to x (rank(infinity) would be getCardinality()). If you provide the smallest value as a parameter, this function will return 1. If provide a value smaller than the smallest value, it will return 0. The value is internally computed as a 64-bit number.- Specified by:
rank
in interfaceImmutableBitmapDataProvider
- Parameters:
x
- upper limit- Returns:
- the rank
- See Also:
- Ranking in statistics
-
readExternal
- Specified by:
readExternal
in interfaceExternalizable
- Throws:
IOException
-
remove
public void remove(int x)If present remove the specified integer (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 more space efficient- Returns:
- whether a change was applied
-
contains
Checks whether the parameter is a subset of this RoaringBitmap or not- Parameters:
subset
- the potential subset- Returns:
- true if the parameter is a subset of this RoaringBitmap
-
select
public int select(int j)Return the jth value stored in this bitmap. The provided value needs to be smaller than the cardinality otherwise an IllegalArgumentException exception is thrown. The smallest value is at index 0. Note that this function differs in convention from the rank function which returns 1 when ranking the smallest value.- Specified by:
select
in interfaceImmutableBitmapDataProvider
- Parameters:
j
- index of the value- Returns:
- the value
- See Also:
- Selection algorithm
-
nextValue
public long nextValue(int fromValue)Description copied from interface:ImmutableBitmapDataProvider
Returns the first value equal to or larger than the provided value (interpreted as an unsigned integer). If no such bit exists then-1
is returned. It is not necessarily a computationally effective way to iterate through the values.- Specified by:
nextValue
in interfaceImmutableBitmapDataProvider
- Parameters:
fromValue
- the lower bound (inclusive)- Returns:
- the smallest value larger than or equal to the specified value,
or
-1
if there is no such value
-
previousValue
public long previousValue(int fromValue)Description copied from interface:ImmutableBitmapDataProvider
Returns the first value less than or equal to the provided value (interpreted as an unsigned integer). If no such bit exists then-1
is returned. It is not an efficient way to iterate through the values backwards.- Specified by:
previousValue
in interfaceImmutableBitmapDataProvider
- Parameters:
fromValue
- the upper bound (inclusive)- Returns:
- the largest value less than or equal to the specified value,
or
-1
if there is no such value
-
nextAbsentValue
public long nextAbsentValue(int fromValue)Description copied from interface:ImmutableBitmapDataProvider
Returns the first absent value equal to or larger than the provided value (interpreted as an unsigned integer). It is not necessarily a computationally effective way to iterate through the values.- Specified by:
nextAbsentValue
in interfaceImmutableBitmapDataProvider
- Parameters:
fromValue
- the lower bound (inclusive)- Returns:
- the smallest absent value larger than or equal to the specified value.
-
previousAbsentValue
public long previousAbsentValue(int fromValue)Description copied from interface:ImmutableBitmapDataProvider
Returns the first absent value less than or equal to the provided value (interpreted as an unsigned integer). It is not necessarily a computationally effective way to iterate through the values.- Specified by:
previousAbsentValue
in interfaceImmutableBitmapDataProvider
- Parameters:
fromValue
- the lower bound (inclusive)- Returns:
- the smallest absent value larger than or equal to the specified value.
-
first
public int first()Description copied from interface:ImmutableBitmapDataProvider
Get the first (smallest) integer in this RoaringBitmap, that is, return the minimum of the set.- Specified by:
first
in interfaceImmutableBitmapDataProvider
- Returns:
- the first (smallest) integer
-
last
public int last()Description copied from interface:ImmutableBitmapDataProvider
Get the last (largest) integer in this RoaringBitmap, that is, return the maximum of the set.- Specified by:
last
in interfaceImmutableBitmapDataProvider
- Returns:
- the last (largest) integer
-
serialize
Serialize this bitmap. See format specification at https://github.com/RoaringBitmap/RoaringFormatSpec Consider callingrunOptimize()
before serialization to improve compression. The current bitmap is not modified. There is a distinct and dedicated method to serialize to a ByteBuffer. 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 interfaceImmutableBitmapDataProvider
- Parameters:
out
- the DataOutput stream- Throws:
IOException
- Signals that an I/O exception has occurred.
-
serialize
Description copied from interface:ImmutableBitmapDataProvider
Serialize this bitmap to a ByteBuffer. This is the preferred method to serialize to a byte array (byte[]) or to a String (via Base64.getEncoder().encodeToString).. Irrespective of the endianess of the provided buffer, data is written using LITTlE_ENDIAN as per the RoaringBitmap specification. The current bitmap is not modified.byte[] array = new byte[mrb.serializedSizeInBytes()]; mrb.serialize(ByteBuffer.wrap(array));
- Specified by:
serialize
in interfaceImmutableBitmapDataProvider
- Parameters:
buffer
- the ByteBuffer
-
maximumSerializedSize
public 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.- Parameters:
cardinality
- maximal cardinalityuniverse_size
- maximal value- Returns:
- upper bound on the serialized size in bytes of the bitmap
-
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 interfaceImmutableBitmapDataProvider
- Returns:
- the size in bytes
-
toArray
public int[] toArray()Return the set values as an array, if the cardinality is smaller than 2147483648. The integer values are in sorted order.- Specified by:
toArray
in interfaceImmutableBitmapDataProvider
- Returns:
- array representing the set values.
-
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<Container>
- Parameters:
key
- the key to appendcontainer
- the data to append
-
toMutableRoaringBitmap
Convert (copies) to a mutable roaring bitmap.- Returns:
- a copy of this bitmap as a MutableRoaringBitmap
-
toString
A string describing the bitmap. -
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
-
xor
public static RoaringBitmap xor(Iterator<? extends RoaringBitmap> bitmaps, long rangeStart, long rangeEnd)Computes XOR between input bitmaps in the given range, from rangeStart (inclusive) to rangeEnd (exclusive)- Parameters:
bitmaps
- input bitmaps, these are not modifiedrangeStart
- inclusive beginning of rangerangeEnd
- exclusive ending of range- Returns:
- new result bitmap
-
xor
@Deprecated public static RoaringBitmap xor(Iterator<? extends RoaringBitmap> bitmaps, int rangeStart, int rangeEnd)Deprecated.use the version where longs specify the range. Negative values not allowed for rangeStart and rangeEndComputes XOR between input bitmaps in the given range, from rangeStart (inclusive) to rangeEnd (exclusive)- Parameters:
bitmaps
- input bitmaps, these are not modifiedrangeStart
- inclusive beginning of rangerangeEnd
- exclusive ending of range- Returns:
- new result bi
-