1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
//! Something borrowed, something... moved?
//!
//!   - **Date:** October 12, 2015
//!   - **Subject:** The `struct` data type constructor, and the basics of
//!     Rust's "ownership" concept and "borrowing" and "moving".
//!   - [**Audio**][mp3]
//!
//! [mp3]: https://www.podtrac.com/pts/redirect.mp3/cdn.newrustacean.com/file/newrustacean/e002.mp3
//!
//! <audio style="width: 100%" title="Something borrowed, something... moved?" controls preload=metadata src="https://www.podtrac.com/pts/redirect.mp3/cdn.newrustacean.com/file/newrustacean/e002.mp3" />
//!
//! # Notes
//!
//! Today's episode discusses, and the associated source code demonstrates,
//! a few basic behaviors of structs... including borrowing!
//!
//! After taking a short look at one of Rust's basic approaches to creating new
//! types, we dive into a *fairly* thorough overview of how borrowing works in
//! fairly run-of-the-mill Rust code. This is a basic introduction, and as such
//! I'm not getting into things like heap-allocated memory (`Box`) or dealing
//! with `move` semantics with threads or closures. (I haven't actually figured
//! those out well enough yet to write something like this for them!)
//!
//! As usual, you'll want to have the [`src`] open to see what I'm doing with
//! the components documented below.
//!
//! [`src`]: /src/show_notes/e002.rs.html
//!
//! # Links
//!
//!   - `rustfmt` -- a tool for formatting Rust code
//!       + [repo][1]
//!       + ["rustfmt-ing Rust`][2]
//!       + [Reddit discussion][3]
//!   - RFC for incremental compilation
//!       + [Text of the RFC][4]
//!       + [GitHub pull request][5]
//!
//! [1]: https://github.com/nrc/rustfmt
//! [2]: http://www.ncameron.org/blog/rustfmt-ing-rust/
//! [3]: https://www.reddit.com/r/rust/comments/3nt2vm/rustfmting_rust_please_help_me_rustfmt_the_rust/
//! [4]: https://github.com/nikomatsakis/rfcs/blob/incremental-compilation/text/0000-incremental-compilation.md
//! [5]: https://github.com/rust-lang/rfcs/pull/1298
//!
//! # Follow/Support
//!
//!   - New Rustacean:
//!     + Twitter: [@newrustacean](https://www.twitter.com/newrustacean)
//!       + App.net: [@newrustacean](https://alpha.app.net/newrustacean)
//!       + <a href="https://www.patreon.com/newrustacean" rel="payment">Patreon</a>
//!     + Email: [[email protected]](mailto:[email protected])
//!   - Chris Krycho
//!     + Twitter: [@chriskrycho](https://www.twitter.com/chriskrycho)
//!       + App.net: [@chriskrycho](https://alpha.app.net/chriskrycho)

/// This struct is simple but useful to see how borrowing and moving work.
#[derive(Debug)]
pub struct Circle {
    /// X position of the circle's origin.
    pub x: f64,
    /// Y position of the circle's origin
    pub y: f64,
    /// Radius of the circle
    pub r: f64,
}

/// Demonstrates how borrowing works with plain old functions.
pub fn demonstrate_ownership() {
    // Just create a couple circles whose origin is at the origin.
    let immutable = Circle::origin(14.0);
    let mut mutable = Circle::origin(12.0);

    // Borrow an immutable one immutably.
    borrow(&immutable);

    // You can't borrow an immutable type mutably.
    // borrow_mut(&mut immutable);

    // You can borrow a mutable type immutably, *or* mutably.
    borrow(&mutable);
    borrow_mut(&mut mutable);
    println!(
        "Updated the radius of the mutable reference: {:}",
        mutable.r
    );

    // If I move an object, I can no longer access it afterward. If you
    // uncomment the following line, you'll see that the Circle instances are
    // no longer accessible. Note that moving and borrowing are orthogonal to
    // mutability. It's not accessible after this because it actually gets
    // dropped, i.e. de-allocated.
    move_circle(immutable);
    move_circle(mutable);
    // println!("Immutable: {:?}", immutable);
    // println!("Mutable: {:?}", mutable);
}

/// Demonstrates general borrowing of an immutable reference.
pub fn borrow(ref_to_circle: &Circle) {
    // I can access but not change the values.
    println!(
        "Immutable reference-- origin: {:},{:} | Radius: {:}",
        ref_to_circle.x, ref_to_circle.y, ref_to_circle.r
    );

    // You can uncomment this to see the compiler error if you try to *change*
    // the contents.
    // ref_to_circle.r *= 2.0;

    // Similarly, if you try to reassign the reference itself, it will fail:
    // *ref_to_circle = Circle::new()
}

/// Demonstrates general borrowing of a mutable reference.
pub fn borrow_mut(mutable_ref_to_circle: &mut Circle) {
    // I can still access these values, of course.
    println!(
        "Mutable reference-- origin: {:},{:} | Radius: {:}",
        mutable_ref_to_circle.x, mutable_ref_to_circle.y, mutable_ref_to_circle.r
    );

    // But I can also update the values.
    mutable_ref_to_circle.r *= 2.0;
}

/// Demonstrates general moving of an instance.
pub fn move_circle(moved_circle: Circle) {
    println!("Moved a circle: {:?}", moved_circle);

    // Note that this is an immutable type: this won't compile.
    // moved_circle.r *= 2.0;

    // We own the object, but it's still immutable, so we can't reassign the
    // name as we like.
    // moved_circle = Circle::new(4.5, 9.0, 18.0);
}

/// Implement some methods on the `Circle`.
///
/// This lets use demonstrate both how methods work in general and specifically
/// how they interact with the idea of ownership.
impl Circle {
    /// Creates a `Circle` instance centered on the "origin" (x = 0, y = 0).
    fn origin(r: f64) -> Circle {
        Circle {
            x: 0.0,
            y: 0.0,
            r: r,
        }
    }

    /// Creates a `Circle` instance centered on specified x, y values.
    pub fn new(x: f64, y: f64, r: f64) -> Circle {
        Circle { x: x, y: y, r: r }
    }

    /// Returns the value of `Circle.x`, borrowing an immutable reference to
    /// the circle to do it.
    ///
    /// Because the reference is immutable, if you tried to do this---
    ///
    /// ```ignore
    /// self.x = 10;
    /// ```
    ///
    /// ---the compiler would not allow it.
    pub fn x_by_ref(&self) -> f64 {
        println!("Taking a reference.");
        // The reference is immutable.
        self.x
    }

    /// Returns the value of `Circle.x`, borrowing a mutable reference to the
    /// circle and changing the value (demonstrating a situation in which you
    /// would want to use a mutable rather than immutable reference).
    pub fn x_by_mut_ref(&mut self) -> f64 {
        println!("Taking a mutable reference.");
        self.x = self.x + 1.0;
        self.x
    }

    /// Returns the value of `Circle.x`, taking ownership of the circle. As a
    /// result of the change in ownership, the circle goes out of scope after
    /// the method returns, so the circle instance will be inaccessible after
    /// that.
    ///
    /// Note that the item is taken as immutable, so attempting to change the
    /// internals will still fail. **Ownership is orthogonal to immutability.**
    pub fn by_take(self) -> f64 {
        println!("Taking ownership, not just borrowing a reference. INTENSE.");
        self.x
    }

    /// Returns the value of `Circle.x`, taking ownership of a mutable circle.
    pub fn by_take_mut(mut self) -> f64 {
        println!("Taking ownership *and* mutating all the things.");
        self.x += 14.0;
        self.x
    }
}

/// Demonstrates how the same concepts apply when dealing with methods.
pub fn demonstrate_method_ownership() {
    // There are several ways to construct struct types. The first is a plain
    // struct constructor.
    let basic = Circle {
        x: 1.0,
        y: 2.0,
        r: 5.0,
    };
    // The next is using a constructor.
    let mut mutable = Circle::new(14.0, 12.0, 10.0);
    // Constructors can have default behavior, like this one.
    let immutable = Circle::origin(12.0);
    println!("{:?}", basic);
    println!("{:?}", immutable);
    println!("{:?}", mutable);

    // Now we can see how different method calls work. When we borrow a
    // reference, there is no consequence: during the life of the method, the
    // immutable object is "borrowed" by the `x_by_ref` method. Ownership returns
    // to the `main` function when it returns.
    let by_ref_x = immutable.x_by_ref();
    println!("By reference: {}", by_ref_x);

    // The same is true of a method that borrows a mutable reference. Note,
    // however, that since the reference is mutable, it can change the contents
    // of the struct.
    print!("Original x_by_mut_ref x value: {}... ", mutable.x);
    let by_mut_ref_x = mutable.x_by_mut_ref();
    println!("After calling `x_by_mut_ref`: {}", by_mut_ref_x);

    // Note that both of these struct instances are still available for `main`
    // to use once they return from the method call:
    println!(
        "immutable's y: {} | mutable's r: {}",
        immutable.y, mutable.r
    );

    // A method that takes ownership can still return a value. However, it has
    // a very different behavior in terms of the struct instance, in a way that
    // seems surprising compared to languages without the concept of "borrowing"
    // vs. "taking" (C, Java, Python, etc.).
    //
    // Run a method that takes ownership rather than just borrowing a reference.
    // The value returned is as expected. However, the item has been *moved*,
    // not just borrowed. That is, `main` no longer owns it---`by_take` took
    // over the ownership. Once `by_take` ended, `immutable` actually gets
    // deconstructed ("dropped") because it went out of scope. As a result, the
    // following line won't compile (you can uncomment it to see for yourself):
    let by_take_x = immutable.by_take();
    println!("By take: {}", by_take_x);
    // println!("Does the circle still exist? {:?}", immutable);

    // Likewise, if we use the mutable circle with the method which takes
    // ownership and mutates it, we can get the value back as before, but the
    // circle will have been dropped when the `by_take_mut` call ended.
    let by_mut_take_x = mutable.by_take_mut();
    println!("By mutable take: {}", by_mut_take_x);
    // println!("Does the mutable circle still exist? {:?}", mutable);
}