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.numbers.examples.jmh.arrays;
18
19 /**
20 * Defines a transformer for {@code double[]} 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.
24 *
25 * <p>The transformer allows pre-processing data before applying a sort algorithm.
26 * This is required to handle {@code NaN} and signed-zeros {@code -0.0}.
27 *
28 * <p>Note: The {@code <} relation does not provide a total order on all double
29 * values: {@code -0.0 == 0.0} is {@code true} and a {@code NaN}
30 * value compares neither less than, greater than, nor equal to any value,
31 * even itself.
32 *
33 * <p>The {@link java.util.Arrays#sort(double[])} method respects the order imposed by
34 * {@link Double#compare(double, double)}: {@code -0.0} is treated as less than value
35 * {@code 0.0} and {@code Double.NaN} is considered greater than any
36 * other value and all {@code Double.NaN} values are considered equal.
37 *
38 * <p>This interface allows implementations to respect the behaviour
39 * {@link Double#compare(double, double)}, or implement different behaviour.
40 *
41 * @see java.util.Arrays#sort(double[])
42 * @since 1.2
43 */
44 interface DoubleDataTransformer {
45 /**
46 * Pre-process the data for partitioning.
47 *
48 * <p>This method will scan all the data and apply
49 * processing to {@code NaN} and signed-zeros {@code -0.0}.
50 *
51 * <p>A method matching {@link java.util.Arrays#sort(double[])} would move
52 * all {@code NaN} to the end of the array and order zeros. However ordering
53 * zeros is not useful if the data is to be fully or partially reordered
54 * by the caller. Possible solutions are to count signed zeros, or ignore them since
55 * they will not interfere with comparison operators {@code <, ==, >}.
56 *
57 * <p>The length of the data that must be processed by partitioning can be
58 * accessed using {@link #length()}. For example if {@code NaN} values are moved
59 * to the end of the data they are already partitioned. A partition algorithm
60 * can then avoid processing {@code NaN} during partitioning.
61 *
62 * @param data Data.
63 * @return pre-processed data (may be a copy)
64 */
65 double[] preProcess(double[] data);
66
67 /**
68 * Get the size of the data.
69 *
70 * <p>Note: Although the pre-processed data array may be longer than this length some
71 * values may have been excluded from the data (e.g. removal of NaNs). This is the
72 * effective size of the data.
73 *
74 * @return the size
75 */
76 int size();
77
78 /**
79 * Get the length of the pre-processed data that must be partitioned.
80 *
81 * <p>Note: Although the pre-processed data array may be longer than this length it is
82 * only required to partition indices below this length. For example the end of the
83 * array may contain values to ignore from partitioning such as {@code NaN}.
84 *
85 * @return the length
86 */
87 int length();
88
89 /**
90 * Post-process the data after partitioning. This method can restore values that
91 * may have been removed from the pre-processed data, for example signed zeros
92 * or revert any special {@code NaN} value processing.
93 *
94 * <p>If no partition indices are available use {@code null} and {@code n = 0}.
95 *
96 * @param data Data.
97 * @param k Partition indices.
98 * @param n Count of partition indices.
99 */
100 void postProcess(double[] data, int[] k, int n);
101
102 /**
103 * Post-process the data after sorting. This method can restore values that
104 * may have been removed from the pre-processed data, for example signed zeros
105 * or revert any special {@code NaN} value processing.
106 *
107 * <p>Warning: Assumes data is fully sorted in {@code [0, length)} (see {@link #length()}).
108 *
109 * @param data Data.
110 */
111 void postProcess(double[] data);
112 }