001    /*
002     * Copyright (C) 2008 The Guava Authors
003     *
004     * Licensed under the Apache License, Version 2.0 (the "License");
005     * you may not use this file except in compliance with the License.
006     * You may obtain a copy of the License at
007     *
008     * http://www.apache.org/licenses/LICENSE-2.0
009     *
010     * Unless required by applicable law or agreed to in writing, software
011     * distributed under the License is distributed on an "AS IS" BASIS,
012     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013     * See the License for the specific language governing permissions and
014     * limitations under the License.
015     */
016    
017    package com.google.common.primitives;
018    
019    import static com.google.common.base.Preconditions.checkArgument;
020    import static com.google.common.base.Preconditions.checkElementIndex;
021    import static com.google.common.base.Preconditions.checkNotNull;
022    import static com.google.common.base.Preconditions.checkPositionIndexes;
023    import static java.lang.Double.NEGATIVE_INFINITY;
024    import static java.lang.Double.POSITIVE_INFINITY;
025    
026    import com.google.common.annotations.GwtCompatible;
027    
028    import java.io.Serializable;
029    import java.util.AbstractList;
030    import java.util.Arrays;
031    import java.util.Collection;
032    import java.util.Collections;
033    import java.util.Comparator;
034    import java.util.List;
035    import java.util.RandomAccess;
036    
037    /**
038     * Static utility methods pertaining to {@code double} primitives, that are not
039     * already found in either {@link Double} or {@link Arrays}.
040     *
041     * <p>See the Guava User Guide article on <a href=
042     * "http://code.google.com/p/guava-libraries/wiki/PrimitivesExplained">
043     * primitive utilities</a>.
044     *
045     * @author Kevin Bourrillion
046     * @since 1.0
047     */
048    @GwtCompatible
049    public final class Doubles {
050      private Doubles() {}
051    
052      /**
053       * The number of bytes required to represent a primitive {@code double}
054       * value.
055       *
056       * @since 10.0
057       */
058      public static final int BYTES = Double.SIZE / Byte.SIZE;
059    
060      /**
061       * Returns a hash code for {@code value}; equal to the result of invoking
062       * {@code ((Double) value).hashCode()}.
063       *
064       * @param value a primitive {@code double} value
065       * @return a hash code for the value
066       */
067      public static int hashCode(double value) {
068        return ((Double) value).hashCode();
069        // TODO(kevinb): do it this way when we can (GWT problem):
070        // long bits = Double.doubleToLongBits(value);
071        // return (int)(bits ^ (bits >>> 32));
072      }
073    
074      /**
075       * Compares the two specified {@code double} values. The sign of the value
076       * returned is the same as that of <code>((Double) a).{@linkplain
077       * Double#compareTo compareTo}(b)</code>. As with that method, {@code NaN} is
078       * treated as greater than all other values, and {@code 0.0 > -0.0}.
079       *
080       * @param a the first {@code double} to compare
081       * @param b the second {@code double} to compare
082       * @return a negative value if {@code a} is less than {@code b}; a positive
083       *     value if {@code a} is greater than {@code b}; or zero if they are equal
084       */
085      public static int compare(double a, double b) {
086        return Double.compare(a, b);
087      }
088    
089      /**
090       * Returns {@code true} if {@code value} represents a real number. This is
091       * equivalent to, but not necessarily implemented as,
092       * {@code !(Double.isInfinite(value) || Double.isNaN(value))}.
093       *
094       * @since 10.0
095       */
096      public static boolean isFinite(double value) {
097        return NEGATIVE_INFINITY < value & value < POSITIVE_INFINITY;
098      }
099    
100      /**
101       * Returns {@code true} if {@code target} is present as an element anywhere in
102       * {@code array}. Note that this always returns {@code false} when {@code
103       * target} is {@code NaN}.
104       *
105       * @param array an array of {@code double} values, possibly empty
106       * @param target a primitive {@code double} value
107       * @return {@code true} if {@code array[i] == target} for some value of {@code
108       *     i}
109       */
110      public static boolean contains(double[] array, double target) {
111        for (double value : array) {
112          if (value == target) {
113            return true;
114          }
115        }
116        return false;
117      }
118    
119      /**
120       * Returns the index of the first appearance of the value {@code target} in
121       * {@code array}. Note that this always returns {@code -1} when {@code target}
122       * is {@code NaN}.
123       *
124       * @param array an array of {@code double} values, possibly empty
125       * @param target a primitive {@code double} value
126       * @return the least index {@code i} for which {@code array[i] == target}, or
127       *     {@code -1} if no such index exists.
128       */
129      public static int indexOf(double[] array, double target) {
130        return indexOf(array, target, 0, array.length);
131      }
132    
133      // TODO(kevinb): consider making this public
134      private static int indexOf(
135          double[] array, double target, int start, int end) {
136        for (int i = start; i < end; i++) {
137          if (array[i] == target) {
138            return i;
139          }
140        }
141        return -1;
142      }
143    
144      /**
145       * Returns the start position of the first occurrence of the specified {@code
146       * target} within {@code array}, or {@code -1} if there is no such occurrence.
147       *
148       * <p>More formally, returns the lowest index {@code i} such that {@code
149       * java.util.Arrays.copyOfRange(array, i, i + target.length)} contains exactly
150       * the same elements as {@code target}.
151       *
152       * <p>Note that this always returns {@code -1} when {@code target} contains
153       * {@code NaN}.
154       *
155       * @param array the array to search for the sequence {@code target}
156       * @param target the array to search for as a sub-sequence of {@code array}
157       */
158      public static int indexOf(double[] array, double[] target) {
159        checkNotNull(array, "array");
160        checkNotNull(target, "target");
161        if (target.length == 0) {
162          return 0;
163        }
164    
165        outer:
166        for (int i = 0; i < array.length - target.length + 1; i++) {
167          for (int j = 0; j < target.length; j++) {
168            if (array[i + j] != target[j]) {
169              continue outer;
170            }
171          }
172          return i;
173        }
174        return -1;
175      }
176    
177      /**
178       * Returns the index of the last appearance of the value {@code target} in
179       * {@code array}. Note that this always returns {@code -1} when {@code target}
180       * is {@code NaN}.
181       *
182       * @param array an array of {@code double} values, possibly empty
183       * @param target a primitive {@code double} value
184       * @return the greatest index {@code i} for which {@code array[i] == target},
185       *     or {@code -1} if no such index exists.
186       */
187      public static int lastIndexOf(double[] array, double target) {
188        return lastIndexOf(array, target, 0, array.length);
189      }
190    
191      // TODO(kevinb): consider making this public
192      private static int lastIndexOf(
193          double[] array, double target, int start, int end) {
194        for (int i = end - 1; i >= start; i--) {
195          if (array[i] == target) {
196            return i;
197          }
198        }
199        return -1;
200      }
201    
202      /**
203       * Returns the least value present in {@code array}, using the same rules of
204       * comparison as {@link Math#min(double, double)}.
205       *
206       * @param array a <i>nonempty</i> array of {@code double} values
207       * @return the value present in {@code array} that is less than or equal to
208       *     every other value in the array
209       * @throws IllegalArgumentException if {@code array} is empty
210       */
211      public static double min(double... array) {
212        checkArgument(array.length > 0);
213        double min = array[0];
214        for (int i = 1; i < array.length; i++) {
215          min = Math.min(min, array[i]);
216        }
217        return min;
218      }
219    
220      /**
221       * Returns the greatest value present in {@code array}, using the same rules
222       * of comparison as {@link Math#max(double, double)}.
223       *
224       * @param array a <i>nonempty</i> array of {@code double} values
225       * @return the value present in {@code array} that is greater than or equal to
226       *     every other value in the array
227       * @throws IllegalArgumentException if {@code array} is empty
228       */
229      public static double max(double... array) {
230        checkArgument(array.length > 0);
231        double max = array[0];
232        for (int i = 1; i < array.length; i++) {
233          max = Math.max(max, array[i]);
234        }
235        return max;
236      }
237    
238      /**
239       * Returns the values from each provided array combined into a single array.
240       * For example, {@code concat(new double[] {a, b}, new double[] {}, new
241       * double[] {c}} returns the array {@code {a, b, c}}.
242       *
243       * @param arrays zero or more {@code double} arrays
244       * @return a single array containing all the values from the source arrays, in
245       *     order
246       */
247      public static double[] concat(double[]... arrays) {
248        int length = 0;
249        for (double[] array : arrays) {
250          length += array.length;
251        }
252        double[] result = new double[length];
253        int pos = 0;
254        for (double[] array : arrays) {
255          System.arraycopy(array, 0, result, pos, array.length);
256          pos += array.length;
257        }
258        return result;
259      }
260    
261      /**
262       * Returns an array containing the same values as {@code array}, but
263       * guaranteed to be of a specified minimum length. If {@code array} already
264       * has a length of at least {@code minLength}, it is returned directly.
265       * Otherwise, a new array of size {@code minLength + padding} is returned,
266       * containing the values of {@code array}, and zeroes in the remaining places.
267       *
268       * @param array the source array
269       * @param minLength the minimum length the returned array must guarantee
270       * @param padding an extra amount to "grow" the array by if growth is
271       *     necessary
272       * @throws IllegalArgumentException if {@code minLength} or {@code padding} is
273       *     negative
274       * @return an array containing the values of {@code array}, with guaranteed
275       *     minimum length {@code minLength}
276       */
277      public static double[] ensureCapacity(
278          double[] array, int minLength, int padding) {
279        checkArgument(minLength >= 0, "Invalid minLength: %s", minLength);
280        checkArgument(padding >= 0, "Invalid padding: %s", padding);
281        return (array.length < minLength)
282            ? copyOf(array, minLength + padding)
283            : array;
284      }
285    
286      // Arrays.copyOf() requires Java 6
287      private static double[] copyOf(double[] original, int length) {
288        double[] copy = new double[length];
289        System.arraycopy(original, 0, copy, 0, Math.min(original.length, length));
290        return copy;
291      }
292    
293      /**
294       * Returns a string containing the supplied {@code double} values, converted
295       * to strings as specified by {@link Double#toString(double)}, and separated
296       * by {@code separator}. For example, {@code join("-", 1.0, 2.0, 3.0)} returns
297       * the string {@code "1.0-2.0-3.0"}.
298       *
299       * <p>Note that {@link Double#toString(double)} formats {@code double}
300       * differently in GWT sometimes.  In the previous example, it returns the
301       * string {@code "1-2-3"}.
302       *
303       * @param separator the text that should appear between consecutive values in
304       *     the resulting string (but not at the start or end)
305       * @param array an array of {@code double} values, possibly empty
306       */
307      public static String join(String separator, double... array) {
308        checkNotNull(separator);
309        if (array.length == 0) {
310          return "";
311        }
312    
313        // For pre-sizing a builder, just get the right order of magnitude
314        StringBuilder builder = new StringBuilder(array.length * 12);
315        builder.append(array[0]);
316        for (int i = 1; i < array.length; i++) {
317          builder.append(separator).append(array[i]);
318        }
319        return builder.toString();
320      }
321    
322      /**
323       * Returns a comparator that compares two {@code double} arrays
324       * lexicographically. That is, it compares, using {@link
325       * #compare(double, double)}), the first pair of values that follow any
326       * common prefix, or when one array is a prefix of the other, treats the
327       * shorter array as the lesser. For example,
328       * {@code [] < [1.0] < [1.0, 2.0] < [2.0]}.
329       *
330       * <p>The returned comparator is inconsistent with {@link
331       * Object#equals(Object)} (since arrays support only identity equality), but
332       * it is consistent with {@link Arrays#equals(double[], double[])}.
333       *
334       * @see <a href="http://en.wikipedia.org/wiki/Lexicographical_order">
335       *     Lexicographical order article at Wikipedia</a>
336       * @since 2.0
337       */
338      public static Comparator<double[]> lexicographicalComparator() {
339        return LexicographicalComparator.INSTANCE;
340      }
341    
342      private enum LexicographicalComparator implements Comparator<double[]> {
343        INSTANCE;
344    
345        @Override
346        public int compare(double[] left, double[] right) {
347          int minLength = Math.min(left.length, right.length);
348          for (int i = 0; i < minLength; i++) {
349            int result = Doubles.compare(left[i], right[i]);
350            if (result != 0) {
351              return result;
352            }
353          }
354          return left.length - right.length;
355        }
356      }
357    
358      /**
359       * Returns an array containing each value of {@code collection}, converted to
360       * a {@code double} value in the manner of {@link Number#doubleValue}.
361       *
362       * <p>Elements are copied from the argument collection as if by {@code
363       * collection.toArray()}.  Calling this method is as thread-safe as calling
364       * that method.
365       *
366       * @param collection a collection of {@code Number} instances
367       * @return an array containing the same values as {@code collection}, in the
368       *     same order, converted to primitives
369       * @throws NullPointerException if {@code collection} or any of its elements
370       *     is null
371       * @since 1.0 (parameter was {@code Collection<Double>} before 12.0)
372       */
373      public static double[] toArray(Collection<? extends Number> collection) {
374        if (collection instanceof DoubleArrayAsList) {
375          return ((DoubleArrayAsList) collection).toDoubleArray();
376        }
377    
378        Object[] boxedArray = collection.toArray();
379        int len = boxedArray.length;
380        double[] array = new double[len];
381        for (int i = 0; i < len; i++) {
382          // checkNotNull for GWT (do not optimize)
383          array[i] = ((Number) checkNotNull(boxedArray[i])).doubleValue();
384        }
385        return array;
386      }
387    
388      /**
389       * Returns a fixed-size list backed by the specified array, similar to {@link
390       * Arrays#asList(Object[])}. The list supports {@link List#set(int, Object)},
391       * but any attempt to set a value to {@code null} will result in a {@link
392       * NullPointerException}.
393       *
394       * <p>The returned list maintains the values, but not the identities, of
395       * {@code Double} objects written to or read from it.  For example, whether
396       * {@code list.get(0) == list.get(0)} is true for the returned list is
397       * unspecified.
398       *
399       * <p>The returned list may have unexpected behavior if it contains {@code
400       * NaN}, or if {@code NaN} is used as a parameter to any of its methods.
401       *
402       * @param backingArray the array to back the list
403       * @return a list view of the array
404       */
405      public static List<Double> asList(double... backingArray) {
406        if (backingArray.length == 0) {
407          return Collections.emptyList();
408        }
409        return new DoubleArrayAsList(backingArray);
410      }
411    
412      @GwtCompatible
413      private static class DoubleArrayAsList extends AbstractList<Double>
414          implements RandomAccess, Serializable {
415        final double[] array;
416        final int start;
417        final int end;
418    
419        DoubleArrayAsList(double[] array) {
420          this(array, 0, array.length);
421        }
422    
423        DoubleArrayAsList(double[] array, int start, int end) {
424          this.array = array;
425          this.start = start;
426          this.end = end;
427        }
428    
429        @Override public int size() {
430          return end - start;
431        }
432    
433        @Override public boolean isEmpty() {
434          return false;
435        }
436    
437        @Override public Double get(int index) {
438          checkElementIndex(index, size());
439          return array[start + index];
440        }
441    
442        @Override public boolean contains(Object target) {
443          // Overridden to prevent a ton of boxing
444          return (target instanceof Double)
445              && Doubles.indexOf(array, (Double) target, start, end) != -1;
446        }
447    
448        @Override public int indexOf(Object target) {
449          // Overridden to prevent a ton of boxing
450          if (target instanceof Double) {
451            int i = Doubles.indexOf(array, (Double) target, start, end);
452            if (i >= 0) {
453              return i - start;
454            }
455          }
456          return -1;
457        }
458    
459        @Override public int lastIndexOf(Object target) {
460          // Overridden to prevent a ton of boxing
461          if (target instanceof Double) {
462            int i = Doubles.lastIndexOf(array, (Double) target, start, end);
463            if (i >= 0) {
464              return i - start;
465            }
466          }
467          return -1;
468        }
469    
470        @Override public Double set(int index, Double element) {
471          checkElementIndex(index, size());
472          double oldValue = array[start + index];
473          // checkNotNull for GWT (do not optimize)
474          array[start + index] = checkNotNull(element);
475          return oldValue;
476        }
477    
478        @Override public List<Double> subList(int fromIndex, int toIndex) {
479          int size = size();
480          checkPositionIndexes(fromIndex, toIndex, size);
481          if (fromIndex == toIndex) {
482            return Collections.emptyList();
483          }
484          return new DoubleArrayAsList(array, start + fromIndex, start + toIndex);
485        }
486    
487        @Override public boolean equals(Object object) {
488          if (object == this) {
489            return true;
490          }
491          if (object instanceof DoubleArrayAsList) {
492            DoubleArrayAsList that = (DoubleArrayAsList) object;
493            int size = size();
494            if (that.size() != size) {
495              return false;
496            }
497            for (int i = 0; i < size; i++) {
498              if (array[start + i] != that.array[that.start + i]) {
499                return false;
500              }
501            }
502            return true;
503          }
504          return super.equals(object);
505        }
506    
507        @Override public int hashCode() {
508          int result = 1;
509          for (int i = start; i < end; i++) {
510            result = 31 * result + Doubles.hashCode(array[i]);
511          }
512          return result;
513        }
514    
515        @Override public String toString() {
516          StringBuilder builder = new StringBuilder(size() * 12);
517          builder.append('[').append(array[start]);
518          for (int i = start + 1; i < end; i++) {
519            builder.append(", ").append(array[i]);
520          }
521          return builder.append(']').toString();
522        }
523    
524        double[] toDoubleArray() {
525          // Arrays.copyOfRange() is not available under GWT
526          int size = size();
527          double[] result = new double[size];
528          System.arraycopy(array, start, result, 0, size);
529          return result;
530        }
531    
532        private static final long serialVersionUID = 0;
533      }
534    }