    001    /*
    002     * Copyright (C) 2009 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.checkNotNull;
    021
    022    import com.google.common.annotations.GwtCompatible;
    023
    024    import java.util.Comparator;
    025
    026    /**
    027     * Static utility methods pertaining to {@code byte} primitives that
    028     * interpret values as signed. The corresponding methods that treat the values
    029     * as unsigned are found in {@link UnsignedBytes}, and the methods for which
    030     * signedness is not an issue are in {@link Bytes}.
    031     *
    032     * @author Kevin Bourrillion
    033     * @since 1.0
    034     */
    035    // TODO(kevinb): how to prevent warning on UnsignedBytes when building GWT
    036    // javadoc?
    037    @GwtCompatible
    038    public final class SignedBytes {
    039      private SignedBytes() {}
    040
    041      /**
    042       * The largest power of two that can be represented as a signed {@code byte}.
    043       *
    044       * @since 10.0
    045       */
    046      public static final byte MAX_POWER_OF_TWO = 1 << 6;
    047
    048      /**
    049       * Returns the {@code byte} value that is equal to {@code value}, if possible.
    050       *
    051       * @param value any value in the range of the {@code byte} type
    052       * @return the {@code byte} value that equals {@code value}
    053       * @throws IllegalArgumentException if {@code value} is greater than {@link
    054       *     Byte#MAX_VALUE} or less than {@link Byte#MIN_VALUE}
    055       */
    056      public static byte checkedCast(long value) {
    057        byte result = (byte) value;
    058        checkArgument(result == value, "Out of range: %s", value);
    059        return result;
    060      }
    061
    062      /**
    063       * Returns the {@code byte} nearest in value to {@code value}.
    064       *
    065       * @param value any {@code long} value
    066       * @return the same value cast to {@code byte} if it is in the range of the
    067       *     {@code byte} type, {@link Byte#MAX_VALUE} if it is too large,
    068       *     or {@link Byte#MIN_VALUE} if it is too small
    069       */
    070      public static byte saturatedCast(long value) {
    071        if (value > Byte.MAX_VALUE) {
    072          return Byte.MAX_VALUE;
    073        }
    074        if (value < Byte.MIN_VALUE) {
    075          return Byte.MIN_VALUE;
    076        }
    077        return (byte) value;
    078      }
    079
    080      /**
    081       * Compares the two specified {@code byte} values. The sign of the value
    082       * returned is the same as that of {@code ((Byte) a).compareTo(b)}.
    083       *
    084       * @param a the first {@code byte} to compare
    085       * @param b the second {@code byte} to compare
    086       * @return a negative value if {@code a} is less than {@code b}; a positive
    087       *     value if {@code a} is greater than {@code b}; or zero if they are equal
    088       */
    089      public static int compare(byte a, byte b) {
    090        return a - b; // safe due to restricted range
    091      }
    092
    093      /**
    094       * Returns the least value present in {@code array}.
    095       *
    096       * @param array a <i>nonempty</i> array of {@code byte} values
    097       * @return the value present in {@code array} that is less than or equal to
    098       *     every other value in the array
    099       * @throws IllegalArgumentException if {@code array} is empty
    100       */
    101      public static byte min(byte... array) {
    102        checkArgument(array.length > 0);
    103        byte min = array[0];
    104        for (int i = 1; i < array.length; i++) {
    105          if (array[i] < min) {
    106            min = array[i];
    107          }
    108        }
    109        return min;
    110      }
    111
    112      /**
    113       * Returns the greatest value present in {@code array}.
    114       *
    115       * @param array a <i>nonempty</i> array of {@code byte} values
    116       * @return the value present in {@code array} that is greater than or equal to
    117       *     every other value in the array
    118       * @throws IllegalArgumentException if {@code array} is empty
    119       */
    120      public static byte max(byte... array) {
    121        checkArgument(array.length > 0);
    122        byte max = array[0];
    123        for (int i = 1; i < array.length; i++) {
    124          if (array[i] > max) {
    125            max = array[i];
    126          }
    127        }
    128        return max;
    129      }
    130
    131      /**
    132       * Returns a string containing the supplied {@code byte} values separated
    133       * by {@code separator}. For example, {@code join(":", 0x01, 0x02, -0x01)}
    134       * returns the string {@code "1:2:-1"}.
    135       *
    136       * @param separator the text that should appear between consecutive values in
    137       *     the resulting string (but not at the start or end)
    138       * @param array an array of {@code byte} values, possibly empty
    139       */
    140      public static String join(String separator, byte... array) {
    141        checkNotNull(separator);
    142        if (array.length == 0) {
    143          return "";
    144        }
    145
    146        // For pre-sizing a builder, just get the right order of magnitude
    147        StringBuilder builder = new StringBuilder(array.length * 5);
    148        builder.append(array[0]);
    149        for (int i = 1; i < array.length; i++) {
    150          builder.append(separator).append(array[i]);
    151        }
    152        return builder.toString();
    153      }
    154
    155      /**
    156       * Returns a comparator that compares two {@code byte} arrays
    157       * lexicographically. That is, it compares, using {@link
    158       * #compare(byte, byte)}), the first pair of values that follow any common
    159       * prefix, or when one array is a prefix of the other, treats the shorter
    160       * array as the lesser. For example, {@code [] < [0x01] < [0x01, 0x80] <
    161       * [0x01, 0x7F] < [0x02]}. Values are treated as signed.
    162       *
    163       * <p>The returned comparator is inconsistent with {@link
    164       * Object#equals(Object)} (since arrays support only identity equality), but
    165       * it is consistent with {@link java.util.Arrays#equals(byte[], byte[])}.
    166       *
    167       * @see <a href="http://en.wikipedia.org/wiki/Lexicographical_order">
    168       *     Lexicographical order article at Wikipedia</a>
    169       * @since 2.0
    170       */
    171      public static Comparator<byte[]> lexicographicalComparator() {
    172        return LexicographicalComparator.INSTANCE;
    173      }
    174
    175      private enum LexicographicalComparator implements Comparator<byte[]> {
    176        INSTANCE;
    177
    178        @Override
    179        public int compare(byte[] left, byte[] right) {
    180          int minLength = Math.min(left.length, right.length);
    181          for (int i = 0; i < minLength; i++) {
    182            int result = SignedBytes.compare(left[i], right[i]);
    183            if (result != 0) {
    184              return result;
    185            }
    186          }
    187          return left.length - right.length;
    188        }
    189      }
    190    }