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