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.

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: clarify behavior of byteLength with 'base64' #11238

Merged
merged 1 commit into from Feb 9, 2017

Conversation

Projects
None yet
6 participants
@seishun
Member

seishun commented Feb 8, 2017

Ref: #11165

Checklist
  • documentation is changed or added
  • commit message follows commit guidelines
Affected core subsystem(s)

doc

@jasnell

jasnell approved these changes Feb 8, 2017

Couple of nits but otherwise LGTM

Show outdated Hide outdated doc/api/buffer.md
@@ -618,6 +618,10 @@ Returns the actual byte length of a string. This is not the same as
[`String.prototype.length`] since that returns the number of *characters* in
a string.
_Note_ that for `'base64'`, this function assumes valid input. For strings that

This comment has been minimized.

@jasnell

jasnell Feb 8, 2017

Member

For consistency, please s/_Note_/*Note*:

@jasnell

jasnell Feb 8, 2017

Member

For consistency, please s/_Note_/*Note*:

This comment has been minimized.

@addaleax

addaleax Feb 8, 2017

Member

This isn’t specific to base64, it applies at least to hex, too:

> Buffer.byteLength('aa  ', 'hex')
2
> Buffer.from('aa  ', 'hex').length
1

(I think it’s only those two encodings but I didn’t double-check.)

@addaleax

addaleax Feb 8, 2017

Member

This isn’t specific to base64, it applies at least to hex, too:

> Buffer.byteLength('aa  ', 'hex')
2
> Buffer.from('aa  ', 'hex').length
1

(I think it’s only those two encodings but I didn’t double-check.)

This comment has been minimized.

@seishun

seishun Feb 8, 2017

Member

@addaleax oh indeed. That makes wording it a bit more complicated...

@seishun

seishun Feb 8, 2017

Member

@addaleax oh indeed. That makes wording it a bit more complicated...

Show outdated Hide outdated doc/api/buffer.md
@@ -618,6 +618,10 @@ Returns the actual byte length of a string. This is not the same as
[`String.prototype.length`] since that returns the number of *characters* in
a string.
_Note_ that for `'base64'`, this function assumes valid input. For strings that
aren't valid Base64, the return value might be greater than the length of a

This comment has been minimized.

@jasnell

jasnell Feb 8, 2017

Member

nit: s/aren't/are not

@jasnell

jasnell Feb 8, 2017

Member

nit: s/aren't/are not

Show outdated Hide outdated doc/api/buffer.md
@@ -618,6 +618,10 @@ Returns the actual byte length of a string. This is not the same as
[`String.prototype.length`] since that returns the number of *characters* in
a string.
*Note* that for `'base64'` and `'hex'`, this function assumes valid input. For
strings that do not contain Base64/Hex-encoded data, the return value might be

This comment has been minimized.

@addaleax

addaleax Feb 8, 2017

Member

nit: Maybe mention that the method doesn’t account for whitespace in the input … for some people that might be included in “invalid”, but that’s kind of subjective…

@addaleax

addaleax Feb 8, 2017

Member

nit: Maybe mention that the method doesn’t account for whitespace in the input … for some people that might be included in “invalid”, but that’s kind of subjective…

@seishun

This comment has been minimized.

Show comment
Hide comment
@seishun

seishun Feb 8, 2017

Member

Done, but now I have trouble coming up with a descriptive commit message. Any better suggestions?

Member

seishun commented Feb 8, 2017

Done, but now I have trouble coming up with a descriptive commit message. Any better suggestions?

@addaleax

LGTM

“doc: clarify the behavior of byteLength” (or “doc: clarify the behavior of Buffer.byteLength” if you feel like it) sounds perfectly fine to me :)

@@ -618,6 +618,10 @@ Returns the actual byte length of a string. This is not the same as
[`String.prototype.length`] since that returns the number of *characters* in
a string.
*Note* that for `'base64'` and `'hex'`, this function assumes valid input. For
strings that contain non-Base64/Hex-encoded data (e.g. whitespace), the return
value might be greater than the length of a `Buffer` created from the string.

This comment has been minimized.

@joyeecheung

joyeecheung Feb 8, 2017

Member

The return value could be smaller too (e.g. Buffer.byteLength('1345 4 ', 'hex') === 3, Buffer.from('1345 4 ').byteLength === 7), but then since the data is invalid it's just hard to say. Maybe just say something like the return value is meaningless and should not be used?

@joyeecheung

joyeecheung Feb 8, 2017

Member

The return value could be smaller too (e.g. Buffer.byteLength('1345 4 ', 'hex') === 3, Buffer.from('1345 4 ').byteLength === 7), but then since the data is invalid it's just hard to say. Maybe just say something like the return value is meaningless and should not be used?

This comment has been minimized.

@joyeecheung

joyeecheung Feb 8, 2017

Member

Hmm, wait, I forgot to pass hex to Buffer.from('1345 4 '), that one would just throws TypeError: Invalid hex string, so there is nothing to compare :/

@joyeecheung

joyeecheung Feb 8, 2017

Member

Hmm, wait, I forgot to pass hex to Buffer.from('1345 4 '), that one would just throws TypeError: Invalid hex string, so there is nothing to compare :/

This comment has been minimized.

@seishun

seishun Feb 8, 2017

Member

Yeah, logically there is no way for it to be smaller. That would imply that you can encode more data by using an invalid string than a valid string.

It's not completely meaningless - e.g. if you allocate a Buffer with the size at least Buffer.byteLength, then the actual buffer will fit in it. Although I can't imagine a use case for it.

@seishun

seishun Feb 8, 2017

Member

Yeah, logically there is no way for it to be smaller. That would imply that you can encode more data by using an invalid string than a valid string.

It's not completely meaningless - e.g. if you allocate a Buffer with the size at least Buffer.byteLength, then the actual buffer will fit in it. Although I can't imagine a use case for it.

@targos

targos approved these changes Feb 8, 2017

@seishun seishun merged commit 271d50a into nodejs:master Feb 9, 2017

italoacasas added a commit that referenced this pull request Feb 13, 2017

doc: clarify the behavior of Buffer.byteLength
PR-URL: #11238
Refs: #11165
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Michaël Zasso <targos@protonmail.com>

italoacasas added a commit to italoacasas/node that referenced this pull request Feb 14, 2017

doc: clarify the behavior of Buffer.byteLength
PR-URL: nodejs#11238
Refs: nodejs#11165
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Michaël Zasso <targos@protonmail.com>

KryDos added a commit to KryDos/node that referenced this pull request Feb 25, 2017

doc: clarify the behavior of Buffer.byteLength
PR-URL: nodejs#11238
Refs: nodejs#11165
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Michaël Zasso <targos@protonmail.com>

jasnell added a commit that referenced this pull request Mar 7, 2017

doc: clarify the behavior of Buffer.byteLength
PR-URL: #11238
Refs: #11165
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Michaël Zasso <targos@protonmail.com>

jasnell added a commit that referenced this pull request Mar 7, 2017

doc: clarify the behavior of Buffer.byteLength
PR-URL: #11238
Refs: #11165
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Michaël Zasso <targos@protonmail.com>

MylesBorins added a commit that referenced this pull request Mar 9, 2017

doc: clarify the behavior of Buffer.byteLength
PR-URL: #11238
Refs: #11165
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Michaël Zasso <targos@protonmail.com>

@MylesBorins MylesBorins referenced this pull request Mar 9, 2017

Merged

v6.10.1 proposal #11759

MylesBorins added a commit that referenced this pull request Mar 9, 2017

doc: clarify the behavior of Buffer.byteLength
PR-URL: #11238
Refs: #11165
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Michaël Zasso <targos@protonmail.com>

@MylesBorins MylesBorins referenced this pull request Mar 9, 2017

Merged

v4.8.1 proposal #11760

@seishun seishun deleted the seishun:doc-bytelength branch Oct 19, 2017

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