Module roaringbitmap

Package org.roaringbitmap

Class Util

java.lang.Object

org.roaringbitmap.Util

public final class Util
extends Object

Various useful methods for roaring bitmaps.

Field Summary

Fields

Modifier and Type	Field	Description
static final boolean	USE_HYBRID_BINSEARCH	optimization flag: whether to use hybrid binary search: hybrid formats combine a binary search with a sequential search

Method Summary

Modifier and Type	Method	Description
static Container[]	addOffset(Container source, char offsets)	Add value "offset" to all values in the container, producing two new containers.
static int	advanceUntil(char[] array, int pos, int length, char min)	Find the smallest integer larger than pos such that array[pos]>= min.
protected static int	branchyUnsignedBinarySearch(char[] array, int begin, int end, char k)
static int	cardinalityInBitmapRange(long[] bitmap, int start, int end)	Hamming weight of the bitset in the range start, start+1,..., end-1
static int	cardinalityInBitmapWordRange(long[] bitmap, int start, int end)	Deprecated.
static void	fillArray(long[] bitmap, char[] array)	Fill the array with set bits
static void	fillArrayAND(char[] container, long[] bitmap1, long[] bitmap2)	Compute the bitwise AND between two long arrays and write the set bits in the container.
static void	fillArrayANDNOT(char[] container, long[] bitmap1, long[] bitmap2)	Compute the bitwise ANDNOT between two long arrays and write the set bits in the container.
static void	fillArrayXOR(char[] container, long[] bitmap1, long[] bitmap2)	Compute the bitwise XOR between two long arrays and write the set bits in the container.
static void	flipBitmapRange(long[] bitmap, int start, int end)	flip bits at start, start+1,..., end-1
static int	flipBitmapRangeAndCardinalityChange(long[] bitmap, int start, int end)	Deprecated.
protected static char	highbits(int x)
protected static char	highbits(long x)
protected static int	hybridUnsignedBinarySearch(char[] array, int begin, int end, char k)
static int	intersectArrayIntoBitmap(long[] bitmap, char[] array, int length)	Intersects the bitmap with the array, returning the cardinality of the result
static int	iterateUntil(char[] array, int pos, int length, int min)	Find the smallest integer larger than pos such that array[pos]>= min.
protected static char	lowbits(int x)
protected static char	lowbits(long x)
protected static int	lowbitsAsInteger(int x)
protected static int	lowbitsAsInteger(long x)
static int	maxLowBitAsInteger()
static void	partialRadixSort(int[] data)	Sorts the data by the 16 bit prefix using Radix sort.
static void	resetBitmapRange(long[] bitmap, int start, int end)	clear bits at start, start+1,..., end-1
static int	resetBitmapRangeAndCardinalityChange(long[] bitmap, int start, int end)	Deprecated.
static int	reverseUntil(char[] array, int pos, int length, char max)	Find the largest integer smaller than pos such that array[pos]<= max.
static int	select(long w, int j)	Given a word w, return the position of the jth true bit.
static void	setBitmapRange(long[] bitmap, int start, int end)	set bits at start, start+1,..., end-1
static int	setBitmapRangeAndCardinalityChange(long[] bitmap, int start, int end)	Deprecated.
static long	toUnsignedLong(int x)	Converts the argument to a long by an unsigned conversion.
static int	unsignedBinarySearch(char[] array, int begin, int end, char k)	Look for value k in array in the range [begin,end).
static int	unsignedDifference(char[] set1, int length1, char[] set2, int length2, char[] buffer)	Compute the difference between two sorted lists and write the result to the provided output array
static int	unsignedDifference(CharIterator set1, CharIterator set2, char[] buffer)	Compute the difference between two sorted lists and write the result to the provided output array
static int	unsignedExclusiveUnion2by2(char[] set1, int length1, char[] set2, int length2, char[] buffer)	Compute the exclusive union of two sorted lists and write the result to the provided output array
static int	unsignedIntersect2by2(char[] set1, int length1, char[] set2, int length2, char[] buffer)	Intersect two sorted lists and write the result to the provided output array
static boolean	unsignedIntersects(char[] set1, int length1, char[] set2, int length2)	Checks if two arrays intersect
protected static int	unsignedLocalIntersect2by2(char[] set1, int length1, char[] set2, int length2, char[] buffer)
static int	unsignedLocalIntersect2by2Cardinality(char[] set1, int length1, char[] set2, int length2)	Compute the cardinality of the intersection
protected static int	unsignedOneSidedGallopingIntersect2by2(char[] smallSet, int smallLength, char[] largeSet, int largeLength, char[] buffer)
static int	unsignedUnion2by2(char[] set1, int offset1, int length1, char[] set2, int offset2, int length2, char[] buffer)	Unite two sorted lists and write the result to the provided output array

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

USE_HYBRID_BINSEARCH

public static final boolean USE_HYBRID_BINSEARCH

optimization flag: whether to use hybrid binary search: hybrid formats combine a binary search with a sequential search

See Also:

• Constant Field Values

Method Details

addOffset

public static Container[] addOffset(Container source,
 char offsets)

Add value "offset" to all values in the container, producing two new containers. The existing container remains unchanged. The new container are not converted, so they need to be checked: e.g., we could produce two bitmap containers having low cardinality.

Parameters:

source - source container

offsets - value to add to each value in the container

Returns:

return an array made of two containers

advanceUntil

public static int advanceUntil(char[] array,
 int pos,
 int length,
 char min)

Find the smallest integer larger than pos such that array[pos]>= min. If none can be found, return length. Based on code by O. Kaser.

Parameters:

array - array to search within

pos - starting position of the search

length - length of the array to search

min - minimum value

Returns:

x greater than pos such that array[pos] is at least as large as min, pos is is equal to length if it is not possible.

reverseUntil

public static int reverseUntil(char[] array,
 int pos,
 int length,
 char max)

Find the largest integer smaller than pos such that array[pos]<= max. If none can be found, return length. Based on code by O. Kaser.

Parameters:

array - array to search within

pos - starting position of the search

length - length of the array to search

max - maximum value

Returns:

x less than pos such that array[pos] is at least as small as max, pos is is equal to 0 if it is not possible.

iterateUntil

public static int iterateUntil(char[] array,
 int pos,
 int length,
 int min)

Find the smallest integer larger than pos such that array[pos]>= min. If none can be found, return length.

Parameters:

array - array to search within

pos - starting position of the search

length - length of the array to search

min - minimum value

Returns:

x greater than pos such that array[pos] is at least as large as min, pos is is equal to length if it is not possible.

branchyUnsignedBinarySearch

protected static int branchyUnsignedBinarySearch(char[] array,
 int begin,
 int end,
 char k)

fillArrayAND

public static void fillArrayAND(char[] container,
 long[] bitmap1,
 long[] bitmap2)

Compute the bitwise AND between two long arrays and write the set bits in the container.

Parameters:

container - where we write

bitmap1 - first bitmap

bitmap2 - second bitmap

fillArrayANDNOT

public static void fillArrayANDNOT(char[] container,
 long[] bitmap1,
 long[] bitmap2)

Compute the bitwise ANDNOT between two long arrays and write the set bits in the container.

Parameters:

container - where we write

bitmap1 - first bitmap

bitmap2 - second bitmap

fillArrayXOR

public static void fillArrayXOR(char[] container,
 long[] bitmap1,
 long[] bitmap2)

Compute the bitwise XOR between two long arrays and write the set bits in the container.

Parameters:

container - where we write

bitmap1 - first bitmap

bitmap2 - second bitmap

flipBitmapRange

public static void flipBitmapRange(long[] bitmap,
 int start,
 int end)

flip bits at start, start+1,..., end-1

Parameters:

bitmap - array of words to be modified

start - first index to be modified (inclusive)

end - last index to be modified (exclusive)

cardinalityInBitmapWordRange

@Deprecated
public static int cardinalityInBitmapWordRange(long[] bitmap,
 int start,
 int end)

Deprecated.

Hamming weight of the 64-bit words involved in the range start, start+1,..., end-1, that is, it will compute the cardinality of the bitset from index (floor(start/64) to floor((end-1)/64)) inclusively.

Parameters:

bitmap - array of words representing a bitset

start - first index (inclusive)

end - last index (exclusive)

Returns:

the hamming weight of the corresponding words

cardinalityInBitmapRange

public static int cardinalityInBitmapRange(long[] bitmap,
 int start,
 int end)

Hamming weight of the bitset in the range start, start+1,..., end-1

Parameters:

bitmap - array of words representing a bitset

start - first index (inclusive)

end - last index (exclusive)

Returns:

the hamming weight of the corresponding range

highbits

protected static char highbits(int x)

highbits

protected static char highbits(long x)

hybridUnsignedBinarySearch

protected static int hybridUnsignedBinarySearch(char[] array,
 int begin,
 int end,
 char k)

lowbits

protected static char lowbits(int x)

lowbits

protected static char lowbits(long x)

lowbitsAsInteger

protected static int lowbitsAsInteger(int x)

lowbitsAsInteger

protected static int lowbitsAsInteger(long x)

maxLowBitAsInteger

public static int maxLowBitAsInteger()

resetBitmapRange

public static void resetBitmapRange(long[] bitmap,
 int start,
 int end)

clear bits at start, start+1,..., end-1

Parameters:

bitmap - array of words to be modified

start - first index to be modified (inclusive)

end - last index to be modified (exclusive)

intersectArrayIntoBitmap

public static int intersectArrayIntoBitmap(long[] bitmap,
 char[] array,
 int length)

Intersects the bitmap with the array, returning the cardinality of the result

Parameters:

bitmap - the bitmap, modified

array - the array, not modified

length - how much of the array to consume

Returns:

the size of the intersection, i.e. how many bits still set in the bitmap

select

public static int select(long w,
 int j)

Given a word w, return the position of the jth true bit.

Parameters:

w - word

j - index

Returns:

position of jth true bit in w

setBitmapRange

public static void setBitmapRange(long[] bitmap,
 int start,
 int end)

set bits at start, start+1,..., end-1

Parameters:

bitmap - array of words to be modified

start - first index to be modified (inclusive)

end - last index to be modified (exclusive)

setBitmapRangeAndCardinalityChange

@Deprecated
public static int setBitmapRangeAndCardinalityChange(long[] bitmap,
 int start,
 int end)

Deprecated.

set bits at start, start+1,..., end-1 and report the cardinality change

Parameters:

bitmap - array of words to be modified

start - first index to be modified (inclusive)

end - last index to be modified (exclusive)

Returns:

cardinality change

flipBitmapRangeAndCardinalityChange

@Deprecated
public static int flipBitmapRangeAndCardinalityChange(long[] bitmap,
 int start,
 int end)

Deprecated.

flip bits at start, start+1,..., end-1 and report the cardinality change

Parameters:

bitmap - array of words to be modified

start - first index to be modified (inclusive)

end - last index to be modified (exclusive)

Returns:

cardinality change

resetBitmapRangeAndCardinalityChange

@Deprecated
public static int resetBitmapRangeAndCardinalityChange(long[] bitmap,
 int start,
 int end)

Deprecated.

reset bits at start, start+1,..., end-1 and report the cardinality change

Parameters:

bitmap - array of words to be modified

start - first index to be modified (inclusive)

end - last index to be modified (exclusive)

Returns:

cardinality change

unsignedBinarySearch

public static int unsignedBinarySearch(char[] array,
 int begin,
 int end,
 char k)

Look for value k in array in the range [begin,end). If the value is found, return its index. If not, return -(i+1) where i is the index where the value would be inserted. The array is assumed to contain sorted values where shorts are interpreted as unsigned integers.

Parameters:

array - array where we search

begin - first index (inclusive)

end - last index (exclusive)

k - value we search for

Returns:

count

unsignedDifference

public static int unsignedDifference(char[] set1,
 int length1,
 char[] set2,
 int length2,
 char[] buffer)

Compute the difference between two sorted lists and write the result to the provided output array

Parameters:

set1 - first array

length1 - length of first array

set2 - second array

length2 - length of second array

buffer - output array

Returns:

cardinality of the difference

unsignedDifference

public static int unsignedDifference(CharIterator set1,
 CharIterator set2,
 char[] buffer)

Compute the difference between two sorted lists and write the result to the provided output array

Parameters:

set1 - first array

set2 - second array

buffer - output array

Returns:

cardinality of the difference

unsignedExclusiveUnion2by2

public static int unsignedExclusiveUnion2by2(char[] set1,
 int length1,
 char[] set2,
 int length2,
 char[] buffer)

Compute the exclusive union of two sorted lists and write the result to the provided output array

Parameters:

set1 - first array

length1 - length of first array

set2 - second array

length2 - length of second array

buffer - output array

Returns:

cardinality of the exclusive union

unsignedIntersect2by2

public static int unsignedIntersect2by2(char[] set1,
 int length1,
 char[] set2,
 int length2,
 char[] buffer)

Intersect two sorted lists and write the result to the provided output array

Parameters:

set1 - first array

length1 - length of first array

set2 - second array

length2 - length of second array

buffer - output array

Returns:

cardinality of the intersection

unsignedIntersects

public static boolean unsignedIntersects(char[] set1,
 int length1,
 char[] set2,
 int length2)

Checks if two arrays intersect

Parameters:

set1 - first array

length1 - length of first array

set2 - second array

length2 - length of second array

Returns:

true if they intersect

unsignedLocalIntersect2by2

protected static int unsignedLocalIntersect2by2(char[] set1,
 int length1,
 char[] set2,
 int length2,
 char[] buffer)

unsignedLocalIntersect2by2Cardinality

public static int unsignedLocalIntersect2by2Cardinality(char[] set1,
 int length1,
 char[] set2,
 int length2)

Compute the cardinality of the intersection

Parameters:

set1 - first set

length1 - how many values to consider in the first set

set2 - second set

length2 - how many values to consider in the second set

Returns:

cardinality of the intersection

unsignedOneSidedGallopingIntersect2by2

protected static int unsignedOneSidedGallopingIntersect2by2(char[] smallSet,
 int smallLength,
 char[] largeSet,
 int largeLength,
 char[] buffer)

unsignedUnion2by2

public static int unsignedUnion2by2(char[] set1,
 int offset1,
 int length1,
 char[] set2,
 int offset2,
 int length2,
 char[] buffer)

Unite two sorted lists and write the result to the provided output array

Parameters:

set1 - first array

offset1 - offset of first array

length1 - length of first array

set2 - second array

offset2 - offset of second array

length2 - length of second array

buffer - output array

Returns:

cardinality of the union

toUnsignedLong

public static long toUnsignedLong(int x)

Converts the argument to a long by an unsigned conversion. In an unsigned conversion to a long, the high-order 32 bits of the long are zero and the low-order 32 bits are equal to the bits of the integer argument. Consequently, zero and positive int values are mapped to a numerically equal long value and negative int values are mapped to a long value equal to the input plus 2³².

Parameters:

x - the value to convert to an unsigned long

Returns:

the argument converted to long by an unsigned conversion

Since:

1.8

partialRadixSort

public static void partialRadixSort(int[] data)

Sorts the data by the 16 bit prefix using Radix sort. The resulting data will be partially sorted if you just take into account the most significant 16 bits. The least significant 16 bits are unsorted. Note that we treat int values as unsigned integers (from 0 to 2^32).

Parameters:

data - - the data (sorted in place)

fillArray

public static void fillArray(long[] bitmap,
 char[] array)

Fill the array with set bits

Parameters:

bitmap - source bitmap

array - container (should be sufficiently large)