Package org.apache.datasketches.sampling

# Class VarOptItemsSamples<T>

java.lang.Object
org.apache.datasketches.sampling.VarOptItemsSamples<T>

Type Parameters:
  `T` - an item of type T

All Implemented Interfaces:
  `Iterable<VarOptItemsSamples<T>.WeightedSample>`

public class VarOptItemsSamples<T> extends Object implements Iterable<VarOptItemsSamples<T>.WeightedSample>
This class provides access to the samples contained in a VarOptItemsSketch. It provides two mechanisms for access:

- An `Iterator` over `WeightedSample` objects which can can be used to access both the items and weights in the sample, and which avoids copying data from the sketch.
- Getter methods to obtain items or weights as arrays, or individual items. These methods create a (shallow) copy of data from the sketch on the first call to any get method.

If using getters with a sketch storing heterogeneous items from a polymorphic base class, you must call `setClass()` prior to calling one of the getter methods. This is not necessary if using the iterator.

The class also implements `Iterable` to allow the use of forEach loops for convenience.

Author:
  Jon Malkin

## Nested Class Summary

Nested Classes
Modifier and Type
Class
Description
`class`
`VarOptItemsSamples.VarOptItemsIterator`
The standard iterator
`final class`
`VarOptItemsSamples.WeightedSample`
A convenience class to allow easy iterator access to a VarOpt sample.

## Method Summary

Modifier and Type
Method
Description
`int`
`getNumSamples()`
Returns the length Copies items and weights from the sketch, if necessary, and returns the length of any resulting array.
`T[]`
`items()`
Returns a shallow copy of the array of sample items contained in the sketch.
`T`
`items(int i)`
Returns a single item from the samples contained in the sketch.
`Iterator<VarOptItemsSamples<T>.WeightedSample>`
`iterator()`
`void`
`setClass(Class<?> clazz)`
Specifies the class to use when copying the item array from the sketch.
`double[]`
`weights()`
Returns a copy of the array of weights contained in the sketch.
`double`
`weights(int i)`
Returns a single weight from the samples contained in the sketch.

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

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

### Methods inherited from interface java.lang.Iterable

`forEach, spliterator`

## Method Details

### iterator

public Iterator<VarOptItemsSamples<T>.WeightedSample> iterator()

Specified by:
  `iterator` in interface `Iterable<T>`

### setClass

public void setClass(Class<?> clazz)
Specifies the class to use when copying the item array from the sketch. This method is required if the sketch stores heterogeneous item types of some base class, for instance a sketch over `Number`s.

Parameters:
  `clazz` - The class to use when creating the item array result

### getNumSamples

public int getNumSamples()
Returns the length Copies items and weights from the sketch, if necessary, and returns the length of any resulting array. The result will be 0 for an empty sketch.

Returns:
  The number of items and weights in the sketch

### items

public T[] items()
Returns a shallow copy of the array of sample items contained in the sketch. If this is the first getter call, copies data arrays from the sketch.

Returns:
  The number of samples contained in the sketch.

### items

public T items(int i)
Returns a single item from the samples contained in the sketch. Does not perform bounds checking on the input. If this is the first getter call, copies data arrays from the sketch.

Parameters:
  `i` - An index into the list of samples
Returns:
  The sample at array position `i`

### weights

public double[] weights()
Returns a copy of the array of weights contained in the sketch. If this is the first getter call, copies data arrays from the sketch.

Returns:
  The number of samples contained in the sketch.

### weights

public double weights(int i)
Returns a single weight from the samples contained in the sketch. Does not perform bounds checking on the input. If this is the first getter call, copies data arrays from the sketch.

Parameters:
  `i` - An index into the list of weights
Returns:
  The weight at array position `i`