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