3 `struct`s are a way of creating more complex data types. For example, if we were
4 doing calculations involving coordinates in 2D space, we would need both an `x`
12 A `struct` lets us combine these two into a single, unified datatype:
21 let origin = Point { x: 0, y: 0 }; // origin: Point
23 println!("The origin is at ({}, {})", origin.x, origin.y);
27 There’s a lot going on here, so let’s break it down. We declare a `struct` with
28 the `struct` keyword, and then with a name. By convention, `struct`s begin with
29 a capital letter and are camel cased: `PointInSpace`, not `Point_In_Space`.
31 We can create an instance of our `struct` via `let`, as usual, but we use a `key:
32 value` style syntax to set each field. The order doesn’t need to be the same as
33 in the original declaration.
35 Finally, because fields have names, we can access the field through dot
38 The values in `struct`s are immutable by default, like other bindings in Rust.
39 Use `mut` to make them mutable:
48 let mut point = Point { x: 0, y: 0 };
52 println!("The point is at ({}, {})", point.x, point.y);
56 This will print `The point is at (5, 0)`.
58 Rust does not support field mutability at the language level, so you cannot
59 write something like this:
68 Mutability is a property of the binding, not of the structure itself. If you’re
69 used to field-level mutability, this may seem strange at first, but it
70 significantly simplifies things. It even lets you make things mutable for a short
81 let mut point = Point { x: 0, y: 0 };
85 let point = point; // this new binding can’t change now
87 point.y = 6; // this causes an error
93 A `struct` can include `..` to indicate that you want to use a copy of some
94 other `struct` for some of the values. For example:
103 let mut point = Point3d { x: 0, y: 0, z: 0 };
104 point = Point3d { y: 1, .. point };
107 This gives `point` a new `y`, but keeps the old `x` and `z` values. It doesn’t
108 have to be the same `struct` either, you can use this syntax when making new
109 ones, and it will copy the values you don’t specify:
117 let origin = Point3d { x: 0, y: 0, z: 0 };
118 let point = Point3d { z: 1, x: 2, .. origin };
123 Rust has another data type that’s like a hybrid between a [tuple][tuple] and a
124 `struct`, called a ‘tuple struct’. Tuple structs have a name, but
128 struct Color(i32, i32, i32);
129 struct Point(i32, i32, i32);
132 [tuple]: primitive-types.html#tuples
134 These two will not be equal, even if they have the same values:
137 # struct Color(i32, i32, i32);
138 # struct Point(i32, i32, i32);
139 let black = Color(0, 0, 0);
140 let origin = Point(0, 0, 0);
143 It is almost always better to use a `struct` than a tuple struct. We would write
144 `Color` and `Point` like this instead:
160 Now, we have actual names, rather than positions. Good names are important,
161 and with a `struct`, we have actual names.
163 There _is_ one case when a tuple struct is very useful, though, and that’s a
164 tuple struct with only one element. We call this the ‘newtype’ pattern, because
165 it allows you to create a new type, distinct from that of its contained value
166 and expressing its own semantic meaning:
171 let length = Inches(10);
173 let Inches(integer_length) = length;
174 println!("length is {} inches", integer_length);
177 As you can see here, you can extract the inner integer type through a
178 destructuring `let`, just as with regular tuples. In this case, the
179 `let Inches(integer_length)` assigns `10` to `integer_length`.
183 You can define a `struct` with no members at all:
191 Such a `struct` is called ‘unit-like’ because it resembles the empty
192 tuple, `()`, sometimes called ‘unit’. Like a tuple struct, it defines a
195 This is rarely useful on its own (although sometimes it can serve as a
196 marker type), but in combination with other features, it can become
197 useful. For instance, a library may ask you to create a structure that
198 implements a certain [trait][trait] to handle events. If you don’t have
199 any data you need to store in the structure, you can just create a