org.apache.datasketches.quantiles

Class ItemsUnion<T>

java.lang.Object

org.apache.datasketches.quantiles.ItemsUnion<T>

Type Parameters:

T - type of item

public final class ItemsUnion<T>
extends Object

The API for Union operations for generic ItemsSketches

Author:

Lee Rhodes, Alexander Saydakov

Field Summary

Fields

Modifier and Type	Field and Description
protected Comparator<? super T>	comparator_
protected ItemsSketch<T>	gadget_
protected int	maxK_

Method Summary

Modifier and Type	Method and Description
int	getEffectiveK() Returns the effective k of this Union.
static <T> ItemsUnion<T>	getInstance(Comparator<? super T> comparator) Create an instance of ItemsUnion with the default k
static <T> ItemsUnion<T>	getInstance(int maxK, Comparator<? super T> comparator) Create an instance of ItemsUnion
static <T> ItemsUnion<T>	getInstance(ItemsSketch<T> sketch) Create an instance of ItemsUnion based on ItemsSketch
static <T> ItemsUnion<T>	getInstance(org.apache.datasketches.memory.Memory srcMem, Comparator<? super T> comparator, ArrayOfItemsSerDe<T> serDe) Heapify the given srcMem into a Union object.
int	getMaxK() Returns the configured maxK of this Union.
ItemsSketch<T>	getResult() Gets the result of this Union operation as a copy of the internal state.
ItemsSketch<T>	getResultAndReset() Gets the result of this Union operation (without a copy) and resets this Union to the virgin state.
boolean	isDirect() Returns true if this union is direct
boolean	isEmpty() Returns true if this union is empty
void	reset() Resets this Union to a virgin state.
byte[]	toByteArray(ArrayOfItemsSerDe<T> serDe) Serialize this union to a byte array.
String	toString() Returns summary information about the backing sketch.
String	toString(boolean sketchSummary, boolean dataDetail) Returns summary information about the backing sketch.
void	update(ItemsSketch<T> sketchIn) Iterative union operation, which means this method can be repeatedly called.
void	update(org.apache.datasketches.memory.Memory srcMem, ArrayOfItemsSerDe<T> serDe) Iterative union operation, which means this method can be repeatedly called.
void	update(T dataItem) Update this union with the given double (or float) data Item.

Methods inherited from class java.lang.Object

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

Field Detail

maxK_

protected final int maxK_

comparator_

protected final Comparator<? super T> comparator_

gadget_

protected ItemsSketch<T> gadget_

Method Detail

getInstance

public static <T> ItemsUnion<T> getInstance(Comparator<? super T> comparator)

Create an instance of ItemsUnion with the default k

Type Parameters:

T - type of item

Parameters:

comparator - to compare items

Returns:

an instance of ItemsUnion

getInstance

public static <T> ItemsUnion<T> getInstance(int maxK,
                                            Comparator<? super T> comparator)

Create an instance of ItemsUnion

Type Parameters:

T - type of item

Parameters:

maxK - determines the accuracy and size of the union and is a maximum value. The effective k can be smaller due to unions with smaller k sketches. It is recommended that maxK be a power of 2 to enable unioning of sketches with different values of k.

comparator - to compare items

Returns:

an instance of ItemsUnion

getInstance

public static <T> ItemsUnion<T> getInstance(org.apache.datasketches.memory.Memory srcMem,
                                            Comparator<? super T> comparator,
                                            ArrayOfItemsSerDe<T> serDe)

Heapify the given srcMem into a Union object.

Type Parameters:

T - type of item

Parameters:

srcMem - the given srcMem. A reference to srcMem will not be maintained internally.

comparator - to compare items

serDe - an instance of ArrayOfItemsSerDe

Returns:

an instance of ItemsUnion

getInstance

public static <T> ItemsUnion<T> getInstance(ItemsSketch<T> sketch)

Create an instance of ItemsUnion based on ItemsSketch

Type Parameters:

T - type of item

Parameters:

sketch - the basis of the union

Returns:

an instance of ItemsUnion

update

public void update(ItemsSketch<T> sketchIn)

Iterative union operation, which means this method can be repeatedly called. Merges the given sketch into this union object. The given sketch is not modified. It is required that the ratio of the two K values be a power of 2. This is easily satisfied if each of the K values is already a power of 2. If the given sketch is null or empty it is ignored.

It is required that the results of the union operation, which can be obtained at any time, is obtained from getResult().

Parameters:

sketchIn - the sketch to be merged into this one.

update

public void update(org.apache.datasketches.memory.Memory srcMem,
                   ArrayOfItemsSerDe<T> serDe)

Iterative union operation, which means this method can be repeatedly called. Merges the given Memory image of a ItemsSketch into this union object. The given Memory object is not modified and a link to it is not retained. It is required that the ratio of the two K values be a power of 2. This is easily satisfied if each of the K values is already a power of 2. If the given sketch is null or empty it is ignored.

It is required that the results of the union operation, which can be obtained at any time, is obtained from getResult().

Parameters:

srcMem - Memory image of sketch to be merged

serDe - an instance of ArrayOfItemsSerDe

update

public void update(T dataItem)

Update this union with the given double (or float) data Item.

Parameters:

dataItem - The given datum.

getResult

public ItemsSketch<T> getResult()

Gets the result of this Union operation as a copy of the internal state. This enables further union update operations on this state.

Returns:

the result of this Union operation

getResultAndReset

public ItemsSketch<T> getResultAndReset()

Gets the result of this Union operation (without a copy) and resets this Union to the virgin state.

Returns:

the result of this Union operation and reset.

reset

public void reset()

Resets this Union to a virgin state.

isEmpty

public boolean isEmpty()

Returns true if this union is empty

Returns:

true if this union is empty

isDirect

public boolean isDirect()

Returns true if this union is direct

Returns:

true if this union is direct

getMaxK

public int getMaxK()

Returns the configured maxK of this Union.

Returns:

the configured maxK of this Union.

getEffectiveK

public int getEffectiveK()

Returns the effective k of this Union.

Returns:

the effective k of this Union.

toString

public String toString()

Returns summary information about the backing sketch.

Overrides:

toString in class Object

toString

public String toString(boolean sketchSummary,
                       boolean dataDetail)

Returns summary information about the backing sketch. Used for debugging.

Parameters:

sketchSummary - if true includes sketch summary

dataDetail - if true includes data detail

Returns:

summary information about the sketch.

toByteArray

public byte[] toByteArray(ArrayOfItemsSerDe<T> serDe)

Serialize this union to a byte array. Result is an ItemsSketch, serialized in an unordered, non-compact form. The resulting byte[] can be passed to getInstance for either a sketch or union.

Parameters:

serDe - an instance of ArrayOfItemsSerDe

Returns:

byte array of this union