implement Base.position (#68)

Author: bicycle1885

docs/make.jl

@@ -2,15 +2,14 @@ using Documenter
 using TranscodingStreams
 
 makedocs(
-    format=:html,
     sitename="TranscodingStreams.jl",
     modules=[TranscodingStreams],
     pages=["index.md", "examples.md", "reference.md", "devnotes.md"],
-    assets=["assets/custom.css"])
+    assets=["assets/custom.css"],
+)
 
 deploydocs(
     repo="github.com/bicycle1885/TranscodingStreams.jl.git",
-    julia="0.7",
     target="build",
     deps=nothing,
     make=nothing)

docs/src/reference.md

@@ -16,6 +16,7 @@ TranscodingStreams.TOKEN_END
 TranscodingStreams.unsafe_read
 TranscodingStreams.unread
 TranscodingStreams.unsafe_unread
+Base.position(stream::TranscodingStream)
 ```
 
 Statistics

src/buffer.jl

@@ -7,11 +7,11 @@
 # Buffered data are stored in `data` and three position fields are used to keep
 # track of marked data, buffered data and margin.
 #
-#             marked      buffer      margin
-#          |<-------->||<-------->||<-------->|
-#     |....xxxxxxxxxxxxXXXXXXXXXXXX...........|
-#     ^    ^           ^           ^          ^
-#     1    markpos     bufferpos   marginpos  lastindex(data)
+#                     marked      buffer      margin
+#                  |<-------->||<-------->||<-------->|
+#       data   ....xxxxxxxxxxxxXXXXXXXXXXXX............
+#              ^   ^           ^           ^          ^
+#   position   1   markpos     bufferpos   marginpos  lastindex(data)
 #
 # `markpos` is positive iff there are marked data; otherwise it is set to zero.
 # `markpos` ≤ `bufferpos` ≤ `marginpos` must hold whenever possible.

src/stream.jl

@@ -241,6 +241,53 @@ function Base.skip(stream::TranscodingStream, offset::Integer)
     return
 end
 
+"""
+    position(stream::TranscodingStream)
+
+Return the number of bytes read from or written to `stream`.
+
+Note that the returned value will be different from that of the underlying
+stream wrapped by `stream`.  This is because `stream` buffers some data and the
+codec may change the length of data.
+
+Examples
+--------
+
+```
+julia> using CodecZlib, TranscodingStreams
+
+julia> file = open(joinpath(dirname(pathof(CodecZlib)), "..", "test", "abra.gz"));
+
+julia> stream = GzipDecompressorStream(file)
+TranscodingStream{GzipDecompressor,IOStream}(<mode=idle>)
+
+julia> position(stream)
+0
+
+julia> read(stream, 4)
+4-element Array{UInt8,1}:
+ 0x61
+ 0x62
+ 0x72
+ 0x61
+
+julia> position(stream)
+4
+```
+"""
+function Base.position(stream::TranscodingStream)
+    mode = stream.state.mode
+    @checkmode (:idle, :read, :write)
+    if mode === :idle
+        return Int64(0)
+    elseif mode === :read
+        return stats(stream).out
+    elseif mode === :write
+        return stats(stream).in
+    end
+    @assert false "unreachable"
+end
+
 
 # Seek Operations
 # ---------------
@@ -517,7 +564,7 @@ function stats(stream::TranscodingStream)
         in = transcoded_in + buffersize(buffer1)
         out = transcoded_out - buffersize(buffer2)
     else
-        assert(false)
+        @assert false "unreachable"
     end
     return Stats(in, out, transcoded_in, transcoded_out)
 end

test/codecquadruple.jl

@@ -50,6 +50,22 @@ end
     @test read(stream) == b"ffffoooooooo"
     close(stream)
 
+    stream = TranscodingStream(QuadrupleCodec(), IOBuffer("foo"))
+    @test position(stream) === 0
+    read(stream, 3)
+    @test position(stream) === 3
+    read(stream, UInt8)
+    @test position(stream) === 4
+    close(stream)
+
+    stream = TranscodingStream(QuadrupleCodec(), IOBuffer())
+    @test position(stream) === 0
+    write(stream, 0x00)
+    @test position(stream) === 1
+    write(stream, "foo")
+    @test position(stream) === 4
+    close(stream)
+
     # Buffers are shared.
     stream1 = TranscodingStream(QuadrupleCodec(), IOBuffer("foo"))
     stream2 = TranscodingStream(QuadrupleCodec(), stream1)