Package org.apache.datasketches.quantiles

# Class DoublesUnion

java.lang.Object
org.apache.datasketches.quantiles.DoublesUnion

public abstract class DoublesUnion extends Object
The API for Union operations for quantiles DoublesSketches

Author:
  Lee Rhodes

## Constructor Summary

Constructors
Constructor
Description
`DoublesUnion()`

## Method Summary

Modifier and Type
Method
Description
`static DoublesUnionBuilder`
`builder()`
Returns a new UnionBuilder
`abstract int`
`getEffectiveK()`
Returns the effective k of this Union.
`abstract int`
`getMaxK()`
Returns the configured maxK of this Union.
`abstract UpdateDoublesSketch`
`getResult()`
Gets the result of this Union as an UpdateDoublesSketch, which enables further update operations on the resulting sketch.
`abstract UpdateDoublesSketch`
`getResult(org.apache.datasketches.memory.WritableMemory dstMem)`
Places the result of this Union into the provided memory as an UpdateDoublesSketch, which enables further update operations on the resulting sketch.
`abstract UpdateDoublesSketch`
`getResultAndReset()`
Gets the result of this Union as an UpdateDoublesSketch, which enables further update operations on the resulting sketch.
`abstract boolean`
`hasMemory()`
Returns true if this union's data structure is backed by Memory or WritableMemory.
`static DoublesUnion`
`heapify(org.apache.datasketches.memory.Memory srcMem)`
Returns a Heap Union object that has been initialized with the data from the given memory image of a sketch.
`static DoublesUnion`
`heapify(DoublesSketch sketch)`
Returns a Heap Union object that has been initialized with the data from the given sketch.
`abstract boolean`
`isDirect()`
Returns true if this union is off-heap (direct)
`abstract boolean`
`isEmpty()`
Returns true if this union is empty
`abstract boolean`
`isSameResource(org.apache.datasketches.memory.Memory that)`
Returns true if the backing resource of this is identical with the backing resource of that.
`abstract void`
`reset()`
Resets this Union to a virgin state.
`abstract byte[]`
`toByteArray()`
Serialize this union to a byte array.
`abstract String`
`toString()`
Returns summary information about the backing sketch.
`abstract String`
`toString(boolean sketchSummary, boolean dataDetail)`
Returns summary information about the backing sketch.
`abstract void`
`union(org.apache.datasketches.memory.Memory mem)`
Iterative union operation, which means this method can be repeatedly called.
`abstract void`
`union(DoublesSketch sketchIn)`
Iterative union operation, which means this method can be repeatedly called.
`abstract void`
`update(double dataItem)`
Update this union with the given double (or float) data Item.
`static DoublesUnion`
`wrap(org.apache.datasketches.memory.Memory mem)`
Returns a read-only Union object that wraps off-heap data of the given memory image of a sketch.
`static DoublesUnion`
`wrap(org.apache.datasketches.memory.WritableMemory mem)`
Returns an updatable Union object that wraps off-heap data of the given memory image of a sketch.

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

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

## Constructor Details

### DoublesUnion

public DoublesUnion()

## Method Details

### builder

public static DoublesUnionBuilder builder()
Returns a new UnionBuilder

Returns:
  a new UnionBuilder

### heapify

public static DoublesUnion heapify(DoublesSketch sketch)
Returns a Heap Union object that has been initialized with the data from the given sketch.

Parameters:
  `sketch` - A DoublesSketch to be used as a source of data only and will not be modified.
Returns:
  a DoublesUnion object

### heapify

public static DoublesUnion heapify(org.apache.datasketches.memory.Memory srcMem)
Returns a Heap Union object that has been initialized with the data from the given memory image of a sketch.

Parameters:
  `srcMem` - A memory image of a DoublesSketch to be used as a source of data, but will not be modified.
Returns:
  a Union object

### wrap

public static DoublesUnion wrap(org.apache.datasketches.memory.Memory mem)
Returns a read-only Union object that wraps off-heap data of the given memory image of a sketch. The data structures of the Union remain off-heap.

Parameters:
  `mem` - A memory region to be used as the data structure for the sketch and will be modified.
Returns:
  a Union object

### wrap

public static DoublesUnion wrap(org.apache.datasketches.memory.WritableMemory mem)
Returns an updatable Union object that wraps off-heap data of the given memory image of a sketch. The data structures of the Union remain off-heap.

Parameters:
  `mem` - A memory region to be used as the data structure for the sketch and will be modified.
Returns:
  a Union object

### hasMemory

public abstract boolean hasMemory()
Returns true if this union's data structure is backed by Memory or WritableMemory.

Returns:
  true if this union's data structure is backed by Memory or WritableMemory.

### isDirect

public abstract boolean isDirect()
Returns true if this union is off-heap (direct)

Returns:
  true if this union is off-heap (direct)

### isEmpty

public abstract boolean isEmpty()
Returns true if this union is empty

Returns:
  true if this union is empty

### getMaxK

public abstract int getMaxK()
Returns the configured maxK of this Union.

Returns:
  the configured maxK of this Union.

### getEffectiveK

public abstract int getEffectiveK()
Returns the effective k of this Union.

Returns:
  the effective k of this Union.

### union

public abstract void union(DoublesSketch 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 abstract void union(org.apache.datasketches.memory.Memory mem)
Iterative union operation, which means this method can be repeatedly called. Merges the given Memory image of a DoublesSketch 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:
  `mem` - Memory image of sketch to be merged

### update

public abstract void update(double dataItem)
Update this union with the given double (or float) data Item.

Parameters:
  `dataItem` - The given double datum.

### getResult

public abstract UpdateDoublesSketch getResult()
Gets the result of this Union as an UpdateDoublesSketch, which enables further update operations on the resulting sketch. The Union state has not been changed, which allows further union operations.

Returns:
  the result of this Union operation

### getResult

public abstract UpdateDoublesSketch getResult(org.apache.datasketches.memory.WritableMemory dstMem)
Places the result of this Union into the provided memory as an UpdateDoublesSketch, which enables further update operations on the resulting sketch. The Union state has not been changed, which allows further union operations.

Parameters:
  `dstMem` - the destination memory for the result
Returns:
  the result of this Union operation

### getResultAndReset

public abstract UpdateDoublesSketch getResultAndReset()
Gets the result of this Union as an UpdateDoublesSketch, which enables further update operations on the resulting sketch. The Union is reset to the virgin state.

Returns:
  the result of this Union operation and reset.

### reset

public abstract void reset()
Resets this Union to a virgin state.

### toByteArray

public abstract byte[] toByteArray()
Serialize this union to a byte array. Result is an UpdateDoublesSketch, serialized in an unordered, non-compact form. The resulting byte[] can be heapified or wrapped as either a sketch or a union.

Returns:
  byte array of this union

### toString

public abstract String toString()
Returns summary information about the backing sketch.

Overrides:
  `toString` in class `Object`

### toString

public abstract 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.

### isSameResource

public abstract boolean isSameResource(org.apache.datasketches.memory.Memory that)
Returns true if the backing resource of this is identical with the backing resource of that. The capacities must be the same. If this is a region, the region offset must also be the same.

Parameters:
  `that` - A different non-null object
Returns:
  true if the backing resource of this is the same as the backing resource of that.