Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: improve 'hex' Buffer decoding description and examples #41598

Merged
merged 4 commits into from
Jan 21, 2022
Merged

doc: improve 'hex' Buffer decoding description and examples #41598

Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
ccd7221
doc: add missing word in `'hex'` Buffer decoding description
gioragutt Jan 19, 2022
7c9c04b
fix max line width lint issue
gioragutt Jan 19, 2022
eb2fcf5
Update buffer.md
gioragutt Jan 19, 2022
02371aa
Update buffer.md
gioragutt Jan 19, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions doc/api/buffer.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -175,8 +175,8 @@ string into a `Buffer` as decoding.
encoding a `Buffer` to a string, this encoding will omit padding.

* `'hex'`: Encode each byte as two hexadecimal characters. Data truncation
may occur when decoding strings that do exclusively contain valid hexadecimal
characters. See below for an example.
may occur when decoding strings that do not exclusively contain valid
hexadecimal characters. See below for an example.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Unfortunately, it doesn't matter much if the strings exclusively contain hexadecimal characters. In fact, it might be more surprising that Buffer.from truncates data even when it only contains hex digits:

// only hex, still truncated :(
Buffer.from('000', 'hex').toString('hex') === '00'

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it because it reads 2 characters at a time?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nvm, read the docs, which state:

Buffer.from('1a7g', 'hex');
// Prints <Buffer 1a>, data truncated when data ends in single digit ('7').

So the last '0' is truncated because it's a single character, and the hex decoder expects pairs of characters.
So since the third '0' does not have a pairing character, it is truncated.

Perhaps the description should state that? You know, not only in the code example?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
may occur when decoding strings that do not exclusively contain valid
hexadecimal characters. See below for an example.
may occur when decoding strings that do not exclusively consist of an even
number of hexadecimal characters. See below for an example.

Maybe something like this?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think that this, plus another code example (something like 123 -> 12) would be very nice

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@tniessen WDYT?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

SGTM. These are unfortunate oddities that we need to maintain for backward compatibility :(

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I took a better look at the examples and figured that I could achieve the same thing by altering the strings used in the examples.


The following legacy character encodings are also supported:

Expand Down