Skip to content

Fix IO.read/2 docs: integer count is in characters, not bytes#15549

Merged
josevalim merged 1 commit into
elixir-lang:mainfrom
nseaSeb:fix-io-read-doc-chars
Jul 8, 2026
Merged

Fix IO.read/2 docs: integer count is in characters, not bytes#15549
josevalim merged 1 commit into
elixir-lang:mainfrom
nseaSeb:fix-io-read-doc-chars

Conversation

@nseaSeb

@nseaSeb nseaSeb commented Jul 8, 2026

Copy link
Copy Markdown
Contributor

IO.read/2 is the Unicode-safe reader and delegates an integer count to :io.get_chars/3, which counts characters, not bytes. The docs were copied from IO.binread/2 (the byte-oriented, Unicode-unsafe reader), so they incorrectly described the integer argument as a number of bytes and carried binread/2's "preferred mode for reading non-textual inputs" note. This also contradicted read/2's own return description, which already documents the result as "the output characters".

Assisted-by: Claude Code:claude-opus-4-8

`IO.read/2` is the Unicode-safe reader and delegates an integer count
to `:io.get_chars/3`, which counts characters, not bytes. The docs were
copied from `IO.binread/2` (the byte-oriented, Unicode-unsafe reader),
so they incorrectly described the integer argument as a number of bytes
and carried binread/2's "preferred mode for reading non-textual inputs"
note. This also contradicted read/2's own return description, which
already documents the result as "the output characters".

Assisted-by: Claude Code:claude-opus-4-8
Signed-off-by: nseaSeb <nseaprotector@gmail.com>
@josevalim josevalim merged commit 9e687da into elixir-lang:main Jul 8, 2026
@AlexGx

AlexGx commented Jul 8, 2026

Copy link
Copy Markdown
Contributor

IMO its a not fully correct change. Characters is too broad and imprecise.

If the device is in Unicode mode, the count is number of Unicode code points. Otherwise, the count is the number of bytes.

Quick proof

echo "José" > test.txt

iex(1)> {:ok, file} = File.open("test.txt")
{:ok, #PID<0.109.0>}
iex(2)> IO.read(file, 4)
"JosÃ"
iex(3)> {:ok, file2} = File.open("test.txt", [:utf8])
{:ok, #PID<0.110.0>}
iex(4)> IO.read(file2, 4)
"José"

Also Id suggest to update returns section to smth like:

- `data` - the data read from the device as a binary or charlist,
    depending on the device mode

@josevalim

Copy link
Copy Markdown
Member

Thanks, I pushed a clearer description!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

3 participants