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);
     }
 
+    /**
+     *  Return value for peek() if the stream does not support peeking, or if
+     *  it cannot from this offset.
+     */
+    static const size_t PEEK_UNSUPPORTED = (size_t) -1;

[bungeman-skia, 2015/03/31 22:04:48]

I think we tend toward enums with 'k' prefixes (though I'm fine with them not
being enums, I think we require 'enum foo : size_t' now). These all caps things
look like defines.

[scroggo, 2015/04/01 18:38:31]

I'm fine with renaming them to use 'k' prefixes (prefices?).
I was unfamiliar with that option. Sounds good to me.

Done.

+
+    /**
+     *  Return value for peek() if the stream encountered a fatal error. The
+     *  stream is no unreliable.
+     */
+    static const size_t PEEK_FAILURE     = (size_t) -2;
+
+    /**
+     *  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 less than size bytes from the
+     *  end or the stream has reached its limit for how many bytes it can peek.
+     *  If there is a fatal error, PEEK_FAILURE is returned, and the stream
+     *  cannot be used anymore.
+     *  After this call, the stream will have the same state it did beforehand,
+     *  unless there was an error (and PEEK_FAILURE was returned).
+     *  If peeking is unsupported, returns PEEK_UNSUPPORTED
+     *  @param buffer Must not be NULL. Destination to copy bytes.
+     *  @param size Number of bytes to copy.
+     *  @return the number of bytes actually read, or an error message.
+     */
+    virtual size_t peek(void* buffer, size_t size) { return PEEK_UNSUPPORTED; }

[bungeman-skia, 2015/03/31 22:04:48]

We already have the pattern of either returning bool (rewind, seek, move) or
having a bool capability checker (hasPosition, hasLength). I'm not sure what to
do about this one, since the root issue is that 'read' doesn't do a good job of
error reporting itself.

+
     /** 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 PEEK_FAILURE;
+        }
+        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