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