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
024 import com.google.common.annotations.GwtCompatible;
025
026 import java.io.Serializable;
027 import java.util.AbstractList;
028 import java.util.Arrays;
029 import java.util.Collection;
030 import java.util.Collections;
031 import java.util.List;
032 import java.util.RandomAccess;
033
034 /**
035 * Static utility methods pertaining to {@code byte} primitives, that are not
036 * already found in either {@link Byte} or {@link Arrays}, <i>and interpret
037 * bytes as neither signed nor unsigned</i>. The methods which specifically
038 * treat bytes as signed or unsigned are found in {@link SignedBytes} and {@link
039 * UnsignedBytes}.
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 // TODO(kevinb): how to prevent warning on UnsignedBytes when building GWT
049 // javadoc?
050 @GwtCompatible
051 public final class Bytes {
052 private Bytes() {}
053
054 /**
055 * Returns a hash code for {@code value}; equal to the result of invoking
056 * {@code ((Byte) value).hashCode()}.
057 *
058 * @param value a primitive {@code byte} value
059 * @return a hash code for the value
060 */
061 public static int hashCode(byte value) {
062 return value;
063 }
064
065 /**
066 * Returns {@code true} if {@code target} is present as an element anywhere in
067 * {@code array}.
068 *
069 * @param array an array of {@code byte} values, possibly empty
070 * @param target a primitive {@code byte} value
071 * @return {@code true} if {@code array[i] == target} for some value of {@code
072 * i}
073 */
074 public static boolean contains(byte[] array, byte target) {
075 for (byte value : array) {
076 if (value == target) {
077 return true;
078 }
079 }
080 return false;
081 }
082
083 /**
084 * Returns the index of the first appearance of the value {@code target} in
085 * {@code array}.
086 *
087 * @param array an array of {@code byte} values, possibly empty
088 * @param target a primitive {@code byte} value
089 * @return the least index {@code i} for which {@code array[i] == target}, or
090 * {@code -1} if no such index exists.
091 */
092 public static int indexOf(byte[] array, byte target) {
093 return indexOf(array, target, 0, array.length);
094 }
095
096 // TODO(kevinb): consider making this public
097 private static int indexOf(
098 byte[] array, byte target, int start, int end) {
099 for (int i = start; i < end; i++) {
100 if (array[i] == target) {
101 return i;
102 }
103 }
104 return -1;
105 }
106
107 /**
108 * Returns the start position of the first occurrence of the specified {@code
109 * target} within {@code array}, or {@code -1} if there is no such occurrence.
110 *
111 * <p>More formally, returns the lowest index {@code i} such that {@code
112 * java.util.Arrays.copyOfRange(array, i, i + target.length)} contains exactly
113 * the same elements as {@code target}.
114 *
115 * @param array the array to search for the sequence {@code target}
116 * @param target the array to search for as a sub-sequence of {@code array}
117 */
118 public static int indexOf(byte[] array, byte[] target) {
119 checkNotNull(array, "array");
120 checkNotNull(target, "target");
121 if (target.length == 0) {
122 return 0;
123 }
124
125 outer:
126 for (int i = 0; i < array.length - target.length + 1; i++) {
127 for (int j = 0; j < target.length; j++) {
128 if (array[i + j] != target[j]) {
129 continue outer;
130 }
131 }
132 return i;
133 }
134 return -1;
135 }
136
137 /**
138 * Returns the index of the last appearance of the value {@code target} in
139 * {@code array}.
140 *
141 * @param array an array of {@code byte} values, possibly empty
142 * @param target a primitive {@code byte} value
143 * @return the greatest index {@code i} for which {@code array[i] == target},
144 * or {@code -1} if no such index exists.
145 */
146 public static int lastIndexOf(byte[] array, byte target) {
147 return lastIndexOf(array, target, 0, array.length);
148 }
149
150 // TODO(kevinb): consider making this public
151 private static int lastIndexOf(
152 byte[] array, byte target, int start, int end) {
153 for (int i = end - 1; i >= start; i--) {
154 if (array[i] == target) {
155 return i;
156 }
157 }
158 return -1;
159 }
160
161 /**
162 * Returns the values from each provided array combined into a single array.
163 * For example, {@code concat(new byte[] {a, b}, new byte[] {}, new
164 * byte[] {c}} returns the array {@code {a, b, c}}.
165 *
166 * @param arrays zero or more {@code byte} arrays
167 * @return a single array containing all the values from the source arrays, in
168 * order
169 */
170 public static byte[] concat(byte[]... arrays) {
171 int length = 0;
172 for (byte[] array : arrays) {
173 length += array.length;
174 }
175 byte[] result = new byte[length];
176 int pos = 0;
177 for (byte[] array : arrays) {
178 System.arraycopy(array, 0, result, pos, array.length);
179 pos += array.length;
180 }
181 return result;
182 }
183
184 /**
185 * Returns an array containing the same values as {@code array}, but
186 * guaranteed to be of a specified minimum length. If {@code array} already
187 * has a length of at least {@code minLength}, it is returned directly.
188 * Otherwise, a new array of size {@code minLength + padding} is returned,
189 * containing the values of {@code array}, and zeroes in the remaining places.
190 *
191 * @param array the source array
192 * @param minLength the minimum length the returned array must guarantee
193 * @param padding an extra amount to "grow" the array by if growth is
194 * necessary
195 * @throws IllegalArgumentException if {@code minLength} or {@code padding} is
196 * negative
197 * @return an array containing the values of {@code array}, with guaranteed
198 * minimum length {@code minLength}
199 */
200 public static byte[] ensureCapacity(
201 byte[] array, int minLength, int padding) {
202 checkArgument(minLength >= 0, "Invalid minLength: %s", minLength);
203 checkArgument(padding >= 0, "Invalid padding: %s", padding);
204 return (array.length < minLength)
205 ? copyOf(array, minLength + padding)
206 : array;
207 }
208
209 // Arrays.copyOf() requires Java 6
210 private static byte[] copyOf(byte[] original, int length) {
211 byte[] copy = new byte[length];
212 System.arraycopy(original, 0, copy, 0, Math.min(original.length, length));
213 return copy;
214 }
215
216 /**
217 * Returns an array containing each value of {@code collection}, converted to
218 * a {@code byte} value in the manner of {@link Number#byteValue}.
219 *
220 * <p>Elements are copied from the argument collection as if by {@code
221 * collection.toArray()}. Calling this method is as thread-safe as calling
222 * that method.
223 *
224 * @param collection a collection of {@code Number} instances
225 * @return an array containing the same values as {@code collection}, in the
226 * same order, converted to primitives
227 * @throws NullPointerException if {@code collection} or any of its elements
228 * is null
229 * @since 1.0 (parameter was {@code Collection<Byte>} before 12.0)
230 */
231 public static byte[] toArray(Collection<? extends Number> collection) {
232 if (collection instanceof ByteArrayAsList) {
233 return ((ByteArrayAsList) collection).toByteArray();
234 }
235
236 Object[] boxedArray = collection.toArray();
237 int len = boxedArray.length;
238 byte[] array = new byte[len];
239 for (int i = 0; i < len; i++) {
240 // checkNotNull for GWT (do not optimize)
241 array[i] = ((Number) checkNotNull(boxedArray[i])).byteValue();
242 }
243 return array;
244 }
245
246 /**
247 * Returns a fixed-size list backed by the specified array, similar to {@link
248 * Arrays#asList(Object[])}. The list supports {@link List#set(int, Object)},
249 * but any attempt to set a value to {@code null} will result in a {@link
250 * NullPointerException}.
251 *
252 * <p>The returned list maintains the values, but not the identities, of
253 * {@code Byte} objects written to or read from it. For example, whether
254 * {@code list.get(0) == list.get(0)} is true for the returned list is
255 * unspecified.
256 *
257 * @param backingArray the array to back the list
258 * @return a list view of the array
259 */
260 public static List<Byte> asList(byte... backingArray) {
261 if (backingArray.length == 0) {
262 return Collections.emptyList();
263 }
264 return new ByteArrayAsList(backingArray);
265 }
266
267 @GwtCompatible
268 private static class ByteArrayAsList extends AbstractList<Byte>
269 implements RandomAccess, Serializable {
270 final byte[] array;
271 final int start;
272 final int end;
273
274 ByteArrayAsList(byte[] array) {
275 this(array, 0, array.length);
276 }
277
278 ByteArrayAsList(byte[] array, int start, int end) {
279 this.array = array;
280 this.start = start;
281 this.end = end;
282 }
283
284 @Override public int size() {
285 return end - start;
286 }
287
288 @Override public boolean isEmpty() {
289 return false;
290 }
291
292 @Override public Byte get(int index) {
293 checkElementIndex(index, size());
294 return array[start + index];
295 }
296
297 @Override public boolean contains(Object target) {
298 // Overridden to prevent a ton of boxing
299 return (target instanceof Byte)
300 && Bytes.indexOf(array, (Byte) target, start, end) != -1;
301 }
302
303 @Override public int indexOf(Object target) {
304 // Overridden to prevent a ton of boxing
305 if (target instanceof Byte) {
306 int i = Bytes.indexOf(array, (Byte) target, start, end);
307 if (i >= 0) {
308 return i - start;
309 }
310 }
311 return -1;
312 }
313
314 @Override public int lastIndexOf(Object target) {
315 // Overridden to prevent a ton of boxing
316 if (target instanceof Byte) {
317 int i = Bytes.lastIndexOf(array, (Byte) target, start, end);
318 if (i >= 0) {
319 return i - start;
320 }
321 }
322 return -1;
323 }
324
325 @Override public Byte set(int index, Byte element) {
326 checkElementIndex(index, size());
327 byte oldValue = array[start + index];
328 // checkNotNull for GWT (do not optimize)
329 array[start + index] = checkNotNull(element);
330 return oldValue;
331 }
332
333 @Override public List<Byte> subList(int fromIndex, int toIndex) {
334 int size = size();
335 checkPositionIndexes(fromIndex, toIndex, size);
336 if (fromIndex == toIndex) {
337 return Collections.emptyList();
338 }
339 return new ByteArrayAsList(array, start + fromIndex, start + toIndex);
340 }
341
342 @Override public boolean equals(Object object) {
343 if (object == this) {
344 return true;
345 }
346 if (object instanceof ByteArrayAsList) {
347 ByteArrayAsList that = (ByteArrayAsList) object;
348 int size = size();
349 if (that.size() != size) {
350 return false;
351 }
352 for (int i = 0; i < size; i++) {
353 if (array[start + i] != that.array[that.start + i]) {
354 return false;
355 }
356 }
357 return true;
358 }
359 return super.equals(object);
360 }
361
362 @Override public int hashCode() {
363 int result = 1;
364 for (int i = start; i < end; i++) {
365 result = 31 * result + Bytes.hashCode(array[i]);
366 }
367 return result;
368 }
369
370 @Override public String toString() {
371 StringBuilder builder = new StringBuilder(size() * 5);
372 builder.append('[').append(array[start]);
373 for (int i = start + 1; i < end; i++) {
374 builder.append(", ").append(array[i]);
375 }
376 return builder.append(']').toString();
377 }
378
379 byte[] toByteArray() {
380 // Arrays.copyOfRange() is not available under GWT
381 int size = size();
382 byte[] result = new byte[size];
383 System.arraycopy(array, start, result, 0, size);
384 return result;
385 }
386
387 private static final long serialVersionUID = 0;
388 }
389 }