Package 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

## Method Summary

Modifier and Type
Method
Description
`int`
`getEffectiveK()`
Returns the effective k of this Union.
`static <T> ItemsUnion<T>`
`getInstance(Class<T> clazz, int maxK, Comparator<? super T> comparator)`
Create an instance of ItemsUnion
`static <T> ItemsUnion<T>`
`getInstance(Class<T> clazz, Comparator<? super T> comparator)`
Create an instance of ItemsUnion with the default k
`static <T> ItemsUnion<T>`
`getInstance(Class<T> clazz, org.apache.datasketches.memory.Memory srcMem, Comparator<? super T> comparator, ArrayOfItemsSerDe<T> serDe)`
Heapify the given srcMem into a Union object.
`static <T> ItemsUnion<T>`
`getInstance(ItemsSketch<T> sketch)`
Create an instance of ItemsUnion based on ItemsSketch
`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`
`union(org.apache.datasketches.memory.Memory srcMem, ArrayOfItemsSerDe<T> serDe)`
Iterative union operation, which means this method can be repeatedly called.
`void`
`union(ItemsSketch<T> sketchIn)`
Iterative union operation, which means this method can be repeatedly called.
`void`
`update(T dataItem)`
Update this union with the given dataItem.

### Methods inherited from class java.lang.Object

`equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

## Method Details

### getInstance

public static <T> ItemsUnion<T> getInstance(Class<T> clazz, Comparator<? super T> comparator)
Create an instance of ItemsUnion with the default k

Type Parameters:
  `T` - The sketch data type
Parameters:
  `clazz` - The sketch class type
  `comparator` - to compare items
Returns:
  an instance of ItemsUnion

### getInstance

public static <T> ItemsUnion<T> getInstance(Class<T> clazz, int maxK, Comparator<? super T> comparator)
Create an instance of ItemsUnion

Type Parameters:
  `T` - The sketch data type
Parameters:
  `clazz` - The sketch class type
  `maxK` - determines the accuracy and size of the union and is a maximum. 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 a different k.
  `comparator` - to compare items
Returns:
  an instance of ItemsUnion

### getInstance

public static <T> ItemsUnion<T> getInstance(Class<T> clazz, org.apache.datasketches.memory.Memory srcMem, Comparator<? super T> comparator, ArrayOfItemsSerDe<T> serDe)
Heapify the given srcMem into a Union object.

Type Parameters:
  `T` - The sketch data type
Parameters:
  `clazz` - The sketch class type A reference to srcMem will not be maintained internally.
  `srcMem` - the given srcMem.
  `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` - The sketch data type
Parameters:
  `sketch` - the basis of the union
Returns:
  an instance of ItemsUnion

### union

public void union(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's be a power of 2. This is easily satisfied if each of the K's are 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.

### union

public void union(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's be a power of 2. This is easily satisfied if each of the K's are 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 dataItem.

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. Keeps maxK, comparator and clazz

### 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