#5861: bytestring: incorrect documentation for hGetContents
-------------------------------+--------------------------------------------
Reporter: kmcallister | Owner:
Type: bug | Status: new
Priority: normal | Component: libraries (other)
Version: | Keywords: bytestring
Os: Unknown/Multiple | Architecture: Unknown/Multiple
Failure: Documentation bug | Testcase:
Blockedby: | Blocking:
Related: |
-------------------------------+--------------------------------------------
(I guess this is the `ByteString` bug tracker? This copies an email I
sent directly to Don Stewart and Duncan Coutts.)
The current documentation [1] for `Data.ByteString.hGetContents` says:
"As with `hGet`, the string representation in the file is assumed to be
ISO-8859-1."
This confuses me -- why would `ByteString` care what the "string
representation" of a file is, or that it even has one?
Perhaps it's for the benefit of this function's appearance in
`ByteString.Char8`. But the caveats of that module are widely documented
throughout, and it's a hack that most people shouldn't use. I think the
docs for `hGetContents` should reflect the "main" module and its intended
use on possibly opaque binary data.
Don Stewart suggested that this is "a property of the underlying handle",
but I have confirmed that `ByteString` is insensitive to the handle's
designated encoding.
{{{
$ cat test-bytestring-handle-encoding.hs
import System.IO
import qualified Data.ByteString as B
test :: TextEncoding -> IO ()
test enc = do
hdl <- openFile "snowman" ReadMode
hSetEncoding hdl enc
B.hGetContents hdl >>= (print . B.unpack)
hClose hdl
main :: IO ()
main = do
test utf8
test utf32
test latin1
$ ghc -V
The Glorious Glasgow Haskell Compilation System, version 7.0.4
$ ghc-pkg list bytestring
/var/lib/ghc/package.conf.d
bytestring-0.9.1.10
$ echo -ne '\xe2\x98\x83' > snowman
$ hexdump -C snowman
00000000 e2 98 83 |...|
00000003
$ runhaskell test-bytestring-handle-encoding.hs
[226,152,131]
[226,152,131]
[226,152,131]
}}}
[1]
http://hackage.haskell.org/packages/archive/bytestring/0.9.2.0/doc/html
/Data-ByteString.html#v:hGetContents
--
Ticket URL: <http://hackage.haskell.org/trac/ghc/ticket/5861>
GHC <http://www.haskell.org/ghc/>
The Glasgow Haskell Compiler
_______________________________________________
Glasgow-haskell-bugs mailing list
[email protected]
http://www.haskell.org/mailman/listinfo/glasgow-haskell-bugs
