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
017package com.google.common.primitives;
018
019import static com.google.common.base.Preconditions.checkArgument;
020import static com.google.common.base.Preconditions.checkElementIndex;
021import static com.google.common.base.Preconditions.checkNotNull;
022import static com.google.common.base.Preconditions.checkPositionIndexes;
023import static java.lang.Double.NEGATIVE_INFINITY;
024import static java.lang.Double.POSITIVE_INFINITY;
025
026import com.google.common.annotations.GwtCompatible;
027
028import java.io.Serializable;
029import java.util.AbstractList;
030import java.util.Arrays;
031import java.util.Collection;
032import java.util.Collections;
033import java.util.Comparator;
034import java.util.List;
035import 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
049public 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}