haskell / haskell/bytestring

hGet documentation on return type is incorrect

Open
#588 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
Haskell
Stars
301
Forks
144
Avg merge
7d 22h
Merged PRs (30d)
1

Description

Hello,

See https://github.com/haskell/bytestring/blob/66414042e5a0ec08b9bcfb924c396c68a5bd8cdb/Data/ByteString.hs#L1927 . It states it returns the bytes read, up to `n`. But that is the behavior of the underlying hGetBuf, not hGet. hGet itself returns a `ByteString` with length up to `n`.

I think it would also be ergonomic to call out with emphasis that near EOF the returned bytestring can be shorter. (On a quick skimming, I assumed that `hGet` would fail / return empty if not enough bytes are available, while `hGetSome` would return the partial bytes. But turns out the difference is rather in terms of blocking or not in case data is not yet available?)

Also the doc `Like hGet, except that a shorter ByteStringmay be returned if there are not enough bytes immediately available to satisfy the whole request.` on `hGetSome` adds to the confusion. Kind of implies to the unaware reader that `hGet` would always return non-shorter bytestring.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.