diff --git a/src/main/java/org/apache/datasketches/quantilescommon/GenericPartitionBoundaries.java b/src/main/java/org/apache/datasketches/quantilescommon/GenericPartitionBoundaries.java index 0eb44f3e7..f01d136a6 100644 --- a/src/main/java/org/apache/datasketches/quantilescommon/GenericPartitionBoundaries.java +++ b/src/main/java/org/apache/datasketches/quantilescommon/GenericPartitionBoundaries.java @@ -148,7 +148,6 @@ public GenericPartitionBoundaries( * sketch algorithm. * * @return the maximum item of the stream - * @throws IllegalArgumentException if sketch is empty. */ public T getMaxItem() { return maxItem; } @@ -157,7 +156,6 @@ public GenericPartitionBoundaries( * sketch algorithm. * * @return the minimum item of the stream - * @throws IllegalArgumentException if sketch is empty. */ public T getMinItem() { return minItem; } diff --git a/src/main/java/org/apache/datasketches/quantilescommon/PartitioningFeature.java b/src/main/java/org/apache/datasketches/quantilescommon/PartitioningFeature.java index 82b293b3a..75f6fb546 100644 --- a/src/main/java/org/apache/datasketches/quantilescommon/PartitioningFeature.java +++ b/src/main/java/org/apache/datasketches/quantilescommon/PartitioningFeature.java @@ -52,6 +52,7 @@ public interface PartitioningFeature { * * * @return an instance of {@link GenericPartitionBoundaries GenericPartitionBoundaries}. + * @throws IllegalArgumentException if sketch is empty. */ default GenericPartitionBoundaries getPartitionBoundariesFromNumParts(final int numEquallySizedParts) { return getPartitionBoundariesFromNumParts(numEquallySizedParts, INCLUSIVE); @@ -83,6 +84,7 @@ default GenericPartitionBoundaries getPartitionBoundariesFromNumParts(final i * with the exception of the highest returned quantile, which is the upper boundary of the highest ranked partition. * * @return an instance of {@link GenericPartitionBoundaries GenericPartitionBoundaries}. + * @throws IllegalArgumentException if sketch is empty. */ GenericPartitionBoundaries getPartitionBoundariesFromNumParts( int numEquallySizedParts, QuantileSearchCriteria searchCrit); @@ -105,6 +107,7 @@ GenericPartitionBoundaries getPartitionBoundariesFromNumParts( * {@link SketchPartitionLimits#getMinPartitionSizeItems() getMinPartitionSizeItems()} * * @return an instance of {@link GenericPartitionBoundaries GenericPartitionBoundaries}. + * @throws IllegalArgumentException if sketch is empty. */ default GenericPartitionBoundaries getPartitionBoundariesFromPartSize(final long nominalPartSizeItems) { return getPartitionBoundariesFromPartSize(nominalPartSizeItems, INCLUSIVE); @@ -129,6 +132,7 @@ default GenericPartitionBoundaries getPartitionBoundariesFromPartSize(final l * with the exception of the highest returned quantile, which is the upper boundary of the highest ranked partition. * * @return an instance of {@link GenericPartitionBoundaries GenericPartitionBoundaries}. + * @throws IllegalArgumentException if sketch is empty. */ GenericPartitionBoundaries getPartitionBoundariesFromPartSize( long nominalPartSizeItems, QuantileSearchCriteria searchCrit); diff --git a/src/main/java/org/apache/datasketches/quantilescommon/QuantilesDoublesAPI.java b/src/main/java/org/apache/datasketches/quantilescommon/QuantilesDoublesAPI.java index 63ec15284..3b48c2fbe 100644 --- a/src/main/java/org/apache/datasketches/quantilescommon/QuantilesDoublesAPI.java +++ b/src/main/java/org/apache/datasketches/quantilescommon/QuantilesDoublesAPI.java @@ -21,6 +21,8 @@ import static org.apache.datasketches.quantilescommon.QuantileSearchCriteria.INCLUSIVE; +import org.apache.datasketches.common.SketchesArgumentException; + /** * The Quantiles API for item type double. * @see QuantilesAPI @@ -33,7 +35,8 @@ public interface QuantilesDoublesAPI extends QuantilesAPI { * This is equivalent to {@link #getCDF(double[], QuantileSearchCriteria) getCDF(splitPoints, INCLUSIVE)} * @param splitPoints an array of m unique, monotonically increasing items. * @return a discrete CDF array of m+1 double ranks (or cumulative probabilities) on the interval [0.0, 1.0]. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllDoublesSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesDoublesSketch. */ default double[] getCDF(final double[] splitPoints) { return getCDF(splitPoints, INCLUSIVE); @@ -70,7 +73,8 @@ default double[] getCDF(final double[] splitPoints) { * * @param searchCrit the desired search criteria. * @return a discrete CDF array of m+1 double ranks (or cumulative probabilities) on the interval [0.0, 1.0]. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllDoublesSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesDoublesSketch. */ double[] getCDF(double[] splitPoints, QuantileSearchCriteria searchCrit); @@ -79,7 +83,8 @@ default double[] getCDF(final double[] splitPoints) { * item returned by getQuantile(1.0). * * @return the maximum item of the stream - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllDoublesSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesDoublesSketch. */ double getMaxItem(); @@ -88,7 +93,8 @@ default double[] getCDF(final double[] splitPoints) { * item returned by getQuantile(0.0). * * @return the minimum item of the stream - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllDoublesSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesDoublesSketch. */ double getMinItem(); @@ -96,7 +102,8 @@ default double[] getCDF(final double[] splitPoints) { * This is equivalent to {@link #getPMF(double[], QuantileSearchCriteria) getPMF(splitPoints, INCLUSIVE)} * @param splitPoints an array of m unique, monotonically increasing items. * @return a PMF array of m+1 probability masses as doubles on the interval [0.0, 1.0]. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllDoublesSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesDoublesSketch. */ default double[] getPMF(final double[] splitPoints) { return getPMF(splitPoints, INCLUSIVE); @@ -140,7 +147,8 @@ default double[] getPMF(final double[] splitPoints) { * * @param searchCrit the desired search criteria. * @return a PMF array of m+1 probability masses as doubles on the interval [0.0, 1.0]. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllDoublesSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesDoublesSketch. */ double[] getPMF(double[] splitPoints, QuantileSearchCriteria searchCrit); @@ -148,7 +156,8 @@ default double[] getPMF(final double[] splitPoints) { * This is equivalent to {@link #getQuantile(double, QuantileSearchCriteria) getQuantile(rank, INCLUSIVE)} * @param rank the given normalized rank, a double in the range [0.0, 1.0]. * @return the approximate quantile given the normalized rank. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllDoublesSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesDoublesSketch. */ default double getQuantile(final double rank) { return getQuantile(rank, INCLUSIVE); @@ -163,7 +172,8 @@ default double getQuantile(final double rank) { * If EXCLUSIVE, he given rank includes all quantiles < * the quantile directly corresponding to the given rank. * @return the approximate quantile given the normalized rank. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllDoublesSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesDoublesSketch. * @see org.apache.datasketches.quantilescommon.QuantileSearchCriteria */ double getQuantile(double rank, QuantileSearchCriteria searchCrit); @@ -180,7 +190,8 @@ default double getQuantile(final double rank) { * @param rank the given normalized rank * @return the lower bound of the quantile confidence interval in which the quantile of the * given rank exists. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllDoublesSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesDoublesSketch. */ double getQuantileLowerBound(double rank); @@ -196,7 +207,8 @@ default double getQuantile(final double rank) { * @param rank the given normalized rank * @return the upper bound of the quantile confidence interval in which the true quantile of the * given rank exists. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllDoublesSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesDoublesSketch. */ double getQuantileUpperBound(double rank); @@ -205,7 +217,8 @@ default double getQuantile(final double rank) { * @param ranks the given array of normalized ranks, each of which must be * in the interval [0.0,1.0]. * @return an array of quantiles corresponding to the given array of normalized ranks. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllDoublesSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesDoublesSketch. */ default double[] getQuantiles(final double[] ranks) { return getQuantiles(ranks, INCLUSIVE); @@ -219,7 +232,8 @@ default double[] getQuantiles(final double[] ranks) { * @param searchCrit if INCLUSIVE, the given ranks include all quantiles ≤ * the quantile directly corresponding to each rank. * @return an array of quantiles corresponding to the given array of normalized ranks. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllDoublesSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesDoublesSketch. * @see org.apache.datasketches.quantilescommon.QuantileSearchCriteria */ double[] getQuantiles(double[] ranks, QuantileSearchCriteria searchCrit); @@ -228,7 +242,8 @@ default double[] getQuantiles(final double[] ranks) { * This is equivalent to {@link #getRank(double, QuantileSearchCriteria) getRank(quantile, INCLUSIVE)} * @param quantile the given quantile * @return the normalized rank corresponding to the given quantile - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllDoublesSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesDoublesSketch. */ default double getRank(final double quantile) { return getRank(quantile, INCLUSIVE); @@ -240,7 +255,8 @@ default double getRank(final double quantile) { * @param quantile the given quantile * @param searchCrit if INCLUSIVE the given quantile is included into the rank. * @return the normalized rank corresponding to the given quantile - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllDoublesSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesDoublesSketch. * @see org.apache.datasketches.quantilescommon.QuantileSearchCriteria */ double getRank(double quantile, QuantileSearchCriteria searchCrit); @@ -249,7 +265,8 @@ default double getRank(final double quantile) { * This is equivalent to {@link #getRanks(double[], QuantileSearchCriteria) getRanks(quantiles, INCLUSIVE)} * @param quantiles the given array of quantiles * @return an array of normalized ranks corresponding to the given array of quantiles. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllDoublesSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesDoublesSketch. */ default double[] getRanks(final double[] quantiles) { return getRanks(quantiles, INCLUSIVE); @@ -262,7 +279,8 @@ default double[] getRanks(final double[] quantiles) { * @param quantiles the given array of quantiles * @param searchCrit if INCLUSIVE, the given quantiles include the rank directly corresponding to each quantile. * @return an array of normalized ranks corresponding to the given array of quantiles. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllDoublesSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesDoublesSketch. * @see org.apache.datasketches.quantilescommon.QuantileSearchCriteria */ double[] getRanks(double[] quantiles, QuantileSearchCriteria searchCrit); diff --git a/src/main/java/org/apache/datasketches/quantilescommon/QuantilesFloatsAPI.java b/src/main/java/org/apache/datasketches/quantilescommon/QuantilesFloatsAPI.java index 2713e1b02..3b8db77d2 100644 --- a/src/main/java/org/apache/datasketches/quantilescommon/QuantilesFloatsAPI.java +++ b/src/main/java/org/apache/datasketches/quantilescommon/QuantilesFloatsAPI.java @@ -21,6 +21,8 @@ import static org.apache.datasketches.quantilescommon.QuantileSearchCriteria.INCLUSIVE; +import org.apache.datasketches.common.SketchesArgumentException; + /** * The Quantiles API for item type float. * @see QuantilesAPI @@ -32,7 +34,8 @@ public interface QuantilesFloatsAPI extends QuantilesAPI { * This is equivalent to {@link #getCDF(float[], QuantileSearchCriteria) getCDF(splitPoints, INCLUSIVE)} * @param splitPoints an array of m unique, monotonically increasing items. * @return a discrete CDF array of m+1 double ranks (or cumulative probabilities) on the interval [0.0, 1.0]. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllFloatsSketch. + * @throws IllegalArgumentException if sketch is empty and is a ReqSketch. */ default double[] getCDF(final float[] splitPoints) { return getCDF(splitPoints, INCLUSIVE); @@ -69,7 +72,8 @@ default double[] getCDF(final float[] splitPoints) { * * @param searchCrit the desired search criteria. * @return a discrete CDF array of m+1 double ranks (or cumulative probabilities) on the interval [0.0, 1.0]. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllFloatsSketch. + * @throws IllegalArgumentException if sketch is empty and is a ReqSketch. */ double[] getCDF(float[] splitPoints, QuantileSearchCriteria searchCrit); @@ -78,7 +82,8 @@ default double[] getCDF(final float[] splitPoints) { * item retained by the sketch algorithm. * * @return the maximum item of the stream - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllFloatsSketch. + * @throws IllegalArgumentException if sketch is empty and is a ReqSketch. */ float getMaxItem(); @@ -87,7 +92,8 @@ default double[] getCDF(final float[] splitPoints) { * item retained by the sketch algorithm. * * @return the minimum item of the stream - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllFloatsSketch. + * @throws IllegalArgumentException if sketch is empty and is a ReqSketch. */ float getMinItem(); @@ -95,7 +101,8 @@ default double[] getCDF(final float[] splitPoints) { * This is equivalent to {@link #getPMF(float[], QuantileSearchCriteria) getPMF(splitPoints, INCLUSIVE)} * @param splitPoints an array of m unique, monotonically increasing items. * @return a PMF array of m+1 probability masses as doubles on the interval [0.0, 1.0]. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllFloatsSketch. + * @throws IllegalArgumentException if sketch is empty and is a ReqSketch. */ default double[] getPMF(final float[] splitPoints) { return getPMF(splitPoints, INCLUSIVE); @@ -139,7 +146,8 @@ default double[] getPMF(final float[] splitPoints) { * * @param searchCrit the desired search criteria. * @return a PMF array of m+1 probability masses as doubles on the interval [0.0, 1.0]. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllFloatsSketch. + * @throws IllegalArgumentException if sketch is empty and is a ReqSketch. */ double[] getPMF(float[] splitPoints, QuantileSearchCriteria searchCrit); @@ -147,7 +155,8 @@ default double[] getPMF(final float[] splitPoints) { * This is equivalent to {@link #getQuantile(double, QuantileSearchCriteria) getQuantile(rank, INCLUSIVE)} * @param rank the given normalized rank, a double in the range [0.0, 1.0]. * @return the approximate quantile given the normalized rank. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllFloatsSketch. + * @throws IllegalArgumentException if sketch is empty and is a ReqSketch. */ default float getQuantile(final double rank) { return getQuantile(rank, INCLUSIVE); @@ -162,7 +171,8 @@ default float getQuantile(final double rank) { * If EXCLUSIVE, he given rank includes all quantiles < * the quantile directly corresponding to the given rank. * @return the approximate quantile given the normalized rank. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllFloatsSketch. + * @throws IllegalArgumentException if sketch is empty and is a ReqSketch. * @see org.apache.datasketches.quantilescommon.QuantileSearchCriteria */ float getQuantile(double rank, QuantileSearchCriteria searchCrit); @@ -179,7 +189,8 @@ default float getQuantile(final double rank) { * @param rank the given normalized rank * @return the lower bound of the quantile confidence interval in which the quantile of the * given rank exists. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllFloatsSketch. + * @throws IllegalArgumentException if sketch is empty and is a ReqSketch. */ float getQuantileLowerBound(double rank); @@ -195,7 +206,8 @@ default float getQuantile(final double rank) { * @param rank the given normalized rank * @return the upper bound of the quantile confidence interval in which the true quantile of the * given rank exists. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllFloatsSketch. + * @throws IllegalArgumentException if sketch is empty and is a ReqSketch. */ float getQuantileUpperBound(double rank); @@ -204,7 +216,8 @@ default float getQuantile(final double rank) { * @param ranks the given array of normalized ranks, each of which must be * in the interval [0.0,1.0]. * @return an array of quantiles corresponding to the given array of normalized ranks. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllFloatsSketch. + * @throws IllegalArgumentException if sketch is empty and is a ReqSketch. */ default float[] getQuantiles(final double[] ranks) { return getQuantiles(ranks, INCLUSIVE); @@ -218,7 +231,8 @@ default float[] getQuantiles(final double[] ranks) { * @param searchCrit if INCLUSIVE, the given ranks include all quantiles ≤ * the quantile directly corresponding to each rank. * @return an array of quantiles corresponding to the given array of normalized ranks. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllFloatsSketch. + * @throws IllegalArgumentException if sketch is empty and is a ReqSketch. * @see org.apache.datasketches.quantilescommon.QuantileSearchCriteria */ float[] getQuantiles(double[] ranks, QuantileSearchCriteria searchCrit); @@ -227,7 +241,8 @@ default float[] getQuantiles(final double[] ranks) { * This is equivalent to {@link #getRank(float, QuantileSearchCriteria) getRank(quantile, INCLUSIVE)} * @param quantile the given quantile * @return the normalized rank corresponding to the given quantile. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllFloatsSketch. + * @throws IllegalArgumentException if sketch is empty and is a ReqSketch. */ default double getRank(final float quantile) { return getRank(quantile, INCLUSIVE); @@ -239,7 +254,8 @@ default double getRank(final float quantile) { * @param quantile the given quantile * @param searchCrit if INCLUSIVE the given quantile is included into the rank. * @return the normalized rank corresponding to the given quantile. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllFloatsSketch. + * @throws IllegalArgumentException if sketch is empty and is a ReqSketch. * @see org.apache.datasketches.quantilescommon.QuantileSearchCriteria */ double getRank(float quantile, QuantileSearchCriteria searchCrit); @@ -248,7 +264,8 @@ default double getRank(final float quantile) { * This is equivalent to {@link #getRanks(float[], QuantileSearchCriteria) getRanks(quantiles, INCLUSIVE)} * @param quantiles the given array of quantiles * @return an array of normalized ranks corresponding to the given array of quantiles. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllFloatsSketch. + * @throws IllegalArgumentException if sketch is empty and is a ReqSketch. */ default double[] getRanks(final float[] quantiles) { return getRanks(quantiles, INCLUSIVE); @@ -261,7 +278,8 @@ default double[] getRanks(final float[] quantiles) { * @param quantiles the given array of quantiles * @param searchCrit if INCLUSIVE, the given quantiles include the rank directly corresponding to each quantile. * @return an array of normalized ranks corresponding to the given array of quantiles. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllFloatsSketch. + * @throws IllegalArgumentException if sketch is empty and is a ReqSketch. * @see org.apache.datasketches.quantilescommon.QuantileSearchCriteria */ double[] getRanks(float[] quantiles, QuantileSearchCriteria searchCrit); diff --git a/src/main/java/org/apache/datasketches/quantilescommon/QuantilesGenericAPI.java b/src/main/java/org/apache/datasketches/quantilescommon/QuantilesGenericAPI.java index 6251a9596..3efd04b9a 100644 --- a/src/main/java/org/apache/datasketches/quantilescommon/QuantilesGenericAPI.java +++ b/src/main/java/org/apache/datasketches/quantilescommon/QuantilesGenericAPI.java @@ -24,6 +24,8 @@ import java.util.Comparator; +import org.apache.datasketches.common.SketchesArgumentException; + /** * The Quantiles API for item type generic. * @see QuantilesAPI @@ -36,7 +38,8 @@ public interface QuantilesGenericAPI extends QuantilesAPI, PartitioningFeatur * This is equivalent to {@link #getCDF(Object[], QuantileSearchCriteria) getCDF(splitPoints, INCLUSIVE)} * @param splitPoints an array of m unique, monotonically increasing items. * @return a discrete CDF array of m+1 double ranks (or cumulative probabilities) on the interval [0.0, 1.0]. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllItemsSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesItemsSketch. */ default double[] getCDF(final T[] splitPoints) { return getCDF(splitPoints, INCLUSIVE); @@ -73,7 +76,8 @@ default double[] getCDF(final T[] splitPoints) { * * @param searchCrit the desired search criteria. * @return a discrete CDF array of m+1 double ranks (or cumulative probabilities) on the interval [0.0, 1.0]. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllItemsSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesItemsSketch. */ double[] getCDF(T[] splitPoints, QuantileSearchCriteria searchCrit); @@ -94,7 +98,8 @@ default double[] getCDF(final T[] splitPoints) { * sketch algorithm. * * @return the maximum item of the stream - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllItemsSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesItemsSketch. */ T getMaxItem(); @@ -108,7 +113,8 @@ default int getMaxPartitions() { * sketch algorithm. * * @return the minimum item of the stream - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllItemsSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesItemsSketch. */ T getMinItem(); @@ -116,7 +122,8 @@ default int getMaxPartitions() { * This is equivalent to {@link #getPMF(Object[], QuantileSearchCriteria) getPMF(splitPoints, INCLUSIVE)} * @param splitPoints an array of m unique, monotonically increasing items. * @return a PMF array of m+1 probability masses as doubles on the interval [0.0, 1.0]. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllItemsSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesItemsSketch. */ default double[] getPMF(final T[] splitPoints) { return getPMF(splitPoints, INCLUSIVE); @@ -160,7 +167,8 @@ default double[] getPMF(final T[] splitPoints) { * * @param searchCrit the desired search criteria. * @return a PMF array of m+1 probability masses as doubles on the interval [0.0, 1.0]. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllItemsSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesItemsSketch. */ double[] getPMF(T[] splitPoints, QuantileSearchCriteria searchCrit); @@ -168,7 +176,8 @@ default double[] getPMF(final T[] splitPoints) { * This is equivalent to {@link #getQuantile(double, QuantileSearchCriteria) getQuantile(rank, INCLUSIVE)} * @param rank the given normalized rank, a double in the range [0.0, 1.0]. * @return the approximate quantile given the normalized rank. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllItemsSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesItemsSketch. */ default T getQuantile(final double rank) { return getQuantile(rank, INCLUSIVE); @@ -183,7 +192,8 @@ default T getQuantile(final double rank) { * If EXCLUSIVE, he given rank includes all quantiles < * the quantile directly corresponding to the given rank. * @return the approximate quantile given the normalized rank. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllItemsSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesItemsSketch. * @see org.apache.datasketches.quantilescommon.QuantileSearchCriteria */ T getQuantile(double rank, QuantileSearchCriteria searchCrit); @@ -200,7 +210,8 @@ default T getQuantile(final double rank) { * @param rank the given normalized rank * @return the lower bound of the quantile confidence interval in which the quantile of the * given rank exists. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllItemsSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesItemsSketch. */ T getQuantileLowerBound(double rank); @@ -216,7 +227,8 @@ default T getQuantile(final double rank) { * @param rank the given normalized rank * @return the upper bound of the quantile confidence interval in which the true quantile of the * given rank exists. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllItemsSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesItemsSketch. */ T getQuantileUpperBound(double rank); @@ -225,7 +237,8 @@ default T getQuantile(final double rank) { * @param ranks the given array of normalized ranks, each of which must be * in the interval [0.0,1.0]. * @return an array of quantiles corresponding to the given array of normalized ranks. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllItemsSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesItemsSketch. */ default T[] getQuantiles(final double[] ranks) { return getQuantiles(ranks, INCLUSIVE); @@ -239,7 +252,8 @@ default T[] getQuantiles(final double[] ranks) { * @param searchCrit if INCLUSIVE, the given ranks include all quantiles ≤ * the quantile directly corresponding to each rank. * @return an array of quantiles corresponding to the given array of normalized ranks. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllItemsSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesItemsSketch. * @see org.apache.datasketches.quantilescommon.QuantileSearchCriteria */ T[] getQuantiles(double[] ranks, QuantileSearchCriteria searchCrit); @@ -248,7 +262,8 @@ default T[] getQuantiles(final double[] ranks) { * This is equivalent to {@link #getRank(Object, QuantileSearchCriteria) getRank(T quantile, INCLUSIVE)} * @param quantile the given quantile * @return the normalized rank corresponding to the given quantile. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllItemsSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesItemsSketch. */ default double getRank(final T quantile) { return getRank(quantile, INCLUSIVE); @@ -260,7 +275,8 @@ default double getRank(final T quantile) { * @param quantile the given quantile * @param searchCrit if INCLUSIVE the given quantile is included into the rank. * @return the normalized rank corresponding to the given quantile. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllItemsSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesItemsSketch. * @see org.apache.datasketches.quantilescommon.QuantileSearchCriteria */ double getRank(T quantile, QuantileSearchCriteria searchCrit); @@ -269,7 +285,8 @@ default double getRank(final T quantile) { * This is equivalent to {@link #getRanks(Object[], QuantileSearchCriteria) getRanks(quantiles, INCLUSIVE)} * @param quantiles the given array of quantiles * @return an array of normalized ranks corresponding to the given array of quantiles. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllItemsSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesItemsSketch. */ default double[] getRanks(final T[] quantiles) { return getRanks(quantiles, INCLUSIVE); @@ -282,7 +299,8 @@ default double[] getRanks(final T[] quantiles) { * @param quantiles the given array of quantiles * @param searchCrit if INCLUSIVE, the given quantiles include the rank directly corresponding to each quantile. * @return an array of normalized ranks corresponding to the given array of quantiles. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty and is a KllItemsSketch. + * @throws IllegalArgumentException if sketch is empty and is a QuantilesItemsSketch. * @see org.apache.datasketches.quantilescommon.QuantileSearchCriteria */ double[] getRanks(T[] quantiles, QuantileSearchCriteria searchCrit); diff --git a/src/main/java/org/apache/datasketches/quantilescommon/QuantilesLongsAPI.java b/src/main/java/org/apache/datasketches/quantilescommon/QuantilesLongsAPI.java index 51802df71..8edc4bc55 100644 --- a/src/main/java/org/apache/datasketches/quantilescommon/QuantilesLongsAPI.java +++ b/src/main/java/org/apache/datasketches/quantilescommon/QuantilesLongsAPI.java @@ -21,6 +21,8 @@ import static org.apache.datasketches.quantilescommon.QuantileSearchCriteria.INCLUSIVE; +import org.apache.datasketches.common.SketchesArgumentException; + /** * The Quantiles API for item type long. * @see QuantilesAPI @@ -33,7 +35,7 @@ public interface QuantilesLongsAPI extends QuantilesAPI { * This is equivalent to {@link #getCDF(long[], QuantileSearchCriteria) getCDF(splitPoints, INCLUSIVE)} * @param splitPoints an array of m unique, monotonically increasing items. * @return a discrete CDF array of m+1 double ranks (or cumulative probabilities) on the interval [0.0, 1.0]. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty. */ default double[] getCDF(final long[] splitPoints) { return getCDF(splitPoints, INCLUSIVE); @@ -70,7 +72,7 @@ default double[] getCDF(final long[] splitPoints) { * * @param searchCrit the desired search criteria. * @return a discrete CDF array of m+1 double ranks (or cumulative probabilities) on the interval [0.0, 1.0]. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty. */ double[] getCDF(long[] splitPoints, QuantileSearchCriteria searchCrit); @@ -79,7 +81,7 @@ default double[] getCDF(final long[] splitPoints) { * item returned by getQuantile(1.0). * * @return the maximum item of the stream - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty. */ long getMaxItem(); @@ -88,7 +90,7 @@ default double[] getCDF(final long[] splitPoints) { * item returned by getQuantile(0.0). * * @return the minimum item of the stream - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty. */ long getMinItem(); @@ -96,7 +98,7 @@ default double[] getCDF(final long[] splitPoints) { * This is equivalent to {@link #getPMF(long[], QuantileSearchCriteria) getPMF(splitPoints, INCLUSIVE)} * @param splitPoints an array of m unique, monotonically increasing items. * @return a PMF array of m+1 probability masses as doubles on the interval [0.0, 1.0]. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty. */ default double[] getPMF(final long[] splitPoints) { return getPMF(splitPoints, INCLUSIVE); @@ -140,7 +142,7 @@ default double[] getPMF(final long[] splitPoints) { * * @param searchCrit the desired search criteria. * @return a PMF array of m+1 probability masses as doubles on the interval [0.0, 1.0]. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty. */ double[] getPMF(long[] splitPoints, QuantileSearchCriteria searchCrit); @@ -148,7 +150,7 @@ default double[] getPMF(final long[] splitPoints) { * This is equivalent to {@link #getQuantile(double, QuantileSearchCriteria) getQuantile(rank, INCLUSIVE)} * @param rank the given normalized rank, a double in the range [0.0, 1.0]. * @return the approximate quantile given the normalized rank. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty. */ default long getQuantile(final double rank) { return getQuantile(rank, INCLUSIVE); @@ -163,7 +165,7 @@ default long getQuantile(final double rank) { * If EXCLUSIVE, he given rank includes all quantiles < * the quantile directly corresponding to the given rank. * @return the approximate quantile given the normalized rank. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty. * @see org.apache.datasketches.quantilescommon.QuantileSearchCriteria */ long getQuantile(double rank, QuantileSearchCriteria searchCrit); @@ -180,7 +182,7 @@ default long getQuantile(final double rank) { * @param rank the given normalized rank * @return the lower bound of the quantile confidence interval in which the quantile of the * given rank exists. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty. */ long getQuantileLowerBound(double rank); @@ -196,7 +198,7 @@ default long getQuantile(final double rank) { * @param rank the given normalized rank * @return the upper bound of the quantile confidence interval in which the true quantile of the * given rank exists. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty. */ long getQuantileUpperBound(double rank); @@ -205,7 +207,7 @@ default long getQuantile(final double rank) { * @param ranks the given array of normalized ranks, each of which must be * in the interval [0.0,1.0]. * @return an array of quantiles corresponding to the given array of normalized ranks. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty. */ default long[] getQuantiles(final double[] ranks) { return getQuantiles(ranks, INCLUSIVE); @@ -219,7 +221,7 @@ default long[] getQuantiles(final double[] ranks) { * @param searchCrit if INCLUSIVE, the given ranks include all quantiles ≤ * the quantile directly corresponding to each rank. * @return an array of quantiles corresponding to the given array of normalized ranks. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty. * @see org.apache.datasketches.quantilescommon.QuantileSearchCriteria */ long[] getQuantiles(double[] ranks, QuantileSearchCriteria searchCrit); @@ -228,7 +230,7 @@ default long[] getQuantiles(final double[] ranks) { * This is equivalent to {@link #getRank(long, QuantileSearchCriteria) getRank(quantile, INCLUSIVE)} * @param quantile the given quantile * @return the normalized rank corresponding to the given quantile - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty. */ default double getRank(final long quantile) { return getRank(quantile, INCLUSIVE); @@ -240,7 +242,7 @@ default double getRank(final long quantile) { * @param quantile the given quantile * @param searchCrit if INCLUSIVE the given quantile is included into the rank. * @return the normalized rank corresponding to the given quantile - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty. * @see org.apache.datasketches.quantilescommon.QuantileSearchCriteria */ double getRank(long quantile, QuantileSearchCriteria searchCrit); @@ -249,7 +251,7 @@ default double getRank(final long quantile) { * This is equivalent to {@link #getRanks(long[], QuantileSearchCriteria) getRanks(quantiles, INCLUSIVE)} * @param quantiles the given array of quantiles * @return an array of normalized ranks corresponding to the given array of quantiles. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty. */ default double[] getRanks(final long[] quantiles) { return getRanks(quantiles, INCLUSIVE); @@ -262,7 +264,7 @@ default double[] getRanks(final long[] quantiles) { * @param quantiles the given array of quantiles * @param searchCrit if INCLUSIVE, the given quantiles include the rank directly corresponding to each quantile. * @return an array of normalized ranks corresponding to the given array of quantiles. - * @throws IllegalArgumentException if sketch is empty. + * @throws SketchesArgumentException if sketch is empty. * @see org.apache.datasketches.quantilescommon.QuantileSearchCriteria */ double[] getRanks(long[] quantiles, QuantileSearchCriteria searchCrit);