add unread and unsafe_unread (#13)

Author: bicycle1885

docs/src/examples.md

@@ -143,3 +143,26 @@ using CodecZlib
 decompressed = transcode(ZlibDecompression(), b"x\x9cKL*JLNLI\x04R\x00\x19\xf2\x04U")
 String(decompressed)
 ```
+
+Unread data
+-----------
+
+`TranscodingStream` supports *unread* operation, which inserts data into the
+current reading position. This is useful when you want to peek from the stream.
+`TranscodingStreams.unread` and `TranscodingStreams.unsafe_unread` functions are
+provided:
+```julia
+using TranscodingStreams
+stream = NoopStream(open("data.txt"))
+data1 = read(stream, 8)
+TranscodingStreams.unread(stream, data1)
+data2 = read(stream, 8)
+@assert data1 == data2
+```
+
+The unread operaion is different from the write operation in that the unreaded
+data are not written to the wrapped stream. The unreaded data are stored in the
+internal buffer of a transcoding stream.
+
+Unfortunately, *unwrite* operation is not provided because there is no way to
+cancel write operations that are already commited to the wrapped stream.

docs/src/references.md

@@ -13,6 +13,8 @@ TranscodingStream(codec::Codec, stream::IO)
 transcode(codec::Codec, data::Vector{UInt8})
 TranscodingStreams.TOKEN_END
 TranscodingStreams.unsafe_read
+TranscodingStreams.unread
+TranscodingStreams.unsafe_unread
 ```
 
 Codec

src/buffer.jl

@@ -191,6 +191,15 @@ function takemarked!(buf::Buffer)
     return resize!(buf.data, sz)
 end
 
+# Insert data to the current buffer.
+function insertdata!(buf::Buffer, data::Ptr{UInt8}, nbytes::Integer)
+    makemargin!(buf, nbytes)
+    copy!(buf.data, buf.bufferpos + nbytes, buf.data, buf.bufferpos, buffersize(buf))
+    unsafe_copy!(bufferptr(buf), data, nbytes)
+    buf.marginpos += nbytes
+    return buf
+end
+
 # Read as much data as possbile from `input` to the margin of `output`.
 # This function will not block if `input` has buffered data.
 function readdata!(input::IO, output::Buffer)

src/stream.jl

@@ -244,6 +244,35 @@ function Base.readavailable(stream::TranscodingStream)
     return data
 end
 
+"""
+    unread(stream::TranscodingStream, data::Vector{UInt8})
+
+Insert `data` to the current reading position of `stream`.
+
+The next `read(stream, sizeof(data))` call will read data that are just
+inserted.
+"""
+function unread(stream::TranscodingStream, data::Vector{UInt8})
+    unsafe_unread(stream, pointer(data), sizeof(data))
+end
+
+"""
+    unsafe_unread(stream::TranscodingStream, data::Ptr, nbytes::Integer)
+
+Insert `nbytes` pointed by `data` to the current reading position of `stream`.
+
+The data are copied into the internal buffer and hence `data` can be safely used
+after the operation without interfering the stream.
+"""
+function unsafe_unread(stream::TranscodingStream, data::Ptr, nbytes::Integer)
+    if nbytes < 0
+        throw(ArgumentError("negative nbytes"))
+    end
+    changestate!(stream, :read)
+    insertdata!(stream.state.buffer1, convert(Ptr{UInt8}, data), nbytes)
+    return nothing
+end
+
 
 # Write Functions
 # ---------------

test/runtests.jl

@@ -198,6 +198,45 @@ end
         read(stream, 3)
         write(stream, b"xyz")
     end
+
+    stream = NoopStream(IOBuffer(""))
+    @test TranscodingStreams.unread(stream, b"foo") === nothing
+    @test read(stream, 3) == b"foo"
+    close(stream)
+
+    stream = NoopStream(IOBuffer("foo"))
+    @test read(stream, 3) == b"foo"
+    @test TranscodingStreams.unread(stream, b"bar") === nothing
+    @test read(stream, 3) == b"bar"
+    close(stream)
+
+    stream = NoopStream(IOBuffer("foobar"))
+    @test TranscodingStreams.unread(stream, b"baz") === nothing
+    @test read(stream, 3) == b"baz"
+    @test read(stream, 3) == b"foo"
+    @test read(stream, 3) == b"bar"
+    @test eof(stream)
+    close(stream)
+
+    stream = NoopStream(IOBuffer("foobar"))
+    @test read(stream, 3) == b"foo"
+    @test TranscodingStreams.unread(stream, b"baz") === nothing
+    @test read(stream, 3) == b"baz"
+    @test read(stream, 3) == b"bar"
+    @test eof(stream)
+    close(stream)
+
+    stream = NoopStream(IOBuffer("foobar"))
+    @test read(stream, 3) == b"foo"
+    @test read(stream, 3) == b"bar"
+    @test TranscodingStreams.unread(stream, b"baz") === nothing
+    @test read(stream, 3) == b"baz"
+    @test eof(stream)
+    close(stream)
+
+    stream = NoopStream(IOBuffer("foobar"))
+    @test_throws ArgumentError TranscodingStreams.unsafe_unread(stream, pointer(b"foo"), -1)
+    close(stream)
 end
 
 # This does not implement necessary interface methods.