Module roaringbitmap

Package org.roaringbitmap

Interface ImmutableBitmapDataProvider

All Known Subinterfaces:

BitmapDataProvider

All Known Implementing Classes:

FastRankRoaringBitmap, ImmutableRoaringBitmap, MutableRoaringBitmap, RoaringBitmap

public interface ImmutableBitmapDataProvider

Interface representing an immutable bitmap.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static final class	ImmutableBitmapDataProvider.RoaringOfInt	An internal class to help provide streams.

Method Summary

Modifier and Type	Method	Description
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).
int	first()	Get the smallest unsigned (first) integer in this RoaringBitmap.
int	firstSigned()	Get the smallest signed integer in this RoaringBitmap.
void	forEach(IntConsumer ic)	Visit all values in the bitmap and pass them to the consumer.
BatchIterator	getBatchIterator()	This iterator may be faster than others
int	getCardinality()	Returns the number of distinct integers added to the bitmap (e.g., number of bits set).
int	getContainerCount()	Returns the number of containers in the bitmap.
PeekableIntIterator	getIntIterator()	For better performance, consider using 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()
PeekableIntIterator	getSignedIntIterator()
int	getSizeInBytes()	Estimate of the memory usage of this data structure.
boolean	isEmpty()	Checks whether the bitmap is empty.
int	last()	Get the largest unsigned (last) integer in this RoaringBitmap.
int	lastSigned()	Get the largest signed integer in this RoaringBitmap.
ImmutableBitmapDataProvider	limit(int x)	Create a new bitmap of the same class, containing at most maxcardinality integers.
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).
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 (rankLong(infinity) would be getLongCardinality()).
default IntStream	reverseStream()
int	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	serializedSizeInBytes()	Report the number of bytes required to serialize this bitmap.
default IntStream	stream()
int[]	toArray()	Return the set values as an array.

Method Details

contains

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

Parameters:

x - integer value

Returns:

whether the integer value is included.

getCardinality

int getCardinality()

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.

Returns:

the cardinality

getLongCardinality

long getLongCardinality()

Returns the number of distinct integers added to the bitmap (e.g., number of bits set). This returns a full 64-bit result.

Returns:

the cardinality

forEach

void forEach(IntConsumer ic)

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

    }});
   
 }
 

Parameters:

ic - the consumer

getIntIterator

PeekableIntIterator getIntIterator()

For better performance, consider using the forEach method.

Returns:

a custom iterator over set bits, the bits are traversed in unsigned integer ascending sorted order

getSignedIntIterator

PeekableIntIterator getSignedIntIterator()

Returns:

a custom iterator over set bits, the bits are traversed in signed integer ascending sorted order

getReverseIntIterator

IntIterator getReverseIntIterator()

Returns:

a custom iterator over set bits, the bits are traversed in unsigned integer descending sorted order

stream

default IntStream stream()

Returns:

an Ordered, Distinct, Sorted and Sized IntStream in ascending order

reverseStream

default IntStream reverseStream()

Returns:

an Ordered, Distinct and Sized IntStream providing bits in descending sorted order

getBatchIterator

BatchIterator getBatchIterator()

This iterator may be faster than others

Returns:

iterator which works on batches of data.

getSizeInBytes

int getSizeInBytes()

Estimate of the memory usage of this data structure. Internally, this is computed as a 64-bit counter.

Returns:

estimated memory usage.

getLongSizeInBytes

long getLongSizeInBytes()

Estimate of the memory usage of this data structure. Provides full 64-bit number.

Returns:

estimated memory usage.

isEmpty

boolean isEmpty()

Checks whether the bitmap is empty.

Returns:

true if this bitmap contains no set bit

limit

ImmutableBitmapDataProvider limit(int x)

Create a new bitmap of the same class, containing at most maxcardinality integers.

Parameters:

x - maximal cardinality

Returns:

a new bitmap with cardinality no more than maxcardinality

rank

int rank(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. The value is internally computed as a 64-bit number.

Parameters:

x - upper limit

Returns:

the rank

See Also:

• Ranking in statistics

rankLong

long rankLong(int x)

Rank returns the number of integers that are smaller or equal to x (rankLong(infinity) would be getLongCardinality()). 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. Same as "rank" but produces a full 64-bit value.

Parameters:

x - upper limit

Returns:

the rank

See Also:

• Ranking in statistics

rangeCardinality

long rangeCardinality(long start,
 long end)

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.

Parameters:

start - lower limit (included)

end - upper limit (excluded)

Returns:

the number of elements in [start,end), between 0 and 0x100000000.

select

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.

Parameters:

j - index of the value

Returns:

the value

See Also:

• Selection algorithm

first

int first()

Get the smallest unsigned (first) integer in this RoaringBitmap.

Returns:

the smallest unsigned (first) integer

Throws:

NoSuchElementException - if empty

last

int last()

Get the largest unsigned (last) integer in this RoaringBitmap.

Returns:

the largest unsigned (last) integer

Throws:

NoSuchElementException - if empty

firstSigned

int firstSigned()

Get the smallest signed integer in this RoaringBitmap.

Returns:

the smallest signed integer

Throws:

NoSuchElementException - if empty

lastSigned

int lastSigned()

Get the largest signed integer in this RoaringBitmap.

Returns:

the largest signed integer

Throws:

NoSuchElementException - if empty

nextValue

long nextValue(int fromValue)

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.

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

long previousValue(int fromValue)

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.

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

long nextAbsentValue(int fromValue)

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.

Parameters:

fromValue - the lower bound (inclusive)

Returns:

the smallest absent value larger than or equal to the specified value or -1 if there is no such value.

previousAbsentValue

long previousAbsentValue(int fromValue)

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.

Parameters:

fromValue - the lower bound (inclusive)

Returns:

the smallest absent value larger than or equal to the specified value or -1 if there is no such value.

serialize

void serialize(DataOutput out)
        throws IOException

Serialize this bitmap. The current bitmap is not modified.

Parameters:

out - the DataOutput stream

Throws:

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

serialize

void serialize(ByteBuffer buffer)

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

Parameters:

buffer - the ByteBuffer

serializedSizeInBytes

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.

Returns:

the size in bytes

toArray

int[] toArray()

Return the set values as an array. The integer values are in sorted order.

Returns:

array representing the set values.

getContainerCount

int getContainerCount()

Returns the number of containers in the bitmap.

Returns:

the number of containers