org.apache.datasketches.sampling

## Class VarOptItemsUnion<T>

- java.lang.Object
- - org.apache.datasketches.sampling.VarOptItemsUnion<T>

Type Parameters:
  `T` - Type of items

    public final class VarOptItemsUnion<T>
    extends Object

Provides a unioning operation over varopt sketches. This union allows the sample size k to float, possibly increasing or decreasing as warranted by the available data.

Author:
  Jon Malkin, Kevin Lang

### Method Summary

All Methods Static Methods Instance Methods Concrete Methods
`VarOptItemsSketch<T>` `getResult()` Gets the varopt sketch resulting from the union of any input sketches.
`static <T> VarOptItemsUnion<T>` `heapify(org.apache.datasketches.memory.Memory srcMem, ArrayOfItemsSerDe<T> serDe)` Instantiates a Union from Memory
`static <T> VarOptItemsUnion<T>` `newInstance(int maxK)` Creates an empty Union with a maximum capacity of size k.
`void` `reset()` Resets this sketch to the empty state, but retains the original value of max k.
`byte[]` `toByteArray(ArrayOfItemsSerDe<T> serDe)` Returns a byte array representation of this union
`byte[]` `toByteArray(ArrayOfItemsSerDe<T> serDe, Class<?> clazz)` Returns a byte array representation of this union.
`String` `toString()` Returns a human-readable summary of the sketch, without items.
`void` `update(org.apache.datasketches.memory.Memory mem, ArrayOfItemsSerDe<T> serDe)` Union the given Memory image of the sketch.
`void` `update(ReservoirItemsSketch<T> reservoirIn)` Union a reservoir sketch.
`void` `update(VarOptItemsSketch<T> sketchIn)` Union the given sketch.

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

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

### Method Detail

#### newInstance

    public static <T> VarOptItemsUnion<T> newInstance(int maxK)

Creates an empty Union with a maximum capacity of size k.

Type Parameters:
  `T` - The type of item this union contains
Parameters:
  `maxK` - The maximum allowed capacity of the unioned result
Returns:
  A new VarOptItemsUnion

#### heapify

    public static <T> VarOptItemsUnion<T> heapify(org.apache.datasketches.memory.Memory srcMem,
                                                  ArrayOfItemsSerDe<T> serDe)

Instantiates a Union from Memory

Type Parameters:
  `T` - The type of item this sketch contains
Parameters:
  `srcMem` - Memory object containing a serialized union
  `serDe` - An instance of ArrayOfItemsSerDe
Returns:
  A VarOptItemsUnion created from the provided Memory

#### update

    public void update(VarOptItemsSketch<T> sketchIn)

Union the given sketch.

This method can be repeatedly called.

Parameters:
  `sketchIn` - The sketch to be merged

#### update

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

Union the given Memory image of the sketch.

This method can be repeatedly called.

Parameters:
  `mem` - Memory image of sketch to be merged
  `serDe` - An instance of ArrayOfItemsSerDe

#### update

    public void update(ReservoirItemsSketch<T> reservoirIn)

Union a reservoir sketch. The reservoir sample is treated as if all items were added with a weight of 1.0.

Parameters:
  `reservoirIn` - The reservoir sketch to be merged

#### getResult

    public VarOptItemsSketch<T> getResult()

Gets the varopt sketch resulting from the union of any input sketches.

Returns:
  A varopt sketch

#### reset

    public void reset()

Resets this sketch to the empty state, but retains the original value of max k.

#### toString

    public String toString()

Returns a human-readable summary of the sketch, without items.

Overrides:
  `toString` in class `Object`
Returns:
  A string version of the sketch summary

#### toByteArray

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

Returns a byte array representation of this union

Parameters:
  `serDe` - An instance of ArrayOfItemsSerDe
Returns:
  a byte array representation of this union

#### toByteArray

    public byte[] toByteArray(ArrayOfItemsSerDe<T> serDe,
                              Class<?> clazz)

Returns a byte array representation of this union. This method should be used when the array elements are subclasses of a common base class.

Parameters:
  `serDe` - An instance of ArrayOfItemsSerDe
  `clazz` - A class to which the items are cast before serialization
Returns:
  a byte array representation of this union