-
Notifications
You must be signed in to change notification settings - Fork 13.3k
update documentation of tuple/unit structs #33250
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
Changes from 2 commits
993f13a
a14df5c
beec630
e1e4fbd
56f24d7
74e9629
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -163,11 +163,48 @@ struct Point(i32, i32, i32); | |
let black = Color(0, 0, 0); | ||
let origin = Point(0, 0, 0); | ||
``` | ||
|
||
Here, `black` and `origin` are not equal, even though they contain the same | ||
values. | ||
|
||
It is almost always better to use a `struct` than a tuple struct. We | ||
would write `Color` and `Point` like this instead: | ||
The members of a tuple struct may be accessed by dot notation or destructuring | ||
`let`, just like regular tuples: | ||
|
||
```rust | ||
# struct Color(i32, i32, i32); | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Why the '#' at the beginning of the line? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. To hide the line from the documentation, while it's needed to make the example self-contained it's repetitive from the example above. |
||
# struct Point(i32, i32, i32); | ||
# let black = Color(0, 0, 0); | ||
# let origin = Point(0, 0, 0); | ||
let black_r = black.0; | ||
let Point(_, origin_y, origin_z) = origin; | ||
``` | ||
|
||
One case when a tuple struct is very useful is when it has only one element. | ||
We call this the ‘newtype’ pattern, because it allows you to create a new type | ||
that is distinct from its contained value and also expresses its own semantic | ||
meaning: | ||
|
||
```rust | ||
struct Inches(i32); | ||
|
||
let length = Inches(10); | ||
|
||
let Inches(integer_length) = length; | ||
println!("length is {} inches", integer_length); | ||
``` | ||
|
||
As above, you can extract the inner integer type through a destructuring `let`. | ||
In this case, the `let Inches(integer_length)` assigns `10` to `integer_length`. | ||
We could have used dot notation to do the same thing: | ||
|
||
```rust | ||
# struct Inches(i32); | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Why the '#'? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. same as above |
||
# let length = Inches(10); | ||
let integer_length = length.0; | ||
``` | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. You could also talk about There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Hmm, good idea. Or I could just say "this same pattern can be used in a destructuring There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Oh right, then better just quickly talk quickly about There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. added |
||
|
||
It's always possible to use a `struct` than a tuple struct, and can be clearer. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. s/than/instead of/ There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Whoops. |
||
We would write `Color` and `Point` like this instead: | ||
|
||
```rust | ||
struct Color { | ||
|
@@ -187,32 +224,14 @@ Good names are important, and while values in a tuple struct can be | |
referenced with dot notation as well, a `struct` gives us actual names, | ||
rather than positions. | ||
|
||
There _is_ one case when a tuple struct is very useful, though, and that is when | ||
it has only one element. We call this the ‘newtype’ pattern, because | ||
it allows you to create a new type that is distinct from its contained value | ||
and also expresses its own semantic meaning: | ||
|
||
```rust | ||
struct Inches(i32); | ||
|
||
let length = Inches(10); | ||
|
||
let Inches(integer_length) = length; | ||
println!("length is {} inches", integer_length); | ||
``` | ||
|
||
As you can see here, you can extract the inner integer type through a | ||
destructuring `let`, as with regular tuples. In this case, the | ||
`let Inches(integer_length)` assigns `10` to `integer_length`. | ||
|
||
# Unit-like structs | ||
|
||
You can define a `struct` with no members at all: | ||
|
||
```rust | ||
struct Electron; | ||
struct Electron {} | ||
|
||
let x = Electron; | ||
let x = Electron {}; | ||
``` | ||
|
||
Such a `struct` is called ‘unit-like’ because it resembles the empty | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This sentence could be confusing even though I get what it is trying to say.
Color(0, 0, 0)
andColor(0, 0, 0)
are also not "equal" in some sense because we didn't derivePartialEq
.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Maybe it should just say "are not the same type, even though they contain the same values".
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Excellent idea! Your second suggestion is just perfect. Could you replace the sentence please?