1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 package org.apache.commons.statistics.descriptive; 18 19 /** 20 * Defines a transformer for {@code NaN} values in arrays. 21 * 22 * <p>This interface is not intended for a public API. It provides a consistent method 23 * to handle partial sorting of {@code double[]} data in the {@link Median} and 24 * {@link Quantile} classes. 25 * 26 * <p>The transformer allows pre-processing floating-point data before applying a sort algorithm. 27 * This is required to handle {@code NaN}. 28 * 29 * <p>Note: The {@code <} relation does not provide a total order on all double 30 * values: {@code -0.0 == 0.0} is {@code true} and a {@code NaN} 31 * value compares neither less than, greater than, nor equal to any value, 32 * even itself. 33 * 34 * <p>The {@link Double#compare(double, double)} method imposes the ordering: 35 * {@code -0.0} is treated as less than value 36 * {@code 0.0} and {@code Double.NaN} is considered greater than any 37 * other value and all {@code Double.NaN} values are considered equal. 38 * 39 * <p>This interface allows implementations to respect the behaviour of 40 * {@link Double#compare(double, double)}, or implement different behaviour. 41 */ 42 @FunctionalInterface 43 interface NaNTransformer { 44 /** 45 * Pre-process the data for partitioning. 46 * 47 * <p>This method will scan all the data and apply processing to {@code NaN} values. 48 * 49 * <p>The method will return: 50 * <ul> 51 * <li>An array to partition; this may be a copy. 52 * <li>The {@code bounds} of the returned data as [start, end); this can be smaller than the 53 * input range if the transformer is configured to exclude NaN values. The start is inclusive 54 * and the end is exclusive. 55 * </ul> 56 * 57 * <p>Implementations may assume the input {@code [from, to)} range is valid given the 58 * length of the {@code data} array. 59 * 60 * @param data Data. 61 * @param from Inclusive start of the range. 62 * @param to Exclusive end of the range. 63 * @param bounds Set to [start, end). 64 * @return pre-processed data (may be a copy) 65 */ 66 double[] apply(double[] data, int from, int to, int[] bounds); 67 }