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.
    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 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 update​(double dataItem)
    Update this union with the given double (or float) data Item.
    abstract void update​(org.apache.datasketches.memory.Memory mem)
    Iterative union operation, which means this method can be repeatedly called.
    abstract void update​(DoublesSketch sketchIn)
    Iterative union operation, which means this method can be repeatedly called.
    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

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

  • Constructor Details

  • 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

    • isEmpty

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

    • isDirect

      public abstract boolean isDirect()
      Returns true if this union is direct
      Returns:
      true if this union is direct

    • 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.

    • update

      public abstract void update​(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 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 abstract void update​(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 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:
      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.