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