From 993f13a2cf125610dc6a34bf68aa6afd87a723d6 Mon Sep 17 00:00:00 2001 From: Alex Burka Date: Wed, 27 Apr 2016 23:29:49 -0400 Subject: [PATCH 1/6] 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 --- src/doc/book/structs.md | 63 +++++++++++++++++++++++++++-------------- 1 file changed, 41 insertions(+), 22 deletions(-) diff --git a/src/doc/book/structs.md b/src/doc/book/structs.md index b2fddf33627..404eac25308 100644 --- a/src/doc/book/structs.md +++ b/src/doc/book/structs.md @@ -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); +# struct Point(i32, i32, i32); +# let black = Color(0, 0, 0); +# let origin = Point(0, 0, 0); +let black_r = black.0; +let (_, 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); +# let length = Inches(10); +let integer_length = length.0; +``` + +It's always possible to use a `struct` than a tuple struct, and can be clearer. +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 From a14df5cc64053beabc03ceb5b6b1352cb48d166c Mon Sep 17 00:00:00 2001 From: Alex Burka Date: Thu, 28 Apr 2016 01:20:54 -0400 Subject: [PATCH 2/6] fix Point destructuring example --- src/doc/book/structs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/book/structs.md b/src/doc/book/structs.md index 404eac25308..44a6d282c00 100644 --- a/src/doc/book/structs.md +++ b/src/doc/book/structs.md @@ -176,7 +176,7 @@ The members of a tuple struct may be accessed by dot notation or destructuring # let black = Color(0, 0, 0); # let origin = Point(0, 0, 0); let black_r = black.0; -let (_, origin_y, origin_z) = origin; +let Point(_, origin_y, origin_z) = origin; ``` One case when a tuple struct is very useful is when it has only one element. From beec630863e9453c79b2f970323639ab1fe8e853 Mon Sep 17 00:00:00 2001 From: Alex Burka Date: Thu, 28 Apr 2016 10:32:08 -0400 Subject: [PATCH 3/6] "equal" -> "same type" --- src/doc/book/structs.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/doc/book/structs.md b/src/doc/book/structs.md index 44a6d282c00..34f50e905dd 100644 --- a/src/doc/book/structs.md +++ b/src/doc/book/structs.md @@ -164,8 +164,8 @@ 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. +Here, `black` and `origin` are not the same type, even though they contain the +same values. The members of a tuple struct may be accessed by dot notation or destructuring `let`, just like regular tuples: From e1e4fbd2a235e9ce31bd614dff667a81b8f8c360 Mon Sep 17 00:00:00 2001 From: Alex Burka Date: Thu, 28 Apr 2016 10:47:19 -0400 Subject: [PATCH 4/6] s/than/instead of/ --- src/doc/book/structs.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/doc/book/structs.md b/src/doc/book/structs.md index 34f50e905dd..eace99670b1 100644 --- a/src/doc/book/structs.md +++ b/src/doc/book/structs.md @@ -203,8 +203,8 @@ We could have used dot notation to do the same thing: let integer_length = length.0; ``` -It's always possible to use a `struct` than a tuple struct, and can be clearer. -We would write `Color` and `Point` like this instead: +It's always possible to use a `struct` instead of a tuple struct, and can be +clearer. We could write `Color` and `Point` like this instead: ```rust struct Color { From 56f24d7c193da3b972994e24b86e1fd63e1e8c9e Mon Sep 17 00:00:00 2001 From: Alex Burka Date: Thu, 28 Apr 2016 11:47:03 -0400 Subject: [PATCH 5/6] add link to match section --- src/doc/book/structs.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/src/doc/book/structs.md b/src/doc/book/structs.md index eace99670b1..1fb74e33a62 100644 --- a/src/doc/book/structs.md +++ b/src/doc/book/structs.md @@ -179,6 +179,9 @@ let black_r = black.0; let Point(_, origin_y, origin_z) = origin; ``` +Patterns like `Point(_, origin_y, origin_z)` are also used in +[match expressions][match]. + 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 @@ -224,6 +227,8 @@ 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. +[match]: match.html + # Unit-like structs You can define a `struct` with no members at all: From 74e96299a22ef1629d7ea8268815fc2b82c7e194 Mon Sep 17 00:00:00 2001 From: Alex Burka Date: Tue, 5 Jul 2016 13:46:06 -0400 Subject: [PATCH 6/6] show both forms of empty struct declaration --- src/doc/book/structs.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/doc/book/structs.md b/src/doc/book/structs.md index 1fb74e33a62..328db25b819 100644 --- a/src/doc/book/structs.md +++ b/src/doc/book/structs.md @@ -234,9 +234,12 @@ rather than positions. You can define a `struct` with no members at all: ```rust -struct Electron {} +struct Electron {} // use empty braces... +struct Proton; // ...or just a semicolon +// whether you declared the struct with braces or not, do the same when creating one let x = Electron {}; +let y = Proton; ``` Such a `struct` is called ‘unit-like’ because it resembles the empty