add transcode(::Type{Codec}, data) method (#23)

Author: bicycle1885

README.md

@@ -51,8 +51,8 @@ close(stream)
 
 # Array API.
 array = Vector{UInt8}(text)
-array = transcode(GzipCompression(), array)
-array = transcode(GzipDecompression(), array)
+array = transcode(GzipCompression, array)
+array = transcode(GzipDecompression, array)
 @assert text == String(array)
 ```
 

docs/src/examples.md

@@ -140,10 +140,33 @@ in one shot. `transcode` takes a codec object as its first argument and a data
 vector as its second argument:
 ```julia
 using CodecZlib
-decompressed = transcode(ZlibDecompression(), b"x\x9cKL*JLNLI\x04R\x00\x19\xf2\x04U")
+decompressed = transcode(ZlibDecompression, b"x\x9cKL*JLNLI\x04R\x00\x19\xf2\x04U")
 String(decompressed)
 ```
 
+Transcode lots of strings
+-------------------------
+
+`transcode(<codec type>, data)` method is convenient but suboptimal when
+transcoding a number of objects. This is because the method reallocates a new
+codec object for every call. Instead, you can use `transcode(<codec object>,
+data)` method that reuses the allocated object as follows:
+```julia
+using CodecZstd
+strings = ["foo", "bar", "baz"]
+codec = ZstdCompression()
+try
+    for s in strings
+        data = transcode(codec, s)
+        # do something...
+    end
+catch
+    rethrow()
+finally
+    CodecZstd.TranscodingStreams.finalize(codec)
+end
+```
+
 Unread data
 -----------
 

src/TranscodingStreams.jl

@@ -16,6 +16,7 @@ include("stream.jl")
 include("io.jl")
 include("identity.jl")
 include("noop.jl")
+include("transcode.jl")
 include("testtools.jl")
 
 end # module

src/stream.jl

@@ -333,44 +333,6 @@ function Base.write(stream::TranscodingStream, ::EndToken)
 end
 
 
-# Transcode
-# ---------
-
-"""
-    transcode(codec::Codec, data::Vector{UInt8})::Vector{UInt8}
-
-Transcode `data` by applying `codec`.
-
-Examples
---------
-
-```julia
-julia> using CodecZlib
-
-julia> data = Vector{UInt8}("abracadabra");
-
-julia> compressed = transcode(ZlibCompression(), data);
-
-julia> decompressed = transcode(ZlibDecompression(), compressed);
-
-julia> String(decompressed)
-"abracadabra"
-
-```
-"""
-function Base.transcode(codec::Codec, data::Vector{UInt8})
-    # Add `minoutsize` because `transcode` will be called at least two times.
-    buffer2 = Buffer(
-        expectedsize(codec, Memory(data)) + minoutsize(codec, Memory(C_NULL, 0)))
-    mark!(buffer2)
-    stream = TranscodingStream(codec, DevNull, State(Buffer(data), buffer2))
-    write(stream, TOKEN_END)
-    transcoded = takemarked!(buffer2)
-    changemode!(stream, :idle)
-    return transcoded
-end
-
-
 # Utils
 # -----
 

src/testtools.jl

@@ -30,8 +30,11 @@ function test_roundtrip_transcode(encode, decode)
     decoder = decode()
     for n in vcat(0:30, sort!(rand(500:100_000, 30))), alpha in (0x00:0xff, 0x00:0x0f)
         data = rand(alpha, n)
+        Base.Test.@test hash(transcode(decode, transcode(encode, data))) == hash(data)
         Base.Test.@test hash(transcode(decoder, transcode(encoder, data))) == hash(data)
     end
+    finalize(encoder)
+    finalize(decoder)
 end
 
 function test_roundtrip_lines(encoder, decoder)

src/transcode.jl

@@ -0,0 +1,74 @@
+# Transcode
+# =========
+
+"""
+    transcode(::Type{C}, data::Vector{UInt8})::Vector{UInt8} where C<:Codec
+
+Transcode `data` by applying a codec `C()`.
+
+Note that this method does allocation and deallocation of `C()` in every call,
+which is handy but less efficient when transcoding a number of objects.
+`transcode(codec, data)` is a recommended method in terms of performance.
+
+Examples
+--------
+
+```julia
+julia> using CodecZlib
+
+julia> data = b"abracadabra";
+
+julia> compressed = transcode(ZlibCompression, data);
+
+julia> decompressed = transcode(ZlibDecompression, compressed);
+
+julia> String(decompressed)
+"abracadabra"
+
+```
+"""
+function Base.transcode(::Type{C}, data::Vector{UInt8}) where C<:Codec
+    codec = C()
+    try
+        return transcode(codec, data)
+    finally
+        finalize(codec)
+    end
+end
+
+"""
+    transcode(codec::Codec, data::Vector{UInt8})::Vector{UInt8}
+
+Transcode `data` by applying `codec`.
+
+Note that this method does not deallocation of `codec`, which is efficient but
+the caller will need to deallocate `codec`.
+
+Examples
+--------
+
+```julia
+julia> using CodecZlib
+
+julia> data = b"abracadabra";
+
+julia> compressed = transcode(ZlibCompression(), data);
+
+julia> decompressed = transcode(ZlibDecompression(), compressed);
+
+julia> String(decompressed)
+"abracadabra"
+
+```
+"""
+function Base.transcode(codec::Codec, data::Vector{UInt8})
+    # Add `minoutsize` because `transcode` will be called at least two times.
+    buffer2 = Buffer(
+        expectedsize(codec, Memory(data)) + minoutsize(codec, Memory(C_NULL, 0)))
+    mark!(buffer2)
+    stream = TranscodingStream(codec, DevNull, State(Buffer(data), buffer2))
+    write(stream, TOKEN_END)
+    transcoded = takemarked!(buffer2)
+    changemode!(stream, :idle)
+    return transcoded
+end

test/runtests.jl

@@ -169,6 +169,13 @@ end
     @test readavailable(stream) == b"oobar"
     close(stream)
 
+    data = b""
+    @test transcode(Noop, data)  == data
+    @test transcode(Noop, data) !== data
+    data = b"foo"
+    @test transcode(Noop, data)  == data
+    @test transcode(Noop, data) !== data
+
     data = b""
     @test transcode(Noop(), data)  == data
     @test transcode(Noop(), data) !== data