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

Jump to bottom

[std] clarify ffi C string nul term & length discussion #56140

Closed
wants to merge 1 commit into from
Closed

[std] clarify ffi C string nul term & length discussion #56140

wants to merge 1 commit into from

Conversation

jnqnfe
Copy link
Contributor

@jnqnfe jnqnfe commented Nov 21, 2018

re-written the paragraph, including:

  • Changed use of "calculated" to "measured". "calculated" just sounds
    wrong, giving a false impression of what strlen() does.
  • Changed "C code must manually call a function". Firstly, "manually"?
    Secondly, a function is called in Rust also... the difference is in
    what the function does - measurement v.s. reading an attribute...
  • Finished that sentence in actually stating the operation that is done.
  • Changed use of "buffer length" to "string length". Use of the term
    "buffer" here was bound to confuse.

@rust-highfive
Copy link
Collaborator

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @TimNN (or someone else) soon.

If any changes to this PR are deemed necessary, please add them as extra commits. This ensures that the reviewer can see what has changed since they last reviewed the code. Due to the way GitHub handles out-of-date commits, this should also make it reasonably obvious what issues have or haven't been addressed. Large or tricky changes may require several passes of review and changes.

Please see the contribution instructions for more information.

@rust-highfive rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Nov 21, 2018
@TimNN
Copy link
Contributor

TimNN commented Nov 27, 2018

  • Changed use of "calculated" to "measured". "calculated" just sounds
    wrong, giving a false impression of what strlen() does.

I don't agree with the change to measured. My intuition (as a non-native English speaker) is that "measure" implies measuring something physical (e.g. distance, time). The dictionary seems to confirm that intuition.

which scans through the bytes of the string looking for the nul character marking the end, keeping a count of characters as it does so.

I don't think describing how strlen may-or-may-not be implemented internally is appropriate here. I'd rather focus on what it returns (essentially the position of the first 0 byte).

@jnqnfe
Copy link
Contributor Author

jnqnfe commented Nov 28, 2018

I've rewritten it again, hopefully you'll like v2 better. Sorry for the delay, I've got very irregular internet access currently.

I don't agree with the change to measured. My intuition (as a non-native English speaker) is that "measure" implies measuring something physical (e.g. distance, time). The dictionary seems to confirm that intuition.

Ok, I wasn't 100% happy with it either, but it was better. I've used "counting" instead in v2.

I don't think describing how strlen may-or-may-not be implemented internally is appropriate here. I'd rather focus on what it returns (essentially the position of the first 0 byte).

I think the discussion necessitates brief mention that it involves counting. I hope you like the revised text more.

@bors
Copy link
Contributor

bors commented Dec 8, 2018

☔ The latest upstream changes (presumably #56578) made this pull request unmergeable. Please resolve the merge conflicts.

@jnqnfe
clarify ffi C string nul term & length discussion
85c6548 
re-written the paragraph, including:
 - Changed use of "calculated" to "count". "calculated" just sounds
   wrong, giving a false impression of what strlen() does.
 - Changed "C code must manually call a function". Firstly, "manually"?
   Secondly, a function is called in Rust also... the difference is in
   what the function does - counting v.s. reading an attribute...
@Dylan-DPC-zz
Copy link

ping from triage @TimNN awaiting your review on this

@TimNN
Copy link
Contributor

TimNN commented Jan 15, 2019

I'm not quite sure about this PR. Some parts are certainly improved, I think, but I'm not sure about other parts of the docs here.

cc @rust-lang/docs: I would appreciated your input here.

@GuillaumeGomez
Copy link
Member

I preferred the original version. :-/

@Dylan-DPC-zz Dylan-DPC-zz added S-waiting-on-team Status: Awaiting decision from the relevant subteam (see the T-<team> label). and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Feb 11, 2019
@Centril
Copy link
Contributor

Centril commented Mar 30, 2019

cc @rust-lang/docs

@Centril
Copy link
Contributor

Centril commented May 29, 2019

r? @steveklabnik

@rust-highfive rust-highfive assigned steveklabnik and unassigned TimNN May 29, 2019
QuietMisdreavus
QuietMisdreavus reviewed Jun 10, 2019
View reviewed changes
Copy link
Member

@QuietMisdreavus QuietMisdreavus left a comment

Choose a reason for hiding this comment

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

While we're in this section, i kind of want to either capitalize the use of NUL or write it as the word "null" - otherwise, to me it just looks like someone kept misspelling "null".

src/libstd/ffi/mod.rs
//! length is stored); in C it is an O(length) operation because the
//! length needs to be computed by scanning the string for the nul
//! terminator.
//! end. The length of the string is not stored, but has to be determined
Copy link
Member

Choose a reason for hiding this comment

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

I feel like "calculated" is still a better word here? "Determined" feels like it implies that there's some kind of conceptual decision-making going on, but "calculated" feels more like it's a rote procedure that needs to be run through to figure out the length. I could be reading way too far into this, though. >_>

src/libstd/ffi/mod.rs
//! nul that marks its end, counting as it goes. The value returned by
//! common functions that perform this, is effectively the index position
//! of the nul, and thus the string length (in terms of buffer size) is
//! actually len+1. Rust strings don't have a nul terminator, their
Copy link
Member

Choose a reason for hiding this comment

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

Part of me wants to add some types to single out what "Rust strings" actually means. Something like:

Rust strings (like &str and String) don't have a nul terminator...

On the other hand, there are many more "string" types in Rust, and e.g. OsString also stores its length separately instead of having a null byte to mark the end. Would it be too confusing to single out these types and leave out the others?

@Mark-Simulacrum
Copy link
Member

I'm going to close this PR as it's been idle for quite a while. If you have some time to address the review comments then we'd be happy to either reopen this PR or see a new PR from you in the future. Thanks!

@apiraino apiraino removed the S-waiting-on-team Status: Awaiting decision from the relevant subteam (see the T-<team> label). label May 25, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@QuietMisdreavus QuietMisdreavus QuietMisdreavus left review comments

Assignees

@steveklabnik steveklabnik

Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.