BufferedSource.peek()

We’ve discussed an idea for a fancy peek API. Here’s an API sketch:

interface BufferedSource {
  /**
   * Returns a new `BufferedSource` that can read data from this `BufferedSource`
   * without consuming it. The returned source becomes invalid once this source
   * is next read or closed.
   *
   * For example, we can use `peek()` to lookahead and read the same data multiple
   * times.
   * 
   * ```
   * val buffer = Buffer()
   * buffer.writeUtf8("abcdefghij")
   *
   * buffer.readUtf8(3) // returns "abc", buffer contains "defghi"
   *
   * val peek = buffer.peek()
   * peek.readUtf8(3) // returns "def", buffer contains "defghi"
   * peek.readUtf8(3) // returns "ghi", buffer contains "defghi"
   *
   * buffer.readUtf8() // returns "def", buffer contains "ghi"
   * ```
   */
  BufferedSource peek()
}

Behind the scenes the peeking source would copy data from the upstream buffer into its own private buffer.

[swankjesse]

One other thing I’m eager for – if we do this right we can also potentially support JsonReader.peek() that behaves the same way. That’s quite powerful for features like the RuntimeJsonAdapterFactory.

[swankjesse]

Gotcha. It won’t catch all programming mistakes. But it should still prevent data corruption because we’ll hault before we return unexpected data.