ralfbiedert / cheats.rs

Rust Language Cheat Sheet - https://cheats.rs
https://cheats.rs
4.14k stars 395 forks source link

updated the wording of the References & Pointers intro text #158

Closed fujiapple852 closed 2 years ago

fujiapple852 commented 2 years ago

The current wording could be interpreted to mean that mut references and *mut raw pointers are "identical":

References give safe access to other memory, raw pointers unsafe access. The respective mut types are identical.

I had a go at updating the wording to make it clearer.

ralfbiedert commented 2 years ago

Thanks for the PR.

The current wording could be interpreted to mean that mut references and *mut raw pointers are "identical":

From a "Data Layout" perspective they are identical. Right now the paragraph reads:

[1] References give safe access to other memory, raw pointers unsafe access. [2] The respective mut types are identical.

Wrt. your PR changes the "other" in [1] is there to make it clear that references handle some "3rd party memory", in contrast to bindings (e.g., let x), where x is the "first-party" name of a specific stack location. That said, while I'm mildly in favor of keeping "other" I'm generally open to removing it if people have strong linguistic opinions.

About changing [2], it appears we interpret the function of that sentence differently. My intent was to say "Let's not bother drawing &mut T as it will look like &T. In contrast, you seem to read it as "&mut T" is functionally (from a language perspective) identical to &T?

fujiapple852 commented 2 years ago

Wrt. your PR changes the "other" in [1] is there to make it clear that references handle some "3rd party memory", in contrast to bindings (e.g., let x), where x is the "first-party" name of a specific stack location.

I removed the word "other" as it wasn't clear to me what it was defined to be in this context. I don't know what a good name for "3rd party memory" would be, perhaps "referent" (of the reference) fits?

the Rust book dodges this naming-things-is-hard problem and defines it by saying "A reference is like a pointer in that it’s an address we can follow to access data stored at that address that is owned by some other variable."

It is a very minor point and I think it is perfectly fine to leave it as-was unless a clearer alternative can be found.

My intent was to say "Let's not bother drawing &mut T as it will look like &T. In contrast, you seem to read it as "&mut T" is functionally (from a language perspective) identical to &T?

Yes almost; I actually read it as &mut T and *mut T are functionally (from a language perspective) identical to each other (as I read *mut T and &mut as the "respective" things in [1]).

My (poor) attempt at rewording was to try any clarify that it means exactly what you said above; i.e. "Let's not bother drawing &mut T as it will look like &T".

How about this?

"References give safe access to the referent, raw pointers unsafe access." "The corresponding mut types have an identical data layout to their immutable counterparts."

And finally I just wanted to remember to say thank you for taking the time to create and maintain this very useful resource!

ralfbiedert commented 2 years ago

"References give safe access to the referent, raw pointers unsafe access." "The corresponding mut types have an identical data layout to their immutable counterparts."

Second part sounds good. I just don't like "referents" here, as it makes the explanation mildly cyclic (if I don't know what references are, I probably also won't know what referents are).

I'll accept this PR to streamline the site update (will change first sentence to "3rd party memory"). Feel free to still comment / disagree on wording, can happily push another update.