add Noop codec (#4)

Author: bicycle1885

docs/src/index.md

@@ -187,24 +187,22 @@ compressed = take!(buf)
 close(stream)
 ```
 
-### Use an identity (no-op) codec
+### Use a noop codec
 
-Sometimes, the `Identity` codec, which does nothing, may be useful. The
-following example creates a decompression stream based on the extension of a
-filepath:
+Sometimes, the `Noop` codec, which does nothing, may be useful. The following
+example creates a decompression stream based on the extension of a filepath:
 ```julia
 using CodecZlib
 using CodecBzip2
 using TranscodingStreams
-using TranscodingStreams.CodecIdentity
 
 function makestream(filepath)
     if endswith(filepath, ".gz")
         codec = GzipDecompression()
     elseif endswith(filepath, ".bz2")
         codec = Bzip2Decompression()
     else
-        codec = Identity()
+        codec = Noop()
     end
     return TranscodingStream(codec, open(filepath))
 end
@@ -239,6 +237,11 @@ transcode(codec::Codec, data::Vector{UInt8})
 TranscodingStreams.TOKEN_END
 ```
 
+```@docs
+TranscodingStreams.Noop
+TranscodingStreams.NoopStream
+```
+
 ```@docs
 TranscodingStreams.CodecIdentity.Identity
 TranscodingStreams.CodecIdentity.IdentityStream

src/TranscodingStreams.jl

@@ -2,7 +2,10 @@ __precompile__()
 
 module TranscodingStreams
 
-export TranscodingStream
+export
+    TranscodingStream,
+    Noop,
+    NoopStream
 
 include("memory.jl")
 include("buffer.jl")
@@ -11,6 +14,7 @@ include("state.jl")
 include("stream.jl")
 include("io.jl")
 include("identity.jl")
+include("noop.jl")
 include("testtools.jl")
 
 end # module

src/noop.jl

@@ -0,0 +1,132 @@
+# Noop Codec
+# ==========
+
+"""
+    Noop()
+
+Create a noop codec.
+
+Noop (no operation) is a codec that does nothing. The data read from or written
+to the stream are kept as-is without any modification. This is often useful as a
+buffered stream or an identity element of a composition of streams.
+
+The implementations are specialized for this codec. For example, a `Noop` stream
+uses only one buffer rather than a pair of buffers, which avoids copying data
+between two buffers and the throughput will be larger than a naive
+implementation.
+"""
+struct Noop <: Codec end
+
+const NoopStream{S} = TranscodingStream{Noop,S} where S<:IO
+
+"""
+    NoopStream(stream::IO)
+
+Create a noop stream.
+"""
+function NoopStream(stream::IO)
+    return TranscodingStream(Noop(), stream)
+end
+
+function TranscodingStream(codec::Noop, stream::IO; bufsize::Integer=DEFAULT_BUFFER_SIZE)
+    if bufsize ≤ 0
+        throw(ArgumentError("non-positive buffer size"))
+    end
+    # Use only one buffer.
+    buffer = Buffer(bufsize)
+    state = TranscodingStreams.State(buffer, buffer)
+    return TranscodingStream(codec, stream, state)
+end
+
+function Base.unsafe_read(stream::NoopStream, output::Ptr{UInt8}, nbytes::UInt)
+    changestate!(stream, :read)
+    buffer = stream.state.buffer1
+    p = output
+    p_end = output + nbytes
+    while p < p_end && !eof(stream)
+        if buffersize(buffer) > 0
+            m = min(buffersize(buffer), p_end - p)
+            unsafe_copy!(p, bufferptr(buffer), m)
+            buffer.bufferpos += m
+        else
+            # directly read data from the underlying stream
+            m = p_end - p
+            unsafe_read(stream.stream, p, m)
+        end
+        p += m
+    end
+    if p < p_end && eof(stream)
+        throw(EOFError())
+    end
+    return
+end
+
+function Base.unsafe_write(stream::NoopStream, input::Ptr{UInt8}, nbytes::UInt)
+    changestate!(stream, :write)
+    buffer = stream.state.buffer1
+    if marginsize(buffer) ≥ nbytes
+        unsafe_copy!(marginptr(buffer), input, nbytes)
+        buffer.marginpos += nbytes
+        return Int(nbytes)
+    else
+        flushbuffer(stream)
+        # directly write data to the underlying stream
+        return unsafe_write(stream.stream, input, nbytes)
+    end
+end
+
+function Base.transcode(::Noop, data::Vector{UInt8})
+    # Copy data because the caller may expect the return object is not the same
+    # as from the input.
+    return copy(data)
+end
+
+
+# Buffering
+# ---------
+#
+# These methods are overloaded for the `Noop` codec because it has only one
+# buffer for efficiency.
+
+function fillbuffer(stream::NoopStream)
+    changestate!(stream, :read)
+    buffer = stream.state.buffer1
+    @assert buffer === stream.state.buffer2
+    nfilled::Int = 0
+    while buffersize(buffer) == 0 && !eof(stream.stream)
+        makemargin!(buffer, 1)
+        n = unsafe_read(stream.stream, marginptr(buffer), marginsize(buffer))
+        buffer.marginpos += n
+        nfilled += n
+    end
+    return nfilled
+end
+
+function flushbuffer(stream::NoopStream)
+    changestate!(stream, :write)
+    buffer = stream.state.buffer1
+    @assert buffer === stream.state.buffer2
+    nflushed::Int = 0
+    while buffersize(buffer) > 0
+        n = unsafe_write(stream.stream, bufferptr(buffer), buffersize(buffer))
+        buffer.bufferpos += n
+        nflushed += n
+    end
+    makemargin!(buffer, 0)
+    return nflushed
+end
+
+function flushbufferall(stream::NoopStream)
+    @assert stream.state.state == :write
+    buffer = stream.state.buffer1
+    bufsize = buffersize(buffer)
+    while buffersize(buffer) > 0
+        writebuffer!(stream.stream, buffer)
+    end
+    return bufsize
+end
+
+function processall(stream::NoopStream)
+    flushbufferall(stream)
+    @assert buffersize(stream.state.buffer1) == 0
+end

test/runtests.jl

@@ -171,6 +171,15 @@ end
     @test_throws ArgumentError TranscodingStream(Identity(), IOBuffer(), bufsize=0)
 end
 
+@testset "Noop Codec" begin
+    data = b"foo"
+    @test transcode(Noop(), data) !== data
+    TranscodingStreams.test_roundtrip_transcode(Noop, Noop)
+    TranscodingStreams.test_roundtrip_read(NoopStream, NoopStream)
+    TranscodingStreams.test_roundtrip_write(NoopStream, NoopStream)
+    TranscodingStreams.test_roundtrip_lines(NoopStream, NoopStream)
+end
+
 # This does not implement necessary interface methods.
 struct InvalidCodec <: TranscodingStreams.Codec end