001/*
002 * Copyright (C) 2007 The Guava Authors
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
005 * in compliance with the License. You may obtain a copy of the License at
006 *
007 * http://www.apache.org/licenses/LICENSE-2.0
008 *
009 * Unless required by applicable law or agreed to in writing, software distributed under the License
010 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
011 * or implied. See the License for the specific language governing permissions and limitations under
012 * the License.
013 */
014
015package com.google.common.io;
016
017import static com.google.common.base.Preconditions.checkArgument;
018import static com.google.common.base.Preconditions.checkNotNull;
019import static com.google.common.base.Preconditions.checkPositionIndex;
020import static com.google.common.base.Preconditions.checkPositionIndexes;
021
022import com.google.common.annotations.Beta;
023import com.google.common.annotations.GwtIncompatible;
024import com.google.common.math.IntMath;
025import com.google.errorprone.annotations.CanIgnoreReturnValue;
026import java.io.ByteArrayInputStream;
027import java.io.ByteArrayOutputStream;
028import java.io.DataInput;
029import java.io.DataInputStream;
030import java.io.DataOutput;
031import java.io.DataOutputStream;
032import java.io.EOFException;
033import java.io.FilterInputStream;
034import java.io.IOException;
035import java.io.InputStream;
036import java.io.OutputStream;
037import java.nio.ByteBuffer;
038import java.nio.channels.FileChannel;
039import java.nio.channels.ReadableByteChannel;
040import java.nio.channels.WritableByteChannel;
041import java.util.ArrayDeque;
042import java.util.Arrays;
043import java.util.Queue;
044
045/**
046 * Provides utility methods for working with byte arrays and I/O streams.
047 *
048 * @author Chris Nokleberg
049 * @author Colin Decker
050 * @since 1.0
051 */
052@GwtIncompatible
053public final class ByteStreams {
054
055  private static final int BUFFER_SIZE = 8192;
056
057  /** Creates a new byte array for buffering reads or writes. */
058  static byte[] createBuffer() {
059    return new byte[BUFFER_SIZE];
060  }
061
062  /**
063   * There are three methods to implement {@link FileChannel#transferTo(long, long,
064   * WritableByteChannel)}:
065   *
066   * <ol>
067   *   <li>Use sendfile(2) or equivalent. Requires that both the input channel and the output
068   *       channel have their own file descriptors. Generally this only happens when both channels
069   *       are files or sockets. This performs zero copies - the bytes never enter userspace.
070   *   <li>Use mmap(2) or equivalent. Requires that either the input channel or the output channel
071   *       have file descriptors. Bytes are copied from the file into a kernel buffer, then directly
072   *       into the other buffer (userspace). Note that if the file is very large, a naive
073   *       implementation will effectively put the whole file in memory. On many systems with paging
074   *       and virtual memory, this is not a problem - because it is mapped read-only, the kernel
075   *       can always page it to disk "for free". However, on systems where killing processes
076   *       happens all the time in normal conditions (i.e., android) the OS must make a tradeoff
077   *       between paging memory and killing other processes - so allocating a gigantic buffer and
078   *       then sequentially accessing it could result in other processes dying. This is solvable
079   *       via madvise(2), but that obviously doesn't exist in java.
080   *   <li>Ordinary copy. Kernel copies bytes into a kernel buffer, from a kernel buffer into a
081   *       userspace buffer (byte[] or ByteBuffer), then copies them from that buffer into the
082   *       destination channel.
083   * </ol>
084   *
085   * This value is intended to be large enough to make the overhead of system calls negligible,
086   * without being so large that it causes problems for systems with atypical memory management if
087   * approaches 2 or 3 are used.
088   */
089  private static final int ZERO_COPY_CHUNK_SIZE = 512 * 1024;
090
091  private ByteStreams() {}
092
093  /**
094   * Copies all bytes from the input stream to the output stream. Does not close or flush either
095   * stream.
096   *
097   * @param from the input stream to read from
098   * @param to the output stream to write to
099   * @return the number of bytes copied
100   * @throws IOException if an I/O error occurs
101   */
102  @CanIgnoreReturnValue
103  public static long copy(InputStream from, OutputStream to) throws IOException {
104    checkNotNull(from);
105    checkNotNull(to);
106    byte[] buf = createBuffer();
107    long total = 0;
108    while (true) {
109      int r = from.read(buf);
110      if (r == -1) {
111        break;
112      }
113      to.write(buf, 0, r);
114      total += r;
115    }
116    return total;
117  }
118
119  /**
120   * Copies all bytes from the readable channel to the writable channel. Does not close or flush
121   * either channel.
122   *
123   * @param from the readable channel to read from
124   * @param to the writable channel to write to
125   * @return the number of bytes copied
126   * @throws IOException if an I/O error occurs
127   */
128  @CanIgnoreReturnValue
129  public static long copy(ReadableByteChannel from, WritableByteChannel to) throws IOException {
130    checkNotNull(from);
131    checkNotNull(to);
132    if (from instanceof FileChannel) {
133      FileChannel sourceChannel = (FileChannel) from;
134      long oldPosition = sourceChannel.position();
135      long position = oldPosition;
136      long copied;
137      do {
138        copied = sourceChannel.transferTo(position, ZERO_COPY_CHUNK_SIZE, to);
139        position += copied;
140        sourceChannel.position(position);
141      } while (copied > 0 || position < sourceChannel.size());
142      return position - oldPosition;
143    }
144
145    ByteBuffer buf = ByteBuffer.wrap(createBuffer());
146    long total = 0;
147    while (from.read(buf) != -1) {
148      Java8Compatibility.flip(buf);
149      while (buf.hasRemaining()) {
150        total += to.write(buf);
151      }
152      Java8Compatibility.clear(buf);
153    }
154    return total;
155  }
156
157  /** Max array length on JVM. */
158  private static final int MAX_ARRAY_LEN = Integer.MAX_VALUE - 8;
159
160  /** Large enough to never need to expand, given the geometric progression of buffer sizes. */
161  private static final int TO_BYTE_ARRAY_DEQUE_SIZE = 20;
162
163  /**
164   * Returns a byte array containing the bytes from the buffers already in {@code bufs} (which have
165   * a total combined length of {@code totalLen} bytes) followed by all bytes remaining in the given
166   * input stream.
167   */
168  private static byte[] toByteArrayInternal(InputStream in, Queue<byte[]> bufs, int totalLen)
169      throws IOException {
170    // Starting with an 8k buffer, double the size of each successive buffer. Buffers are retained
171    // in a deque so that there's no copying between buffers while reading and so all of the bytes
172    // in each new allocated buffer are available for reading from the stream.
173    for (int bufSize = BUFFER_SIZE;
174        totalLen < MAX_ARRAY_LEN;
175        bufSize = IntMath.saturatedMultiply(bufSize, 2)) {
176      byte[] buf = new byte[Math.min(bufSize, MAX_ARRAY_LEN - totalLen)];
177      bufs.add(buf);
178      int off = 0;
179      while (off < buf.length) {
180        // always OK to fill buf; its size plus the rest of bufs is never more than MAX_ARRAY_LEN
181        int r = in.read(buf, off, buf.length - off);
182        if (r == -1) {
183          return combineBuffers(bufs, totalLen);
184        }
185        off += r;
186        totalLen += r;
187      }
188    }
189
190    // read MAX_ARRAY_LEN bytes without seeing end of stream
191    if (in.read() == -1) {
192      // oh, there's the end of the stream
193      return combineBuffers(bufs, MAX_ARRAY_LEN);
194    } else {
195      throw new OutOfMemoryError("input is too large to fit in a byte array");
196    }
197  }
198
199  private static byte[] combineBuffers(Queue<byte[]> bufs, int totalLen) {
200    byte[] result = new byte[totalLen];
201    int remaining = totalLen;
202    while (remaining > 0) {
203      byte[] buf = bufs.remove();
204      int bytesToCopy = Math.min(remaining, buf.length);
205      int resultOffset = totalLen - remaining;
206      System.arraycopy(buf, 0, result, resultOffset, bytesToCopy);
207      remaining -= bytesToCopy;
208    }
209    return result;
210  }
211
212  /**
213   * Reads all bytes from an input stream into a byte array. Does not close the stream.
214   *
215   * @param in the input stream to read from
216   * @return a byte array containing all the bytes from the stream
217   * @throws IOException if an I/O error occurs
218   */
219  public static byte[] toByteArray(InputStream in) throws IOException {
220    checkNotNull(in);
221    return toByteArrayInternal(in, new ArrayDeque<byte[]>(TO_BYTE_ARRAY_DEQUE_SIZE), 0);
222  }
223
224  /**
225   * Reads all bytes from an input stream into a byte array. The given expected size is used to
226   * create an initial byte array, but if the actual number of bytes read from the stream differs,
227   * the correct result will be returned anyway.
228   */
229  static byte[] toByteArray(InputStream in, long expectedSize) throws IOException {
230    checkArgument(expectedSize >= 0, "expectedSize (%s) must be non-negative", expectedSize);
231    if (expectedSize > MAX_ARRAY_LEN) {
232      throw new OutOfMemoryError(expectedSize + " bytes is too large to fit in a byte array");
233    }
234
235    byte[] bytes = new byte[(int) expectedSize];
236    int remaining = (int) expectedSize;
237
238    while (remaining > 0) {
239      int off = (int) expectedSize - remaining;
240      int read = in.read(bytes, off, remaining);
241      if (read == -1) {
242        // end of stream before reading expectedSize bytes
243        // just return the bytes read so far
244        return Arrays.copyOf(bytes, off);
245      }
246      remaining -= read;
247    }
248
249    // bytes is now full
250    int b = in.read();
251    if (b == -1) {
252      return bytes;
253    }
254
255    // the stream was longer, so read the rest normally
256    Queue<byte[]> bufs = new ArrayDeque<byte[]>(TO_BYTE_ARRAY_DEQUE_SIZE + 2);
257    bufs.add(bytes);
258    bufs.add(new byte[] {(byte) b});
259    return toByteArrayInternal(in, bufs, bytes.length + 1);
260  }
261
262  /**
263   * Reads and discards data from the given {@code InputStream} until the end of the stream is
264   * reached. Returns the total number of bytes read. Does not close the stream.
265   *
266   * @since 20.0
267   */
268  @CanIgnoreReturnValue
269  @Beta
270  public static long exhaust(InputStream in) throws IOException {
271    long total = 0;
272    long read;
273    byte[] buf = createBuffer();
274    while ((read = in.read(buf)) != -1) {
275      total += read;
276    }
277    return total;
278  }
279
280  /**
281   * Returns a new {@link ByteArrayDataInput} instance to read from the {@code bytes} array from the
282   * beginning.
283   */
284  @Beta
285  public static ByteArrayDataInput newDataInput(byte[] bytes) {
286    return newDataInput(new ByteArrayInputStream(bytes));
287  }
288
289  /**
290   * Returns a new {@link ByteArrayDataInput} instance to read from the {@code bytes} array,
291   * starting at the given position.
292   *
293   * @throws IndexOutOfBoundsException if {@code start} is negative or greater than the length of
294   *     the array
295   */
296  @Beta
297  public static ByteArrayDataInput newDataInput(byte[] bytes, int start) {
298    checkPositionIndex(start, bytes.length);
299    return newDataInput(new ByteArrayInputStream(bytes, start, bytes.length - start));
300  }
301
302  /**
303   * Returns a new {@link ByteArrayDataInput} instance to read from the given {@code
304   * ByteArrayInputStream}. The given input stream is not reset before being read from by the
305   * returned {@code ByteArrayDataInput}.
306   *
307   * @since 17.0
308   */
309  @Beta
310  public static ByteArrayDataInput newDataInput(ByteArrayInputStream byteArrayInputStream) {
311    return new ByteArrayDataInputStream(checkNotNull(byteArrayInputStream));
312  }
313
314  private static class ByteArrayDataInputStream implements ByteArrayDataInput {
315    final DataInput input;
316
317    ByteArrayDataInputStream(ByteArrayInputStream byteArrayInputStream) {
318      this.input = new DataInputStream(byteArrayInputStream);
319    }
320
321    @Override
322    public void readFully(byte b[]) {
323      try {
324        input.readFully(b);
325      } catch (IOException e) {
326        throw new IllegalStateException(e);
327      }
328    }
329
330    @Override
331    public void readFully(byte b[], int off, int len) {
332      try {
333        input.readFully(b, off, len);
334      } catch (IOException e) {
335        throw new IllegalStateException(e);
336      }
337    }
338
339    @Override
340    public int skipBytes(int n) {
341      try {
342        return input.skipBytes(n);
343      } catch (IOException e) {
344        throw new IllegalStateException(e);
345      }
346    }
347
348    @Override
349    public boolean readBoolean() {
350      try {
351        return input.readBoolean();
352      } catch (IOException e) {
353        throw new IllegalStateException(e);
354      }
355    }
356
357    @Override
358    public byte readByte() {
359      try {
360        return input.readByte();
361      } catch (EOFException e) {
362        throw new IllegalStateException(e);
363      } catch (IOException impossible) {
364        throw new AssertionError(impossible);
365      }
366    }
367
368    @Override
369    public int readUnsignedByte() {
370      try {
371        return input.readUnsignedByte();
372      } catch (IOException e) {
373        throw new IllegalStateException(e);
374      }
375    }
376
377    @Override
378    public short readShort() {
379      try {
380        return input.readShort();
381      } catch (IOException e) {
382        throw new IllegalStateException(e);
383      }
384    }
385
386    @Override
387    public int readUnsignedShort() {
388      try {
389        return input.readUnsignedShort();
390      } catch (IOException e) {
391        throw new IllegalStateException(e);
392      }
393    }
394
395    @Override
396    public char readChar() {
397      try {
398        return input.readChar();
399      } catch (IOException e) {
400        throw new IllegalStateException(e);
401      }
402    }
403
404    @Override
405    public int readInt() {
406      try {
407        return input.readInt();
408      } catch (IOException e) {
409        throw new IllegalStateException(e);
410      }
411    }
412
413    @Override
414    public long readLong() {
415      try {
416        return input.readLong();
417      } catch (IOException e) {
418        throw new IllegalStateException(e);
419      }
420    }
421
422    @Override
423    public float readFloat() {
424      try {
425        return input.readFloat();
426      } catch (IOException e) {
427        throw new IllegalStateException(e);
428      }
429    }
430
431    @Override
432    public double readDouble() {
433      try {
434        return input.readDouble();
435      } catch (IOException e) {
436        throw new IllegalStateException(e);
437      }
438    }
439
440    @Override
441    public String readLine() {
442      try {
443        return input.readLine();
444      } catch (IOException e) {
445        throw new IllegalStateException(e);
446      }
447    }
448
449    @Override
450    public String readUTF() {
451      try {
452        return input.readUTF();
453      } catch (IOException e) {
454        throw new IllegalStateException(e);
455      }
456    }
457  }
458
459  /** Returns a new {@link ByteArrayDataOutput} instance with a default size. */
460  @Beta
461  public static ByteArrayDataOutput newDataOutput() {
462    return newDataOutput(new ByteArrayOutputStream());
463  }
464
465  /**
466   * Returns a new {@link ByteArrayDataOutput} instance sized to hold {@code size} bytes before
467   * resizing.
468   *
469   * @throws IllegalArgumentException if {@code size} is negative
470   */
471  @Beta
472  public static ByteArrayDataOutput newDataOutput(int size) {
473    // When called at high frequency, boxing size generates too much garbage,
474    // so avoid doing that if we can.
475    if (size < 0) {
476      throw new IllegalArgumentException(String.format("Invalid size: %s", size));
477    }
478    return newDataOutput(new ByteArrayOutputStream(size));
479  }
480
481  /**
482   * Returns a new {@link ByteArrayDataOutput} instance which writes to the given {@code
483   * ByteArrayOutputStream}. The given output stream is not reset before being written to by the
484   * returned {@code ByteArrayDataOutput} and new data will be appended to any existing content.
485   *
486   * <p>Note that if the given output stream was not empty or is modified after the {@code
487   * ByteArrayDataOutput} is created, the contract for {@link ByteArrayDataOutput#toByteArray} will
488   * not be honored (the bytes returned in the byte array may not be exactly what was written via
489   * calls to {@code ByteArrayDataOutput}).
490   *
491   * @since 17.0
492   */
493  @Beta
494  public static ByteArrayDataOutput newDataOutput(ByteArrayOutputStream byteArrayOutputStream) {
495    return new ByteArrayDataOutputStream(checkNotNull(byteArrayOutputStream));
496  }
497
498  private static class ByteArrayDataOutputStream implements ByteArrayDataOutput {
499
500    final DataOutput output;
501    final ByteArrayOutputStream byteArrayOutputStream;
502
503    ByteArrayDataOutputStream(ByteArrayOutputStream byteArrayOutputStream) {
504      this.byteArrayOutputStream = byteArrayOutputStream;
505      output = new DataOutputStream(byteArrayOutputStream);
506    }
507
508    @Override
509    public void write(int b) {
510      try {
511        output.write(b);
512      } catch (IOException impossible) {
513        throw new AssertionError(impossible);
514      }
515    }
516
517    @Override
518    public void write(byte[] b) {
519      try {
520        output.write(b);
521      } catch (IOException impossible) {
522        throw new AssertionError(impossible);
523      }
524    }
525
526    @Override
527    public void write(byte[] b, int off, int len) {
528      try {
529        output.write(b, off, len);
530      } catch (IOException impossible) {
531        throw new AssertionError(impossible);
532      }
533    }
534
535    @Override
536    public void writeBoolean(boolean v) {
537      try {
538        output.writeBoolean(v);
539      } catch (IOException impossible) {
540        throw new AssertionError(impossible);
541      }
542    }
543
544    @Override
545    public void writeByte(int v) {
546      try {
547        output.writeByte(v);
548      } catch (IOException impossible) {
549        throw new AssertionError(impossible);
550      }
551    }
552
553    @Override
554    public void writeBytes(String s) {
555      try {
556        output.writeBytes(s);
557      } catch (IOException impossible) {
558        throw new AssertionError(impossible);
559      }
560    }
561
562    @Override
563    public void writeChar(int v) {
564      try {
565        output.writeChar(v);
566      } catch (IOException impossible) {
567        throw new AssertionError(impossible);
568      }
569    }
570
571    @Override
572    public void writeChars(String s) {
573      try {
574        output.writeChars(s);
575      } catch (IOException impossible) {
576        throw new AssertionError(impossible);
577      }
578    }
579
580    @Override
581    public void writeDouble(double v) {
582      try {
583        output.writeDouble(v);
584      } catch (IOException impossible) {
585        throw new AssertionError(impossible);
586      }
587    }
588
589    @Override
590    public void writeFloat(float v) {
591      try {
592        output.writeFloat(v);
593      } catch (IOException impossible) {
594        throw new AssertionError(impossible);
595      }
596    }
597
598    @Override
599    public void writeInt(int v) {
600      try {
601        output.writeInt(v);
602      } catch (IOException impossible) {
603        throw new AssertionError(impossible);
604      }
605    }
606
607    @Override
608    public void writeLong(long v) {
609      try {
610        output.writeLong(v);
611      } catch (IOException impossible) {
612        throw new AssertionError(impossible);
613      }
614    }
615
616    @Override
617    public void writeShort(int v) {
618      try {
619        output.writeShort(v);
620      } catch (IOException impossible) {
621        throw new AssertionError(impossible);
622      }
623    }
624
625    @Override
626    public void writeUTF(String s) {
627      try {
628        output.writeUTF(s);
629      } catch (IOException impossible) {
630        throw new AssertionError(impossible);
631      }
632    }
633
634    @Override
635    public byte[] toByteArray() {
636      return byteArrayOutputStream.toByteArray();
637    }
638  }
639
640  private static final OutputStream NULL_OUTPUT_STREAM =
641      new OutputStream() {
642        /** Discards the specified byte. */
643        @Override
644        public void write(int b) {}
645
646        /** Discards the specified byte array. */
647        @Override
648        public void write(byte[] b) {
649          checkNotNull(b);
650        }
651
652        /** Discards the specified byte array. */
653        @Override
654        public void write(byte[] b, int off, int len) {
655          checkNotNull(b);
656        }
657
658        @Override
659        public String toString() {
660          return "ByteStreams.nullOutputStream()";
661        }
662      };
663
664  /**
665   * Returns an {@link OutputStream} that simply discards written bytes.
666   *
667   * @since 14.0 (since 1.0 as com.google.common.io.NullOutputStream)
668   */
669  @Beta
670  public static OutputStream nullOutputStream() {
671    return NULL_OUTPUT_STREAM;
672  }
673
674  /**
675   * Wraps a {@link InputStream}, limiting the number of bytes which can be read.
676   *
677   * @param in the input stream to be wrapped
678   * @param limit the maximum number of bytes to be read
679   * @return a length-limited {@link InputStream}
680   * @since 14.0 (since 1.0 as com.google.common.io.LimitInputStream)
681   */
682  @Beta
683  public static InputStream limit(InputStream in, long limit) {
684    return new LimitedInputStream(in, limit);
685  }
686
687  private static final class LimitedInputStream extends FilterInputStream {
688
689    private long left;
690    private long mark = -1;
691
692    LimitedInputStream(InputStream in, long limit) {
693      super(in);
694      checkNotNull(in);
695      checkArgument(limit >= 0, "limit must be non-negative");
696      left = limit;
697    }
698
699    @Override
700    public int available() throws IOException {
701      return (int) Math.min(in.available(), left);
702    }
703
704    // it's okay to mark even if mark isn't supported, as reset won't work
705    @Override
706    public synchronized void mark(int readLimit) {
707      in.mark(readLimit);
708      mark = left;
709    }
710
711    @Override
712    public int read() throws IOException {
713      if (left == 0) {
714        return -1;
715      }
716
717      int result = in.read();
718      if (result != -1) {
719        --left;
720      }
721      return result;
722    }
723
724    @Override
725    public int read(byte[] b, int off, int len) throws IOException {
726      if (left == 0) {
727        return -1;
728      }
729
730      len = (int) Math.min(len, left);
731      int result = in.read(b, off, len);
732      if (result != -1) {
733        left -= result;
734      }
735      return result;
736    }
737
738    @Override
739    public synchronized void reset() throws IOException {
740      if (!in.markSupported()) {
741        throw new IOException("Mark not supported");
742      }
743      if (mark == -1) {
744        throw new IOException("Mark not set");
745      }
746
747      in.reset();
748      left = mark;
749    }
750
751    @Override
752    public long skip(long n) throws IOException {
753      n = Math.min(n, left);
754      long skipped = in.skip(n);
755      left -= skipped;
756      return skipped;
757    }
758  }
759
760  /**
761   * Attempts to read enough bytes from the stream to fill the given byte array, with the same
762   * behavior as {@link DataInput#readFully(byte[])}. Does not close the stream.
763   *
764   * @param in the input stream to read from.
765   * @param b the buffer into which the data is read.
766   * @throws EOFException if this stream reaches the end before reading all the bytes.
767   * @throws IOException if an I/O error occurs.
768   */
769  @Beta
770  public static void readFully(InputStream in, byte[] b) throws IOException {
771    readFully(in, b, 0, b.length);
772  }
773
774  /**
775   * Attempts to read {@code len} bytes from the stream into the given array starting at {@code
776   * off}, with the same behavior as {@link DataInput#readFully(byte[], int, int)}. Does not close
777   * the stream.
778   *
779   * @param in the input stream to read from.
780   * @param b the buffer into which the data is read.
781   * @param off an int specifying the offset into the data.
782   * @param len an int specifying the number of bytes to read.
783   * @throws EOFException if this stream reaches the end before reading all the bytes.
784   * @throws IOException if an I/O error occurs.
785   */
786  @Beta
787  public static void readFully(InputStream in, byte[] b, int off, int len) throws IOException {
788    int read = read(in, b, off, len);
789    if (read != len) {
790      throw new EOFException(
791          "reached end of stream after reading " + read + " bytes; " + len + " bytes expected");
792    }
793  }
794
795  /**
796   * Discards {@code n} bytes of data from the input stream. This method will block until the full
797   * amount has been skipped. Does not close the stream.
798   *
799   * @param in the input stream to read from
800   * @param n the number of bytes to skip
801   * @throws EOFException if this stream reaches the end before skipping all the bytes
802   * @throws IOException if an I/O error occurs, or the stream does not support skipping
803   */
804  @Beta
805  public static void skipFully(InputStream in, long n) throws IOException {
806    long skipped = skipUpTo(in, n);
807    if (skipped < n) {
808      throw new EOFException(
809          "reached end of stream after skipping " + skipped + " bytes; " + n + " bytes expected");
810    }
811  }
812
813  /**
814   * Discards up to {@code n} bytes of data from the input stream. This method will block until
815   * either the full amount has been skipped or until the end of the stream is reached, whichever
816   * happens first. Returns the total number of bytes skipped.
817   */
818  static long skipUpTo(InputStream in, final long n) throws IOException {
819    long totalSkipped = 0;
820    // A buffer is allocated if skipSafely does not skip any bytes.
821    byte[] buf = null;
822
823    while (totalSkipped < n) {
824      long remaining = n - totalSkipped;
825      long skipped = skipSafely(in, remaining);
826
827      if (skipped == 0) {
828        // Do a buffered read since skipSafely could return 0 repeatedly, for example if
829        // in.available() always returns 0 (the default).
830        int skip = (int) Math.min(remaining, BUFFER_SIZE);
831        if (buf == null) {
832          // Allocate a buffer bounded by the maximum size that can be requested, for
833          // example an array of BUFFER_SIZE is unnecessary when the value of remaining
834          // is smaller.
835          buf = new byte[skip];
836        }
837        if ((skipped = in.read(buf, 0, skip)) == -1) {
838          // Reached EOF
839          break;
840        }
841      }
842
843      totalSkipped += skipped;
844    }
845
846    return totalSkipped;
847  }
848
849  /**
850   * Attempts to skip up to {@code n} bytes from the given input stream, but not more than {@code
851   * in.available()} bytes. This prevents {@code FileInputStream} from skipping more bytes than
852   * actually remain in the file, something that it {@linkplain java.io.FileInputStream#skip(long)
853   * specifies} it can do in its Javadoc despite the fact that it is violating the contract of
854   * {@code InputStream.skip()}.
855   */
856  private static long skipSafely(InputStream in, long n) throws IOException {
857    int available = in.available();
858    return available == 0 ? 0 : in.skip(Math.min(available, n));
859  }
860
861  /**
862   * Process the bytes of the given input stream using the given processor.
863   *
864   * @param input the input stream to process
865   * @param processor the object to which to pass the bytes of the stream
866   * @return the result of the byte processor
867   * @throws IOException if an I/O error occurs
868   * @since 14.0
869   */
870  @Beta
871  @CanIgnoreReturnValue // some processors won't return a useful result
872  public static <T> T readBytes(InputStream input, ByteProcessor<T> processor) throws IOException {
873    checkNotNull(input);
874    checkNotNull(processor);
875
876    byte[] buf = createBuffer();
877    int read;
878    do {
879      read = input.read(buf);
880    } while (read != -1 && processor.processBytes(buf, 0, read));
881    return processor.getResult();
882  }
883
884  /**
885   * Reads some bytes from an input stream and stores them into the buffer array {@code b}. This
886   * method blocks until {@code len} bytes of input data have been read into the array, or end of
887   * file is detected. The number of bytes read is returned, possibly zero. Does not close the
888   * stream.
889   *
890   * <p>A caller can detect EOF if the number of bytes read is less than {@code len}. All subsequent
891   * calls on the same stream will return zero.
892   *
893   * <p>If {@code b} is null, a {@code NullPointerException} is thrown. If {@code off} is negative,
894   * or {@code len} is negative, or {@code off+len} is greater than the length of the array {@code
895   * b}, then an {@code IndexOutOfBoundsException} is thrown. If {@code len} is zero, then no bytes
896   * are read. Otherwise, the first byte read is stored into element {@code b[off]}, the next one
897   * into {@code b[off+1]}, and so on. The number of bytes read is, at most, equal to {@code len}.
898   *
899   * @param in the input stream to read from
900   * @param b the buffer into which the data is read
901   * @param off an int specifying the offset into the data
902   * @param len an int specifying the number of bytes to read
903   * @return the number of bytes read
904   * @throws IOException if an I/O error occurs
905   * @throws IndexOutOfBoundsException if {@code off} is negative, if {@code len} is negative, or if
906   *     {@code off + len} is greater than {@code b.length}
907   */
908  @Beta
909  @CanIgnoreReturnValue
910  // Sometimes you don't care how many bytes you actually read, I guess.
911  // (You know that it's either going to read len bytes or stop at EOF.)
912  public static int read(InputStream in, byte[] b, int off, int len) throws IOException {
913    checkNotNull(in);
914    checkNotNull(b);
915    if (len < 0) {
916      throw new IndexOutOfBoundsException(String.format("len (%s) cannot be negative", len));
917    }
918    checkPositionIndexes(off, off + len, b.length);
919    int total = 0;
920    while (total < len) {
921      int result = in.read(b, off + total, len - total);
922      if (result == -1) {
923        break;
924      }
925      total += result;
926    }
927    return total;
928  }
929}