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