Add a method to read a stream without advancing it.

include/core/SkStream.h

Index: include/core/SkStream.h
diff --git a/include/core/SkStream.h b/include/core/SkStream.h
index c227765b363624afbf7a3f98f39d480c7f05726d..64965beee8ec0a6c08f88b5453770de5d3a74c23 100644
--- a/include/core/SkStream.h
+++ b/include/core/SkStream.h
@@ -63,6 +63,21 @@ public:
         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).
@@ -144,6 +159,16 @@ public:
     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. */