Add read convenience methods

These methods differ a bit from existing ones since they don't return strings
(for which the UTF-8 encoding is known thanks to their type), but bytes without any
encoding information. But this shouldn't be too confusing, and it can be useful
e.g. for CSV.jl which expects a vector of bytes in UTF-8 rather than a string.

Author: nalimilan

README.md

@@ -105,6 +105,12 @@ noël
 
 julia> readuntil(path, enc"UTF-16", "ë")
 "café\nno"
+
+julia> String(read(path, enc"UTF-16"))
+"café\nnoël"
+
+julia> String(read(path, 5, enc"UTF-16"))
+"café"
 ```
 
 When performing more complex operations on an encoded text file, it will often be easier to specify the encoding only once when opening it. The resulting I/O stream can then be passed to functions that are unaware of encodings (i.e. that assume UTF-8 text):

src/StringEncodings.jl

@@ -202,7 +202,7 @@ end
 
 Returns a new write-only I/O stream, which converts any text in the encoding `from`
 written to it into text in the encoding `to` written to `stream`. Calling `close` on the
-stream is necessary to complete the encoding (but does not close `stream`).
+returned object is necessary to complete the encoding (but it does not close `stream`).
 
 `to` and `from` can be specified either as a string or as an `Encoding` object.
 """
@@ -404,13 +404,26 @@ function open(fname::AbstractString, enc::Encoding, mode::AbstractString)
 end
 
 """
+    read(stream::IO, [nb::Integer,] enc::Encoding)
+    read(filename::AbstractString, [nb::Integer,] enc::Encoding)
     read(stream::IO, ::Type{String}, enc::Encoding)
     read(filename::AbstractString, ::Type{String}, enc::Encoding)
 
-Methods to read text in character encoding `enc`.
+Methods to read text in character encoding `enc`. See documentation for corresponding methods
+without the `enc` argument for details.
 """
-Base.read(s::IO, ::Type{String}, enc::Encoding) = read(StringDecoder(s, enc), String)
-Base.read(filename::AbstractString, ::Type{String}, enc::Encoding) = open(io->read(io, String, enc), filename)
+Base.read(s::IO, enc::Encoding) =
+    read(StringDecoder(s, enc))
+Base.read(filename::AbstractString, enc::Encoding) =
+    open(io->read(io, enc), filename)
+Base.read(s::IO, nb::Integer, enc::Encoding) =
+    read(StringDecoder(s, enc), nb)
+Base.read(filename::AbstractString, nb::Integer, enc::Encoding) =
+    open(io->read(io, nb, enc), filename)
+Base.read(s::IO, ::Type{String}, enc::Encoding) =
+    read(StringDecoder(s, enc), String)
+Base.read(filename::AbstractString, ::Type{String}, enc::Encoding) =
+    open(io->read(io, String, enc), filename)
 
 """
     readline(stream::IO, enc::Encoding; keep::Bool=false)

test/runtests.jl

@@ -141,6 +141,18 @@ mktemp() do path, io
         write(io, s)
     end
 
+    @test String(read(path, enc"ISO-2022-JP")) == s
+    @test String(open(io->read(io, enc"ISO-2022-JP"), path)) == s
+    @test String(open(io->read(io), path, enc"ISO-2022-JP")) == s
+
+    @test String(read(path, 1000, enc"ISO-2022-JP")) == s
+    @test String(open(io->read(io, 1000, enc"ISO-2022-JP"), path)) == s
+    @test String(open(io->read(io, 1000), path, enc"ISO-2022-JP")) == s
+
+    @test String(read(path, 10, enc"ISO-2022-JP")) == first(s, 10)
+    @test String(open(io->read(io, 10, enc"ISO-2022-JP"), path)) == first(s, 10)
+    @test String(open(io->read(io, 10), path, enc"ISO-2022-JP")) == first(s, 10)
+
     @test read(path, String, enc"ISO-2022-JP") == s
     @test open(io->read(io, String, enc"ISO-2022-JP"), path) == s
     @test open(io->read(io, String), path, enc"ISO-2022-JP") == s