1 /*
2 * Copyright (C) 2009 The Guava Authors
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
5 * in compliance with the License. You may obtain a copy of the License at
6 *
7 * http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software distributed under the License
10 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
11 * or implied. See the License for the specific language governing permissions and limitations under
12 * the License.
13 */
14
15 package com.google.common.primitives;
16
17 import static com.google.common.base.Preconditions.checkArgument;
18 import static com.google.common.base.Preconditions.checkNotNull;
19 import static com.google.common.base.Preconditions.checkPositionIndexes;
20
21 import com.google.common.annotations.GwtCompatible;
22 import java.util.Arrays;
23 import java.util.Comparator;
24
25 /**
26 * Static utility methods pertaining to {@code byte} primitives that interpret values as signed. The
27 * corresponding methods that treat the values as unsigned are found in {@link UnsignedBytes}, and
28 * the methods for which signedness is not an issue are in {@link Bytes}.
29 *
30 * <p>See the Guava User Guide article on <a
31 * href="https://github.com/google/guava/wiki/PrimitivesExplained">primitive utilities</a>.
32 *
33 * @author Kevin Bourrillion
34 * @since 1.0
35 */
36 // TODO(kevinb): how to prevent warning on UnsignedBytes when building GWT
37 // javadoc?
38 @GwtCompatible
39 @ElementTypesAreNonnullByDefault
40 public final class SignedBytes {
41 private SignedBytes() {}
42
43 /**
44 * The largest power of two that can be represented as a signed {@code byte}.
45 *
46 * @since 10.0
47 */
48 public static final byte MAX_POWER_OF_TWO = 1 << 6;
49
50 /**
51 * Returns the {@code byte} value that is equal to {@code value}, if possible.
52 *
53 * @param value any value in the range of the {@code byte} type
54 * @return the {@code byte} value that equals {@code value}
55 * @throws IllegalArgumentException if {@code value} is greater than {@link Byte#MAX_VALUE} or
56 * less than {@link Byte#MIN_VALUE}
57 */
58 public static byte checkedCast(long value) {
59 byte result = (byte) value;
60 checkArgument(result == value, "Out of range: %s", value);
61 return result;
62 }
63
64 /**
65 * Returns the {@code byte} nearest in value to {@code value}.
66 *
67 * @param value any {@code long} value
68 * @return the same value cast to {@code byte} if it is in the range of the {@code byte} type,
69 * {@link Byte#MAX_VALUE} if it is too large, or {@link Byte#MIN_VALUE} if it is too small
70 */
71 public static byte saturatedCast(long value) {
72 if (value > Byte.MAX_VALUE) {
73 return Byte.MAX_VALUE;
74 }
75 if (value < Byte.MIN_VALUE) {
76 return Byte.MIN_VALUE;
77 }
78 return (byte) value;
79 }
80
81 /**
82 * Compares the two specified {@code byte} values. The sign of the value returned is the same as
83 * that of {@code ((Byte) a).compareTo(b)}.
84 *
85 * <p><b>Note:</b> this method behaves identically to the JDK 7 method {@link Byte#compare}.
86 *
87 * @param a the first {@code byte} to compare
88 * @param b the second {@code byte} to compare
89 * @return a negative value if {@code a} is less than {@code b}; a positive value if {@code a} is
90 * greater than {@code b}; or zero if they are equal
91 */
92 // TODO(kevinb): if Ints.compare etc. are ever removed, *maybe* remove this
93 // one too, which would leave compare methods only on the Unsigned* classes.
94 public static int compare(byte a, byte b) {
95 return a - b; // safe due to restricted range
96 }
97
98 /**
99 * Returns the least value present in {@code array}.
100 *
101 * @param array a <i>nonempty</i> array of {@code byte} values
102 * @return the value present in {@code array} that is less than or equal to every other value in
103 * the array
104 * @throws IllegalArgumentException if {@code array} is empty
105 */
106 public static byte min(byte... array) {
107 checkArgument(array.length > 0);
108 byte min = array[0];
109 for (int i = 1; i < array.length; i++) {
110 if (array[i] < min) {
111 min = array[i];
112 }
113 }
114 return min;
115 }
116
117 /**
118 * Returns the greatest value present in {@code array}.
119 *
120 * @param array a <i>nonempty</i> array of {@code byte} values
121 * @return the value present in {@code array} that is greater than or equal to every other value
122 * in the array
123 * @throws IllegalArgumentException if {@code array} is empty
124 */
125 public static byte max(byte... array) {
126 checkArgument(array.length > 0);
127 byte max = array[0];
128 for (int i = 1; i < array.length; i++) {
129 if (array[i] > max) {
130 max = array[i];
131 }
132 }
133 return max;
134 }
135
136 /**
137 * Returns a string containing the supplied {@code byte} values separated by {@code separator}.
138 * For example, {@code join(":", 0x01, 0x02, -0x01)} returns the string {@code "1:2:-1"}.
139 *
140 * @param separator the text that should appear between consecutive values in the resulting string
141 * (but not at the start or end)
142 * @param array an array of {@code byte} values, possibly empty
143 */
144 public static String join(String separator, byte... array) {
145 checkNotNull(separator);
146 if (array.length == 0) {
147 return "";
148 }
149
150 // For pre-sizing a builder, just get the right order of magnitude
151 StringBuilder builder = new StringBuilder(array.length * 5);
152 builder.append(array[0]);
153 for (int i = 1; i < array.length; i++) {
154 builder.append(separator).append(array[i]);
155 }
156 return builder.toString();
157 }
158
159 /**
160 * Returns a comparator that compares two {@code byte} arrays <a
161 * href="http://en.wikipedia.org/wiki/Lexicographical_order">lexicographically</a>. That is, it
162 * compares, using {@link #compare(byte, byte)}), the first pair of values that follow any common
163 * prefix, or when one array is a prefix of the other, treats the shorter array as the lesser. For
164 * example, {@code [] < [0x01] < [0x01, 0x80] < [0x01, 0x7F] < [0x02]}. Values are treated as
165 * signed.
166 *
167 * <p>The returned comparator is inconsistent with {@link Object#equals(Object)} (since arrays
168 * support only identity equality), but it is consistent with {@link
169 * java.util.Arrays#equals(byte[], byte[])}.
170 *
171 * @since 2.0
172 */
173 public static Comparator<byte[]> lexicographicalComparator() {
174 return LexicographicalComparator.INSTANCE;
175 }
176
177 private enum LexicographicalComparator implements Comparator<byte[]> {
178 INSTANCE;
179
180 @Override
181 public int compare(byte[] left, byte[] right) {
182 int minLength = Math.min(left.length, right.length);
183 for (int i = 0; i < minLength; i++) {
184 int result = SignedBytes.compare(left[i], right[i]);
185 if (result != 0) {
186 return result;
187 }
188 }
189 return left.length - right.length;
190 }
191
192 @Override
193 public String toString() {
194 return "SignedBytes.lexicographicalComparator()";
195 }
196 }
197
198 /**
199 * Sorts the elements of {@code array} in descending order.
200 *
201 * @since 23.1
202 */
203 public static void sortDescending(byte[] array) {
204 checkNotNull(array);
205 sortDescending(array, 0, array.length);
206 }
207
208 /**
209 * Sorts the elements of {@code array} between {@code fromIndex} inclusive and {@code toIndex}
210 * exclusive in descending order.
211 *
212 * @since 23.1
213 */
214 public static void sortDescending(byte[] array, int fromIndex, int toIndex) {
215 checkNotNull(array);
216 checkPositionIndexes(fromIndex, toIndex, array.length);
217 Arrays.sort(array, fromIndex, toIndex);
218 Bytes.reverse(array, fromIndex, toIndex);
219 }
220 }