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