Skip to content

Commit 993f13a

Browse files
committed
update documentation of tuple/unit structs
I made the "tuple structs are useless" editorializing a bit weaker and moved it to the end. Feel free to overrule me on that. I also added an example of how to unpack a tuple struct with dot notation, because it came up on IRC. `braced_empty_structs` is stable now, so I updated the example for unit-like structs to use that syntax. Should we show both ways? cc @ubsan r? @steveklabnik or @GuillameGomez
1 parent cda7c1c commit 993f13a

File tree

1 file changed

+41
-22
lines changed

1 file changed

+41
-22
lines changed

src/doc/book/structs.md

Lines changed: 41 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -163,11 +163,48 @@ struct Point(i32, i32, i32);
163163
let black = Color(0, 0, 0);
164164
let origin = Point(0, 0, 0);
165165
```
166+
166167
Here, `black` and `origin` are not equal, even though they contain the same
167168
values.
168169

169-
It is almost always better to use a `struct` than a tuple struct. We
170-
would write `Color` and `Point` like this instead:
170+
The members of a tuple struct may be accessed by dot notation or destructuring
171+
`let`, just like regular tuples:
172+
173+
```rust
174+
# struct Color(i32, i32, i32);
175+
# struct Point(i32, i32, i32);
176+
# let black = Color(0, 0, 0);
177+
# let origin = Point(0, 0, 0);
178+
let black_r = black.0;
179+
let (_, origin_y, origin_z) = origin;
180+
```
181+
182+
One case when a tuple struct is very useful is when it has only one element.
183+
We call this the ‘newtype’ pattern, because it allows you to create a new type
184+
that is distinct from its contained value and also expresses its own semantic
185+
meaning:
186+
187+
```rust
188+
struct Inches(i32);
189+
190+
let length = Inches(10);
191+
192+
let Inches(integer_length) = length;
193+
println!("length is {} inches", integer_length);
194+
```
195+
196+
As above, you can extract the inner integer type through a destructuring `let`.
197+
In this case, the `let Inches(integer_length)` assigns `10` to `integer_length`.
198+
We could have used dot notation to do the same thing:
199+
200+
```rust
201+
# struct Inches(i32);
202+
# let length = Inches(10);
203+
let integer_length = length.0;
204+
```
205+
206+
It's always possible to use a `struct` than a tuple struct, and can be clearer.
207+
We would write `Color` and `Point` like this instead:
171208

172209
```rust
173210
struct Color {
@@ -187,32 +224,14 @@ Good names are important, and while values in a tuple struct can be
187224
referenced with dot notation as well, a `struct` gives us actual names,
188225
rather than positions.
189226

190-
There _is_ one case when a tuple struct is very useful, though, and that is when
191-
it has only one element. We call this the ‘newtype’ pattern, because
192-
it allows you to create a new type that is distinct from its contained value
193-
and also expresses its own semantic meaning:
194-
195-
```rust
196-
struct Inches(i32);
197-
198-
let length = Inches(10);
199-
200-
let Inches(integer_length) = length;
201-
println!("length is {} inches", integer_length);
202-
```
203-
204-
As you can see here, you can extract the inner integer type through a
205-
destructuring `let`, as with regular tuples. In this case, the
206-
`let Inches(integer_length)` assigns `10` to `integer_length`.
207-
208227
# Unit-like structs
209228

210229
You can define a `struct` with no members at all:
211230

212231
```rust
213-
struct Electron;
232+
struct Electron {}
214233

215-
let x = Electron;
234+
let x = Electron {};
216235
```
217236

218237
Such a `struct` is called ‘unit-like’ because it resembles the empty

0 commit comments

Comments
 (0)