#132 allow users to optionally provide an output buffer when calling transcode

src/transcode.jl

@@ -2,7 +2,7 @@
 # =========
 
 """
-    transcode(::Type{C}, data::Vector{UInt8})::Vector{UInt8} where C<:Codec
+    transcode(::Type{C}, data::ByteData)::ByteData where {C<:Codec}
 
 Transcode `data` by applying a codec `C()`.
 
@@ -27,7 +27,7 @@ julia> String(decompressed)
 
 ```
 """
-function Base.transcode(::Type{C}, data::ByteData) where C<:Codec
+function Base.transcode(::Type{C}, data::ByteData) where {C<:Codec}
     codec = C()
     initialize(codec)
     try
@@ -37,48 +37,11 @@ function Base.transcode(::Type{C}, data::ByteData) where C<:Codec
     end
 end
 
-"""
-    transcode(codec::Codec, data::Vector{UInt8})::Vector{UInt8}
-
-Transcode `data` by applying `codec`.
-
-Note that this method does not initialize or finalize `codec`. This is
-efficient when you transcode a number of pieces of data, but you need to call
-[`TranscodingStreams.initialize`](@ref) and
-[`TranscodingStreams.finalize`](@ref) explicitly.
-
-Examples
---------
-
-```julia
-julia> using CodecZlib
-
-julia> data = b"abracadabra";
-
-julia> codec = ZlibCompressor();
-
-julia> TranscodingStreams.initialize(codec)
-
-julia> compressed = transcode(codec, data);
-
-julia> TranscodingStreams.finalize(codec)
-
-julia> codec = ZlibDecompressor();
-
-julia> TranscodingStreams.initialize(codec)
-
-julia> decompressed = transcode(codec, compressed);
-
-julia> TranscodingStreams.finalize(codec)
-
-julia> String(decompressed)
-"abracadabra"
-
-```
-"""
-function Base.transcode(codec::Codec, data::ByteData)
-    input = Buffer(data)
-    output = Buffer(initial_output_size(codec, buffermem(input)))
+function Base.transcode(
+    codec::Codec,
+    input::Buffer,
+    output::Buffer = Buffer(initial_output_size(codec, buffermem(input))),
+)
     error = Error()
     code = startproc(codec, :write, error)
     if code === :error
@@ -121,6 +84,95 @@ function Base.transcode(codec::Codec, data::ByteData)
     throw(error[])
 end
 
+"""
+    transcode(codec::Codec, data::ByteData)::ByteData
+
+Transcode `data` by applying `codec`.
+
+Note that this method does not initialize or finalize `codec`. This is
+efficient when you transcode a number of pieces of data, but you need to call
+[`TranscodingStreams.initialize`](@ref) and
+[`TranscodingStreams.finalize`](@ref) explicitly.
+
+Examples
+--------
+
+```julia
+julia> using CodecZlib
+
+julia> data = b"abracadabra";
+
+julia> codec = ZlibCompressor();
+
+julia> TranscodingStreams.initialize(codec)
+
+julia> compressed = transcode(codec, data);
+
+julia> TranscodingStreams.finalize(codec)
+
+julia> codec = ZlibDecompressor();
+
+julia> TranscodingStreams.initialize(codec)
+
+julia> decompressed = transcode(codec, compressed);
+
+julia> TranscodingStreams.finalize(codec)
+
+julia> String(decompressed)
+"abracadabra"
+
+```
+"""
+Base.transcode(codec::Codec, data::ByteData) = transcode(codec, Buffer(data))
+
+Base.transcode(codec::Codec, data::ByteData, output::Buffer) =
+    transcode(codec, Buffer(data), output)
+
+"""
+    transcode(codec::Codec, data::ByteData, output::ByteData)::ByteData
+
+Transcode `data` by applying `codec` and store the results in `output`.
+
+Note that this method does not initialize or finalize `codec`. This is
+efficient when you transcode a number of pieces of data, but you need to call
+[`TranscodingStreams.initialize`](@ref) and
+[`TranscodingStreams.finalize`](@ref) explicitly.
+
+Examples
+--------
+
+```julia
+julia> using CodecZlib
+
+julia> data julia> data = b"abracadabra";
+= b"abracadabra";
+
+julia> codec = ZlibCompressor();
+
+julia> TranscodingStreams.initialize(codec)
+
+julia> compressed = Vector{UInt8}()
+
+julia> transcode(codec, data, compressed);
+
+julia> TranscodingStreams.finalize(codec)
+
+julia> codec = ZlibDecompressor();
+
+julia> TranscodingStreams.initialize(codec)
+
+julia> decompressed = transcode(codec, compressed);
+
+julia> TranscodingStreams.finalize(codec)
+
+julia> String(decompressed)
+"abracadabra"
+
+```
+"""
+Base.transcode(codec::Codec, data::ByteData, output::ByteData) =
+    transcode(codec, data, Buffer(output))
+
 # Return the initial output buffer size.
 function initial_output_size(codec::Codec, input::Memory)
     return max(