Add a method to read a stream without advancing it.

include/core/SkStream.h

 /*
  * Copyright 2006 The Android Open Source Project
  *
  * Use of this source code is governed by a BSD-style license that can be
  * found in the LICENSE file.
  */
 
 #ifndef SkStream_DEFINED
 #define SkStream_DEFINED
 
@@ skipping 45 matching lines @@
      */
     virtual size_t read(void* buffer, size_t size) = 0;
 
     /** Skip size number of bytes.
      *  @return the actual number bytes that could be skipped.
      */
     size_t skip(size_t size) {
         return this->read(NULL, size);
     }
 
+    /**
+     *  Attempt to peek at size bytes.
+     *  If this stream supports peeking, copy up to size bytes into buffer. If
+     *  less than size is returned, the stream is at the end or the stream has
+     *  reached its limit for how many bytes it can peek. Zero is returned on
+     *  error.
+     *  After this call, the stream will have the same state it did beforehand,
+     *  unless there was an error.
+     *  If peeking is unsupported, return 0.
+     *  @param buffer Must not be NULL. Destination to copy bytes.
+     *  @param size Number of bytes to copy.
+     *  @return the number of bytes actually read.
+     */
+    virtual size_t peek(void* buffer, size_t size) { return 0; }

[bungeman-skia, 2015/03/30 19:09:00]

Since SkStreamSeekable must support this (slightly different semantics, since if
you call SkStreamSeekable::peek(<non-zero>) and you get back 0 that means an
error really occurred as opposed to maybe peeking is unsupported), perhaps this
should be declared a few line down in the SkStreamSeekable section.

[scroggo, 2015/03/30 19:31:49]

FWIW, an SkStreamSeekable supports it incidentally, since the functions required
for SkStreamSeekable can be (and are) used to implement this. This seems
slightly different from saying that an SkStreamSeekable must support it. That's
not to say that I think it *doesn't* belong in that section, but it might be
something to consider.

It does seem a little odd that an error looks the same as not supported (and as
we were at the end!). We could add out parameters or use particular return
values as sentinels, but I do like the fact that this signature mirrors read().

[djsollen, 2015/03/30 19:56:53]

I think it is important to disambiguate between the 2 states.  Particularly
since the error state means my stream is now unreliable.

+
     /** Returns true when all the bytes in the stream have been read.
      *  This may return true early (when there are no more bytes to be read)
      *  or late (after the first unsuccessful read).
      */
     virtual bool isAtEnd() const = 0;
 
     int8_t   readS8();
     int16_t  readS16();
     int32_t  readS32();
 
@@ skipping 61 matching lines @@
 /** SkStreamSeekable is a SkStreamRewindable for which position, seek, move, and fork are required. */
 class SK_API SkStreamSeekable : public SkStreamRewindable {
 public:
     SkStreamSeekable* duplicate() const override = 0;
 
     bool hasPosition() const override { return true; }
     size_t getPosition() const override = 0;
     bool seek(size_t position) override = 0;
     bool move(long offset) override = 0;
     SkStreamSeekable* fork() const override = 0;
+    // Default implementation reads and then resets the position.
+    size_t peek(void* buffer, size_t size) override {
+        SkASSERT(buffer != NULL);
+        const size_t position = this->getPosition();
+        const size_t bytesRead = this->read(buffer, size);
+        if (!this->seek(position)) {
+            return 0;
+        }
+        return bytesRead;
+    }
 };
 
 /** SkStreamAsset is a SkStreamSeekable for which getLength is required. */
 class SK_API SkStreamAsset : public SkStreamSeekable {
 public:
     SkStreamAsset* duplicate() const override = 0;
     SkStreamAsset* fork() const override = 0;
 
     bool hasLength() const override { return true; }
     size_t getLength() const override = 0;
@@ skipping 280 matching lines @@
 
 private:
     size_t fBytesWritten;
     typedef SkWStream INHERITED;
 };
 
 // for now
 typedef SkFILEStream SkURLStream;
 
 #endif