The latest articles on Forem by Brian Maher (@brimworks). https://forem.com/brimworks https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F1202081%2F2cea7ed4-3544-40a4-9eec-88ab27033407.jpg https://forem.com/brimworks en Brian Maher Sat, 11 Nov 2023 21:14:40 +0000 https://forem.com/brimworks/rust-borrow-checker-explained-part-5-escape-hatches-4hk2 https://forem.com/brimworks/rust-borrow-checker-explained-part-5-escape-hatches-4hk2 <h2> Intro </h2> <p>In part 4 we looked at how to declare structures with borrowed fields, and some of the limitations this introduces. In this final part of the Rust borrow checker series we will investigate some tools that allow us to "break the rules".</p> <p>Specifically, we will see:</p> <ul> <li>How we can use "copy on write" to <strong>possibly</strong> avoid copying.</li> <li>How we can share a reference by counting each use and only releasing the value when the count drops to zero.</li> <li>How inner fields can be made mutable from an immutable context.</li> </ul> <h2> Copy On Write </h2> <p>Rust has a <a href="https://doc.rust-lang.org/std/borrow/enum.Cow.html"><code>Cow</code></a> type which is a simple enumeration over two possible states:</p> <ul> <li><code>Borrowed</code></li> <li><code>Owned</code></li> </ul> <p>This is useful if you want to be able to take an immutable reference with the possibility of changing it into an owned value. This technique is known as "copy on write", and thus the name <code>Cow</code>. Here is an example of using it to take an array of numbers and make sure that they are even:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight rust"><code><span class="k">use</span> <span class="nn">std</span><span class="p">::</span><span class="nn">borrow</span><span class="p">::</span><span class="n">Cow</span><span class="p">;</span> <span class="k">fn</span> <span class="nf">main</span><span class="p">()</span> <span class="p">{</span> <span class="k">let</span> <span class="n">input</span><span class="p">:</span> <span class="o">&amp;</span><span class="p">[</span><span class="nb">isize</span><span class="p">]</span> <span class="o">=</span> <span class="o">&amp;</span><span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">];</span> <span class="k">let</span> <span class="k">mut</span> <span class="n">output</span> <span class="o">=</span> <span class="nn">Cow</span><span class="p">::</span><span class="nf">Borrowed</span><span class="p">(</span><span class="n">input</span><span class="p">);</span> <span class="nf">make_even</span><span class="p">(</span><span class="o">&amp;</span><span class="k">mut</span> <span class="n">output</span><span class="p">);</span> <span class="nd">println!</span><span class="p">(</span><span class="s">"input={input:?} output={output:?}"</span><span class="p">);</span> <span class="p">}</span> <span class="k">fn</span> <span class="nf">make_even</span><span class="p">(</span><span class="n">input</span><span class="p">:</span> <span class="o">&amp;</span><span class="k">mut</span> <span class="n">Cow</span><span class="o">&lt;</span><span class="nv">'_</span><span class="p">,</span> <span class="p">[</span><span class="nb">isize</span><span class="p">]</span><span class="o">&gt;</span><span class="p">)</span> <span class="p">{</span> <span class="k">for</span> <span class="n">idx</span> <span class="k">in</span> <span class="mi">0</span><span class="o">..</span><span class="n">input</span><span class="nf">.len</span><span class="p">()</span> <span class="p">{</span> <span class="k">if</span> <span class="n">input</span><span class="p">[</span><span class="n">idx</span><span class="p">]</span> <span class="o">%</span> <span class="mi">2</span> <span class="o">!=</span> <span class="mi">0</span> <span class="p">{</span> <span class="n">input</span><span class="nf">.to_mut</span><span class="p">()[</span><span class="n">idx</span><span class="p">]</span> <span class="o">=</span> <span class="n">input</span><span class="p">[</span><span class="n">idx</span><span class="p">]</span> <span class="o">+</span> <span class="mi">1</span><span class="p">;</span> <span class="p">}</span> <span class="p">}</span> <span class="p">}</span> </code></pre> </div> <p><a href="https://play.rust-lang.org/?version=stable&amp;mode=debug&amp;edition=2021&amp;gist=c81996a38b2edd9d7d6e5932479fbda8">Try it!</a></p> <p>Note that if the input was all even, then no copy would take place. Only when the <code>to_mut()</code> call is made does it call <code>.clone()</code> on the underlying borrowed value.</p> <p>Obviously, this only works on types that implement <code>Clone</code>.</p> <h2> Breaking Single Ownership: Reference Counting </h2> <p>The single ownership rule can be broken by using reference counting, aka "smart pointers". Rust provides two variants: <a href="https://doc.rust-lang.org/std/sync/struct.Arc.html"><code>Arc</code></a> and <a href="https://doc.rust-lang.org/std/rc/struct.Rc.html"><code>Rc</code></a>. <code>Arc</code> is short for "atomic reference count" and <code>Rc</code> is just "reference count". If there is a possibility of using multiple threads, then stick with <code>Arc</code>.</p> <p>The only practical way of implementing a linked list is to use reference counts:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight rust"><code><span class="k">use</span> <span class="nn">std</span><span class="p">::</span><span class="nn">rc</span><span class="p">::</span><span class="nb">Rc</span><span class="p">;</span> <span class="nd">#[derive(Debug)]</span> <span class="k">struct</span> <span class="n">Node</span> <span class="p">{</span> <span class="n">val</span><span class="p">:</span> <span class="nb">i32</span><span class="p">,</span> <span class="n">next</span><span class="p">:</span> <span class="nb">Option</span><span class="o">&lt;</span><span class="nb">Rc</span><span class="o">&lt;</span><span class="n">Node</span><span class="o">&gt;&gt;</span> <span class="p">}</span> <span class="k">fn</span> <span class="nf">create_list</span><span class="p">()</span> <span class="k">-&gt;</span> <span class="n">Node</span> <span class="p">{</span> <span class="k">let</span> <span class="n">third</span> <span class="o">=</span> <span class="n">Node</span> <span class="p">{</span> <span class="n">val</span><span class="p">:</span> <span class="mi">3</span><span class="p">,</span> <span class="n">next</span><span class="p">:</span> <span class="nb">None</span><span class="p">,</span> <span class="p">};</span> <span class="k">let</span> <span class="n">second</span> <span class="o">=</span> <span class="n">Node</span> <span class="p">{</span> <span class="n">val</span><span class="p">:</span> <span class="mi">2</span><span class="p">,</span> <span class="n">next</span><span class="p">:</span> <span class="nf">Some</span><span class="p">(</span><span class="nn">Rc</span><span class="p">::</span><span class="nf">new</span><span class="p">(</span><span class="n">third</span><span class="p">)),</span> <span class="p">};</span> <span class="k">let</span> <span class="n">first</span> <span class="o">=</span> <span class="n">Node</span> <span class="p">{</span> <span class="n">val</span><span class="p">:</span> <span class="mi">1</span><span class="p">,</span> <span class="n">next</span><span class="p">:</span> <span class="nf">Some</span><span class="p">(</span><span class="nn">Rc</span><span class="p">::</span><span class="nf">new</span><span class="p">(</span><span class="n">second</span><span class="p">)),</span> <span class="p">};</span> <span class="k">return</span> <span class="n">first</span><span class="p">;</span> <span class="p">}</span> <span class="k">fn</span> <span class="nf">main</span><span class="p">()</span> <span class="p">{</span> <span class="k">let</span> <span class="n">list</span> <span class="o">=</span> <span class="nf">create_list</span><span class="p">();</span> <span class="nd">println!</span><span class="p">(</span><span class="s">"LL={list:?}"</span><span class="p">);</span> <span class="p">}</span> </code></pre> </div> <p>Note that since we are no longer borrowing the next nodes, we can create the entire list in the <code>create_list()</code> function, and just return the first node in the list.</p> <p>Smart pointers, aka reference counters:</p> <ul> <li>Implements <code>Clone.clone()</code> trait so that it increments the reference count.</li> <li>Implements <a href="https://doc.rust-lang.org/std/ops/trait.Deref.html"><code>Deref.deref()</code></a> trait so you can directly call the underlying methods of the value being pointed to. This also allows you to use the <code>*</code> syntax to get an immutable view of the value.</li> <li>Incur overhead for the extra space required to store the counter and the cost of incrementing and decrementing the counter.</li> <li>Leak memory if a cycle is formed, but since every smart pointer is immutable, and since <code>Rc::new()</code> takes ownership of the value, it is impossible to define a structure with a cycle... unless you read on.</li> </ul> <h2> Breaking Immutability: RefCell &amp; Mutex </h2> <p>If we want inner mutability, Rust provides two variants: <a href="https://doc.rust-lang.org/std/cell/struct.RefCell.html"><code>RefCell</code></a> and <a href="https://doc.rust-lang.org/std/sync/struct.Mutex.html"><code>Mutex</code></a>. If there is the possibility of multi-threaded programming, then stick with <code>Mutex</code>, otherwise <code>RefCell</code> is sufficient.</p> <p>Our linked list example above was still rather useless since there is no way to modify the list, since the value behind the <code>next</code> link is immutable. Let's fix this using <code>RefCell</code>:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight rust"><code><span class="k">use</span> <span class="nn">std</span><span class="p">::</span><span class="nn">rc</span><span class="p">::</span><span class="nb">Rc</span><span class="p">;</span> <span class="k">use</span> <span class="nn">std</span><span class="p">::</span><span class="nn">cell</span><span class="p">::</span><span class="n">RefCell</span><span class="p">;</span> <span class="nd">#[derive(Debug)]</span> <span class="k">struct</span> <span class="n">Node</span> <span class="p">{</span> <span class="n">val</span><span class="p">:</span> <span class="nb">i32</span><span class="p">,</span> <span class="n">next</span><span class="p">:</span> <span class="nb">Option</span><span class="o">&lt;</span><span class="nb">Rc</span><span class="o">&lt;</span><span class="n">RefCell</span><span class="o">&lt;</span><span class="n">Node</span><span class="o">&gt;&gt;&gt;</span> <span class="p">}</span> <span class="k">fn</span> <span class="nf">create_list</span><span class="p">()</span> <span class="k">-&gt;</span> <span class="n">Node</span> <span class="p">{</span> <span class="k">let</span> <span class="n">third</span> <span class="o">=</span> <span class="n">Node</span> <span class="p">{</span> <span class="n">val</span><span class="p">:</span> <span class="mi">3</span><span class="p">,</span> <span class="n">next</span><span class="p">:</span> <span class="nb">None</span><span class="p">,</span> <span class="p">};</span> <span class="k">let</span> <span class="n">second</span> <span class="o">=</span> <span class="n">Node</span> <span class="p">{</span> <span class="n">val</span><span class="p">:</span> <span class="mi">2</span><span class="p">,</span> <span class="n">next</span><span class="p">:</span> <span class="nf">Some</span><span class="p">(</span><span class="nn">Rc</span><span class="p">::</span><span class="nf">new</span><span class="p">(</span><span class="nn">RefCell</span><span class="p">::</span><span class="nf">new</span><span class="p">(</span><span class="n">third</span><span class="p">))),</span> <span class="p">};</span> <span class="k">let</span> <span class="n">first</span> <span class="o">=</span> <span class="n">Node</span> <span class="p">{</span> <span class="n">val</span><span class="p">:</span> <span class="mi">1</span><span class="p">,</span> <span class="n">next</span><span class="p">:</span> <span class="nf">Some</span><span class="p">(</span><span class="nn">Rc</span><span class="p">::</span><span class="nf">new</span><span class="p">(</span><span class="nn">RefCell</span><span class="p">::</span><span class="nf">new</span><span class="p">(</span><span class="n">second</span><span class="p">))),</span> <span class="p">};</span> <span class="k">return</span> <span class="n">first</span><span class="p">;</span> <span class="p">}</span> <span class="k">fn</span> <span class="nf">main</span><span class="p">()</span> <span class="p">{</span> <span class="k">let</span> <span class="n">list</span> <span class="o">=</span> <span class="nf">create_list</span><span class="p">();</span> <span class="n">list</span><span class="py">.next</span><span class="nf">.as_ref</span><span class="p">()</span><span class="nf">.unwrap</span><span class="p">()</span><span class="nf">.borrow_mut</span><span class="p">()</span><span class="py">.next</span> <span class="o">=</span> <span class="nb">None</span><span class="p">;</span> <span class="nd">println!</span><span class="p">(</span><span class="s">"LL={list:?}"</span><span class="p">);</span> <span class="p">}</span> </code></pre> </div> <p><a href="https://play.rust-lang.org/?version=stable&amp;mode=debug&amp;edition=2021&amp;gist=7c2beb00d963077a322625d2c2c6cf61">Try it!</a></p> <p>Here is a break down of the second line of the main:</p> <ul> <li> <code>list.next</code> obtains the <code>Option</code>.</li> <li> <code>as_ref()</code> borrows this so we now have <code>&amp;Option</code>. Without this, the <code>unwrap()</code> call would take the ownership and we wouldn't be able to reference <code>list</code> in the print below.</li> <li> <code>unwrap()</code> returns the <code>&amp;Rc</code> stored in the option.</li> <li> <code>borrow_mut()</code> returns the <code>&amp;mut Node</code> stored in the <code>Rc</code>.</li> <li>We assign the value <code>None</code> which effectively removes the last element.</li> </ul> <p><strong>NOTE:</strong> The <code>RefCell::borow_mut()</code> still tries to enforce the mutual exclusion rule at runtime, and if it detects breaking that rule, then the program will crash.</p> <p>This means, you need to be careful about what how long the scope of the <code>borrow_mut()</code> result exists.</p> <p>The <code>Mutex::lock()</code> is the multi-threaded safe equivalent method.</p> <h2> A Word On Linked Lists </h2> <ul> <li>Use the builtin <a href="https://doc.rust-lang.org/std/vec/struct.Vec.html"><code>Vec</code></a> which is much more performant than any linked list implementation.</li> <li>If you do need single linked lists, a simple <code>Box&lt;T&gt;</code> is a better way to implement linked lists.</li> <li>If you need double linked lists, you will need either <code>Rc&lt;RefCell&lt;T&gt;&gt;</code> or <code>Arc&lt;Mutex&lt;T&gt;&gt;</code>.</li> </ul> <h2> Conclusion </h2> <p>Sometimes the borrow checker limits what is possible in which case you can use several different escape hatches such as smart pointers or inner mutability, but these escape hatches do come with performance and/or safety losses. Therefore it is best if you can adhere to the borrow checker rules.</p> <p>I hope this article series was helpful on your journey to Rust!</p> Brian Maher Sat, 11 Nov 2023 21:13:47 +0000 https://forem.com/brimworks/rust-borrow-checker-explained-part-4-structure-lifetimes-2od0 https://forem.com/brimworks/rust-borrow-checker-explained-part-4-structure-lifetimes-2od0 <h2> Intro </h2> <p>In part 3 we talked about how to tell the compiler what the lifetime of a function's result(s) are in relationship to the parameters of the function. In this article we will see how to add lifetimes to structures.</p> <h2> Structural Lifetimes </h2> <p>Sometimes it is desirable to have structures which contain pointers, for example, our <code>Num</code> tuple that we talked about in <strong>Part 1</strong> could be borrowing the string instead of owning it:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight rust"><code><span class="k">struct</span> <span class="nf">Num</span><span class="p">(</span><span class="nb">i32</span><span class="p">,</span> <span class="o">&amp;</span><span class="nb">String</span><span class="p">);</span> </code></pre> </div> <p>...but the compiler will complain since we need to give the borrowed string a lifetime:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight plaintext"><code>error[E0106]: missing lifetime specifier --&gt; src/main.rs:1:17 </code></pre> </div> <p>To fix this, we declare lifetime(s) using template arguments, and then annotate the <code>&amp;</code> borrows with the lifetime name. This is very similar to what we did for functions:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight rust"><code><span class="k">struct</span> <span class="nb">Num</span><span class="o">&lt;</span><span class="nv">'a</span><span class="o">&gt;</span><span class="p">(</span><span class="nb">i32</span><span class="p">,</span> <span class="o">&amp;</span><span class="nv">'a</span> <span class="nb">String</span><span class="p">);</span> </code></pre> </div> <p>Let's try it out using code similar to what we did for <strong>Part 1</strong> when we implemented <code>Copy</code> marker trait:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight rust"><code><span class="nd">#[derive(Debug,</span> <span class="nd">Copy,</span> <span class="nd">Clone)]</span> <span class="k">struct</span> <span class="nb">Num</span><span class="o">&lt;</span><span class="nv">'a</span><span class="o">&gt;</span><span class="p">(</span><span class="nb">i32</span><span class="p">,</span> <span class="o">&amp;</span><span class="nv">'a</span> <span class="nb">String</span><span class="p">);</span> <span class="k">fn</span> <span class="nf">main</span><span class="p">()</span> <span class="p">{</span> <span class="k">let</span> <span class="n">two_str</span> <span class="o">=</span> <span class="o">&amp;</span><span class="nn">String</span><span class="p">::</span><span class="nf">from</span><span class="p">(</span><span class="s">"two"</span><span class="p">);</span> <span class="k">let</span> <span class="n">num</span> <span class="o">=</span> <span class="nf">Num</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="n">two_str</span><span class="p">);</span> <span class="k">let</span> <span class="n">even</span> <span class="o">=</span> <span class="nf">is_even</span><span class="p">(</span><span class="n">num</span><span class="p">);</span> <span class="nd">print!</span><span class="p">(</span><span class="s">"is_even={even:?} num={num:?}"</span><span class="p">)</span> <span class="p">}</span> <span class="k">fn</span> <span class="nf">is_even</span><span class="p">(</span><span class="n">num</span><span class="p">:</span> <span class="nb">Num</span><span class="p">)</span> <span class="k">-&gt;</span> <span class="nb">bool</span> <span class="p">{</span> <span class="n">num</span><span class="na">.0</span> <span class="o">%</span> <span class="mi">2</span> <span class="o">==</span> <span class="mi">0</span> <span class="p">}</span> </code></pre> </div> <p><a href="https://play.rust-lang.org/?version=stable&amp;mode=debug&amp;edition=2021&amp;gist=9254c566bff3259fbae2d60be410ada7">Try it!</a></p> <p>You will notice that since we are borrowing the <code>String</code>, we can actually implement the <code>Copy</code> trait!</p> <p>With this lifetime information, the borrow checker can always ensure the lifetime of the borrowed str out lives the <code>Num</code> struct. Let's try it out:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight rust"><code><span class="nd">#[derive(Debug,</span> <span class="nd">Copy,</span> <span class="nd">Clone)]</span> <span class="k">struct</span> <span class="nb">Num</span><span class="o">&lt;</span><span class="nv">'a</span><span class="o">&gt;</span><span class="p">(</span><span class="nb">i32</span><span class="p">,</span> <span class="o">&amp;</span><span class="nv">'a</span> <span class="nb">String</span><span class="p">);</span> <span class="k">fn</span> <span class="nf">main</span><span class="p">()</span> <span class="p">{</span> <span class="k">let</span> <span class="n">num</span><span class="p">;</span> <span class="p">{</span> <span class="k">let</span> <span class="n">two_str</span> <span class="o">=</span> <span class="o">&amp;</span><span class="nn">String</span><span class="p">::</span><span class="nf">from</span><span class="p">(</span><span class="s">"two"</span><span class="p">);</span> <span class="n">num</span> <span class="o">=</span> <span class="nf">Num</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="n">two_str</span><span class="p">);</span> <span class="p">}</span> <span class="k">let</span> <span class="n">even</span> <span class="o">=</span> <span class="nf">is_even</span><span class="p">(</span><span class="n">num</span><span class="p">);</span> <span class="nd">print!</span><span class="p">(</span><span class="s">"is_even={even:?} num={num:?}"</span><span class="p">)</span> <span class="p">}</span> <span class="k">fn</span> <span class="nf">is_even</span><span class="p">(</span><span class="n">num</span><span class="p">:</span> <span class="nb">Num</span><span class="p">)</span> <span class="k">-&gt;</span> <span class="nb">bool</span> <span class="p">{</span> <span class="n">num</span><span class="na">.0</span> <span class="o">%</span> <span class="mi">2</span> <span class="o">==</span> <span class="mi">0</span> <span class="p">}</span> </code></pre> </div> <p><a href="https://play.rust-lang.org/?version=stable&amp;mode=debug&amp;edition=2021&amp;gist=84653d92fb8860737528442aa2fd3cba">Try it!</a><br> </p> <div class="highlight js-code-highlight"> <pre class="highlight plaintext"><code>error[E0716]: temporary value dropped while borrowed --&gt; src/main.rs:7:24 </code></pre> </div> <p>The borrow checker observes that <code>two_str</code> lifetime is shorter than the <code>num</code> lifetime. Hurray for the borrow checker!</p> <h2> Mutable Structural Borrows </h2> <p>Let's see if we can modify <code>is_even()</code> so that it has a side-effect of adding " is even" or " is odd" to the end of the <code>Num.1</code> String field:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight rust"><code><span class="nd">#[derive(Debug)]</span> <span class="k">struct</span> <span class="nb">Num</span><span class="o">&lt;</span><span class="nv">'a</span><span class="o">&gt;</span><span class="p">(</span><span class="nb">i32</span><span class="p">,</span> <span class="o">&amp;</span><span class="nv">'a</span> <span class="k">mut</span> <span class="nb">String</span><span class="p">);</span> <span class="k">fn</span> <span class="nf">main</span><span class="p">()</span> <span class="p">{</span> <span class="k">let</span> <span class="n">two_str</span> <span class="o">=</span> <span class="o">&amp;</span><span class="k">mut</span> <span class="nn">String</span><span class="p">::</span><span class="nf">from</span><span class="p">(</span><span class="s">"two"</span><span class="p">);</span> <span class="k">let</span> <span class="k">mut</span> <span class="n">num</span> <span class="o">=</span> <span class="nf">Num</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="n">two_str</span><span class="p">);</span> <span class="k">let</span> <span class="n">even</span> <span class="o">=</span> <span class="nf">is_even</span><span class="p">(</span><span class="o">&amp;</span><span class="k">mut</span> <span class="n">num</span><span class="p">);</span> <span class="nd">print!</span><span class="p">(</span><span class="s">"is_even={even:?} num={num:?}"</span><span class="p">)</span> <span class="p">}</span> <span class="k">fn</span> <span class="nf">is_even</span><span class="p">(</span><span class="n">num</span><span class="p">:</span> <span class="o">&amp;</span><span class="k">mut</span> <span class="nb">Num</span><span class="p">)</span> <span class="k">-&gt;</span> <span class="nb">bool</span> <span class="p">{</span> <span class="k">if</span> <span class="n">num</span><span class="na">.0</span> <span class="o">%</span> <span class="mi">2</span> <span class="o">==</span> <span class="mi">0</span> <span class="p">{</span> <span class="o">*</span><span class="n">num</span><span class="na">.1</span> <span class="o">=</span> <span class="nd">format!</span><span class="p">(</span><span class="s">"{} is even"</span><span class="p">,</span> <span class="n">num</span><span class="na">.1</span><span class="p">);</span> <span class="k">return</span> <span class="k">true</span><span class="p">;</span> <span class="p">}</span> <span class="k">else</span> <span class="p">{</span> <span class="o">*</span><span class="n">num</span><span class="na">.1</span> <span class="o">=</span> <span class="nd">format!</span><span class="p">(</span><span class="s">"{} is odd"</span><span class="p">,</span> <span class="n">num</span><span class="na">.1</span><span class="p">);</span> <span class="k">return</span> <span class="k">false</span><span class="p">;</span> <span class="p">}</span> <span class="p">}</span> </code></pre> </div> <p><a href="https://play.rust-lang.org/?version=stable&amp;mode=debug&amp;edition=2021&amp;gist=486d6bb1677ace80756c053df7f3ef65">Try it!</a></p> <p>Some important points:</p> <ul> <li> <code>mut</code> sprinkled all around. In particular: <ul> <li> <code>Num</code> declaration transitioned from <code>&amp;'a</code> to <code>&amp;'a mut</code>.</li> <li> <code>Num</code> can <strong>not</strong> implement the <code>Copy</code> or <code>Clone</code> traits automatically, since it has a mutable borrow.</li> <li> <code>two_str</code> is now a <code>&amp;mut</code>.</li> <li>Because <code>Num</code> does not implement <code>Copy</code>, we need to borrow it in the call to <code>is_even()</code>.</li> </ul> </li> <li>We use the <code>*</code> to assign to the mutable reference.</li> </ul> <p>If we modify the above so that <code>two_str</code> is printed at the end of main, we would get an error, since there can only be a single mutable reference... and the <code>Num</code> structure "took" that single mutable reference.</p> <h2> Linked Lists </h2> <p>With this new found information, it might be tempting to use this new found information in order to define a single linked list of numbers like this:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight rust"><code><span class="k">struct</span> <span class="n">Node</span><span class="o">&lt;</span><span class="nv">'a</span><span class="o">&gt;</span> <span class="p">{</span> <span class="n">val</span><span class="p">:</span> <span class="nb">i32</span><span class="p">,</span> <span class="n">next</span><span class="p">:</span> <span class="nb">Option</span><span class="o">&lt;&amp;</span><span class="nv">'a</span> <span class="k">mut</span> <span class="n">Node</span><span class="o">&lt;</span><span class="nv">'a</span><span class="o">&gt;&gt;</span> <span class="p">}</span> </code></pre> </div> <p>Notice that we declare a lifetime, and we tell the borrow checker that the next node in the linked list is a borrowed node with this lifetime... recursively (since the next <code>Node</code> uses the same lifetime).</p> <p>...and we can write this code that creates a linked list of 3 elements, then truncates it to 2:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight rust"><code><span class="nd">#[derive(Debug)]</span> <span class="k">struct</span> <span class="n">Node</span><span class="o">&lt;</span><span class="nv">'a</span><span class="o">&gt;</span> <span class="p">{</span> <span class="n">val</span><span class="p">:</span> <span class="nb">i32</span><span class="p">,</span> <span class="n">next</span><span class="p">:</span> <span class="nb">Option</span><span class="o">&lt;&amp;</span><span class="nv">'a</span> <span class="k">mut</span> <span class="n">Node</span><span class="o">&lt;</span><span class="nv">'a</span><span class="o">&gt;&gt;</span> <span class="p">}</span> <span class="k">fn</span> <span class="nf">main</span><span class="p">()</span> <span class="p">{</span> <span class="k">let</span> <span class="k">mut</span> <span class="n">third</span> <span class="o">=</span> <span class="n">Node</span> <span class="p">{</span> <span class="n">val</span><span class="p">:</span> <span class="mi">3</span><span class="p">,</span> <span class="n">next</span><span class="p">:</span> <span class="nb">None</span><span class="p">,</span> <span class="p">};</span> <span class="k">let</span> <span class="k">mut</span> <span class="n">second</span> <span class="o">=</span> <span class="n">Node</span> <span class="p">{</span> <span class="n">val</span><span class="p">:</span> <span class="mi">2</span><span class="p">,</span> <span class="n">next</span><span class="p">:</span> <span class="nf">Some</span><span class="p">(</span><span class="o">&amp;</span><span class="k">mut</span> <span class="n">third</span><span class="p">),</span> <span class="p">};</span> <span class="k">let</span> <span class="k">mut</span> <span class="n">first</span> <span class="o">=</span> <span class="n">Node</span> <span class="p">{</span> <span class="n">val</span><span class="p">:</span> <span class="mi">1</span><span class="p">,</span> <span class="n">next</span><span class="p">:</span> <span class="nf">Some</span><span class="p">(</span><span class="o">&amp;</span><span class="k">mut</span> <span class="n">second</span><span class="p">),</span> <span class="p">};</span> <span class="nd">println!</span><span class="p">(</span><span class="s">"3 element LL={first:?}"</span><span class="p">);</span> <span class="p">(</span><span class="o">&amp;</span><span class="k">mut</span> <span class="n">first</span><span class="p">)</span><span class="py">.next</span><span class="nf">.as_mut</span><span class="p">()</span><span class="nf">.unwrap</span><span class="p">()</span><span class="py">.next</span> <span class="o">=</span> <span class="nb">None</span><span class="p">;</span> <span class="nd">println!</span><span class="p">(</span><span class="s">"2 element LL={first:?}"</span><span class="p">);</span> <span class="p">}</span> </code></pre> </div> <p><a href="https://play.rust-lang.org/?version=stable&amp;mode=debug&amp;edition=2021&amp;gist=592813347d31d9460e4af2d41a7920bd">Try it!</a></p> <p>However, this structure will be of limited practical use, since the lifetime of every element in the list must be the same or longer than the lifetime of the actual "owned" list elements. Additionally, the mutual exclusion property of mutable references means we can't even change the last println so it prints <code>second</code> since the mutable reference to it was transferred to <code>first</code>'s <code>next</code> field.</p> <h2> Recap Of Structure Lifetimes </h2> <ul> <li>We can use the <code>&lt;'a&gt;</code> syntax to declare a "template" lifetime to any structure.</li> <li>This declaration of lifetime(s) can be used in all the borrowed fields, and in other structures that require a lifetime parameter.</li> <li>Mutably borrowing inside of structures is impractical due to the mutual exclusion rules of mutable references. It also disables the ability to implement <code>Copy</code> and <code>Clone</code>.</li> <li>Immutable borrowing inside of structures is reasonable, but approach with caution, since you need these borrowed field lifetimes to be the same as (or longer than) the lifetime of an instance of that structure.</li> </ul> <p>However, before you start <code>.clone()</code>ing everything into your structures, read <a href="https://dev.to/brimworks/rust-borrow-checker-explained-part-5-escape-hatches-4hk2">Part 5</a> which discusses a few "escape hatches" that allow us to break all these borrow check rules.</p> Brian Maher Sat, 11 Nov 2023 21:13:38 +0000 https://forem.com/brimworks/rust-borrow-checker-explained-part-3-function-result-lifetimes-20j6 https://forem.com/brimworks/rust-borrow-checker-explained-part-3-function-result-lifetimes-20j6 <h2> Intro </h2> <p>In Part 2, we went over the basics of borrowing and how it looks out for you. In this article we will go over the rules of lifetimes which are used by the borrow checker to ensure the <em>owned</em> lifetime always out lasts the <em>borrowed</em> lifetime.</p> <h2> Lifetimes </h2> <p>Lifetimes are just a fancy name for <a href="https://en.wikipedia.org/wiki/Scope_(computer_science)">"scope"</a>. If you recall, in <a href="https://dev.to/brimworks/rust-borrow-checker-explained-2ohj">Part 1</a>, we went over how Rust uses the stack to manage memory. Any argument functions and local variables are automatically "popped" off the stack when the function returns. A Rust lifetime simply describes how long a variable is in scope.</p> <h2> Functions With Explicit Lifetime </h2> <p>Let's try to define a function to get the longest string:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight rust"><code><span class="k">fn</span> <span class="nf">main</span><span class="p">()</span> <span class="p">{</span> <span class="k">let</span> <span class="n">str1</span> <span class="o">=</span> <span class="s">"tiger"</span><span class="p">;</span> <span class="k">let</span> <span class="n">str2</span> <span class="o">=</span> <span class="s">"three blind mice"</span><span class="p">;</span> <span class="k">let</span> <span class="n">longest</span> <span class="o">=</span> <span class="nf">longest_str</span><span class="p">(</span><span class="n">str1</span><span class="p">,</span> <span class="n">str2</span><span class="p">);</span> <span class="nd">print!</span><span class="p">(</span><span class="s">"longest={longest}"</span><span class="p">);</span> <span class="p">}</span> <span class="k">fn</span> <span class="nf">longest_str</span><span class="p">(</span><span class="n">str1</span><span class="p">:</span> <span class="o">&amp;</span><span class="nb">str</span><span class="p">,</span> <span class="n">str2</span><span class="p">:</span> <span class="o">&amp;</span><span class="nb">str</span><span class="p">)</span> <span class="k">-&gt;</span> <span class="o">&amp;</span><span class="nb">str</span> <span class="p">{</span> <span class="k">if</span> <span class="n">str1</span><span class="nf">.len</span><span class="p">()</span> <span class="o">&lt;</span> <span class="n">str2</span><span class="nf">.len</span><span class="p">()</span> <span class="p">{</span> <span class="k">return</span> <span class="n">str2</span><span class="p">;</span> <span class="p">}</span> <span class="k">else</span> <span class="p">{</span> <span class="k">return</span> <span class="n">str1</span><span class="p">;</span> <span class="p">}</span> <span class="p">}</span> </code></pre> </div> <p><a href="https://play.rust-lang.org/?version=stable&amp;mode=debug&amp;edition=2021&amp;gist=c89bbf0603657651b14eee3d2ab8a3a5">Try it!</a></p> <p>Which produces this error:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight plaintext"><code>error[E0106]: missing lifetime specifier --&gt; src/main.rs:8:43 </code></pre> </div> <p>Rust requires lifetimes to be in the function signatures so it can avoid having to infer these lifetimes, which would be computationally expensive and small changes in implementation would alter the implied function signature in ways that are incompatible.</p> <p>If we manually inspect this code, we see that the lifetime of the resulting <code>&amp;str</code> must always be the same as (or longer) than the <code>str1</code> and <code>str2</code> parameters, since we can't know until runtime if <code>str1</code> will be returned or if <code>str2</code> will be returned.</p> <p>So, the explicit lifetime we need is:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight rust"><code><span class="k">fn</span> <span class="n">longest_str</span><span class="o">&lt;</span><span class="nv">'a</span><span class="o">&gt;</span><span class="p">(</span><span class="n">str1</span><span class="p">:</span> <span class="o">&amp;</span><span class="nv">'a</span> <span class="nb">str</span><span class="p">,</span> <span class="n">str2</span><span class="p">:</span> <span class="o">&amp;</span><span class="nv">'a</span> <span class="nb">str</span><span class="p">)</span> <span class="k">-&gt;</span> <span class="o">&amp;</span><span class="nv">'a</span> <span class="nb">str</span> </code></pre> </div> <p>Lifetime names always begin with a single tick, and they need to be declared in the same way as function template parameters. To use them, add the single tick and name after each <code>&amp;</code>, so if one of these was a mutable borrow, you would use the syntax <code>&amp;'a mut</code>.</p> <p>You might be asking, why this is needed when this example uses the exact same lifetime for every parameter. Let's look at this example:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight rust"><code><span class="k">use</span> <span class="nn">std</span><span class="p">::</span><span class="nn">collections</span><span class="p">::</span><span class="n">HashMap</span><span class="p">;</span> <span class="k">fn</span> <span class="nf">main</span><span class="p">()</span> <span class="p">{</span> <span class="k">let</span> <span class="k">mut</span> <span class="n">map</span><span class="p">:</span> <span class="n">HashMap</span><span class="o">&lt;</span><span class="nb">String</span><span class="p">,</span> <span class="nb">String</span><span class="o">&gt;</span> <span class="o">=</span> <span class="nn">HashMap</span><span class="p">::</span><span class="nf">new</span><span class="p">();</span> <span class="n">map</span><span class="nf">.insert</span><span class="p">(</span><span class="s">"one"</span><span class="nf">.into</span><span class="p">(),</span> <span class="s">"1st"</span><span class="nf">.into</span><span class="p">());</span> <span class="k">let</span> <span class="n">value</span><span class="p">;</span> <span class="p">{</span> <span class="c1">// "{" opens a new "scope":</span> <span class="k">let</span> <span class="n">one</span> <span class="o">=</span> <span class="nn">String</span><span class="p">::</span><span class="nf">from</span><span class="p">(</span><span class="s">"one"</span><span class="p">);</span> <span class="n">value</span> <span class="o">=</span> <span class="nf">lookup</span><span class="p">(</span><span class="o">&amp;</span><span class="n">map</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">one</span><span class="p">);</span> <span class="p">}</span> <span class="c1">// `one` is now out of "scope"</span> <span class="nd">print!</span><span class="p">(</span><span class="s">"value={value}"</span><span class="p">);</span> <span class="p">}</span> <span class="k">fn</span> <span class="n">lookup</span><span class="o">&lt;</span><span class="nv">'a</span><span class="o">&gt;</span><span class="p">(</span><span class="n">map</span><span class="p">:</span> <span class="o">&amp;</span><span class="nv">'a</span> <span class="n">HashMap</span><span class="o">&lt;</span><span class="nb">String</span><span class="p">,</span> <span class="nb">String</span><span class="o">&gt;</span><span class="p">,</span> <span class="n">key</span><span class="p">:</span> <span class="o">&amp;</span><span class="nv">'a</span> <span class="nb">String</span><span class="p">)</span> <span class="k">-&gt;</span> <span class="o">&amp;</span><span class="nv">'a</span> <span class="nb">str</span> <span class="p">{</span> <span class="k">return</span> <span class="n">map</span><span class="nf">.get</span><span class="p">(</span><span class="n">key</span><span class="p">)</span><span class="nf">.map</span><span class="p">(|</span><span class="n">v</span><span class="p">|</span> <span class="n">v</span><span class="nf">.as_str</span><span class="p">())</span><span class="nf">.unwrap_or</span><span class="p">(</span><span class="s">"not found"</span><span class="p">);</span> <span class="p">}</span> </code></pre> </div> <p><a href="https://play.rust-lang.org/?version=stable&amp;mode=debug&amp;edition=2021&amp;gist=cfe8bb31f6d4d04137d98f68aa52380e">Try it!</a></p> <p>...which when ran produces this error:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight plaintext"><code>error[E0597]: `one` does not live long enough --&gt; src/main.rs:9:30 </code></pre> </div> <p>This <code>lookup</code> function is declaring that the <code>map</code> <strong>and</strong> <code>key</code> lifetimes must be the same or greater than the result lifetime... however, this actually is not necessary, since the lifetime of the result is <strong>only</strong> dependent on the lifetime of the <code>map</code>. So, we just need the <code>map</code> and result lifetime to be the same, the lifetime of the <code>key</code> can be different:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight rust"><code><span class="k">fn</span> <span class="n">lookup</span><span class="o">&lt;</span><span class="nv">'a</span><span class="p">,</span> <span class="nv">'b</span><span class="o">&gt;</span><span class="p">(</span><span class="n">map</span><span class="p">:</span> <span class="o">&amp;</span><span class="nv">'a</span> <span class="n">HashMap</span><span class="o">&lt;</span><span class="nb">String</span><span class="p">,</span> <span class="nb">String</span><span class="o">&gt;</span><span class="p">,</span> <span class="n">key</span><span class="p">:</span> <span class="o">&amp;</span><span class="nv">'b</span> <span class="nb">String</span><span class="p">)</span> <span class="k">-&gt;</span> <span class="o">&amp;</span><span class="nv">'a</span> <span class="nb">str</span> </code></pre> </div> <p>...and now this code compiles.</p> <h2> Implied Function Lifetime Rules </h2> <p>Rust will try to imply lifetimes using <a href="https://doc.rust-lang.org/beta/reference/lifetime-elision.html">lifetime elision rules</a> to avoid tediously declaring lifetimes which can often be inferred.</p> <p>Rust already knows the lifetime of all function parameters at the call point, the borrow checker just needs help in matching up which function parameter lifetime(s) match with any borrowed result(s)... which is why some of these lifetimes can be implied.</p> <p>The rules:</p> <ul> <li>If a function has no borrowed result, then you don't need to worry about annotating parameters with lifetimes.</li> <li>If a function takes in a single borrowed parameter, <strong>all</strong> borrowed results will have the same lifetime.</li> <li>If a function is actually an object method (it has a borrowed <code>self</code> parameter), <strong>all</strong> borrowed results will have the same lifetime as the object's <code>self</code> parameter.</li> <li>Any borrowed parameter without a lifetime declaration which does not follow a rule above will get a distinct lifetime.</li> </ul> <p>When compiling functions, Rust will enforce the lifetime constraints, so there is no harm in trying to always declare your functions without explicit lifetimes.</p> <h2> Function Result Lifetimes Recap </h2> <p>To recap, we can declare lifetime "template" parameters and use them to describe the relationship between the parameters passed into your function and the result of the function. The borrow checker tries to apply some common patterns for these rules, but it is not perfect, so knowing how to explicitly declare them is necessary at times.</p> <p>The <a href="https://dev.to/brimworks/rust-borrow-checker-explained-part-4-structure-lifetimes-2od0">next article</a> in this series will talk about how to use borrowing inside of your data structures to avoid copying.</p> rust tutorial Brian Maher Sat, 11 Nov 2023 21:13:28 +0000 https://forem.com/brimworks/rust-borrow-checker-explained-part-2-borrowing-4036 https://forem.com/brimworks/rust-borrow-checker-explained-part-2-borrowing-4036 <h2> Intro </h2> <p>In our last article we discussed how to avoid the borrow checker by making copies. In this article, I will introduce the concept of borrowing which allows us to avoid copying and thus increases the performance of our code.</p> <p>More specifically, we will see:</p> <ul> <li>How to perform an immutable borrow using <code>&amp;</code>.</li> <li>How to perform a mutable borrow using <code>&amp;mut</code>.</li> <li>How the borrow check "Angel" will catch errors and keep our code bug free.</li> <li>How to use <code>*</code> to unwrap the borrow.</li> </ul> <h2> Borrowing </h2> <p>It would be a lot more efficient if you could just pass in a pointer instead of copying data around. This is exactly what borrowing is in Rust.</p> <p>In the first part of this series, we tried to compile this code:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight rust"><code><span class="nd">#[derive(Debug)]</span> <span class="k">struct</span> <span class="nf">Num</span><span class="p">(</span><span class="nb">i32</span><span class="p">);</span> <span class="k">fn</span> <span class="nf">main</span><span class="p">()</span> <span class="p">{</span> <span class="k">let</span> <span class="n">num</span> <span class="o">=</span> <span class="nf">Num</span><span class="p">(</span><span class="mi">2</span><span class="p">);</span> <span class="k">let</span> <span class="n">even</span> <span class="o">=</span> <span class="nf">is_even</span><span class="p">(</span><span class="n">num</span><span class="p">);</span> <span class="nd">print!</span><span class="p">(</span><span class="s">"is_even={even:?} num={num:?}"</span><span class="p">)</span> <span class="p">}</span> <span class="k">fn</span> <span class="nf">is_even</span><span class="p">(</span><span class="n">num</span><span class="p">:</span> <span class="nb">Num</span><span class="p">)</span> <span class="k">-&gt;</span> <span class="nb">bool</span> <span class="p">{</span> <span class="n">num</span><span class="na">.0</span> <span class="o">%</span> <span class="mi">2</span> <span class="o">==</span> <span class="mi">0</span> <span class="p">}</span> </code></pre> </div> <p><a href="https://play.rust-lang.org/?version=stable&amp;mode=debug&amp;edition=2021&amp;gist=1f5b4c14547adce39e7ce6c0a4c33641">Try it!</a></p> <p>...and we saw the <code>borrow of moved value</code> error, but if you read a bit further in the error, you would see this:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight plaintext"><code>consider changing this parameter type in function `is_even` to borrow instead if owning the value isn't necessary </code></pre> </div> <p>This suggestion is a better solution than using <code>clone()</code>, since we can avoid copying data.</p> <p>To borrow in Rust, you use <code>&amp;</code> in front of the thing you are borrowing, so we change <code>num.clone()</code> to <code>&amp;num</code>. We also need to declare our <code>is_even()</code> function to take a borrowed <code>&amp;Num</code> type by adding that <code>&amp;</code> in front again:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight rust"><code><span class="nd">#[derive(Debug,</span> <span class="nd">Clone)]</span> <span class="k">struct</span> <span class="nf">Num</span><span class="p">(</span><span class="nb">i32</span><span class="p">,</span> <span class="nb">String</span><span class="p">);</span> <span class="k">fn</span> <span class="nf">main</span><span class="p">()</span> <span class="p">{</span> <span class="k">let</span> <span class="n">num</span> <span class="o">=</span> <span class="nf">Num</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="s">"two"</span><span class="nf">.into</span><span class="p">());</span> <span class="k">let</span> <span class="n">even</span> <span class="o">=</span> <span class="nf">is_even</span><span class="p">(</span><span class="o">&amp;</span><span class="n">num</span><span class="p">);</span> <span class="nd">print!</span><span class="p">(</span><span class="s">"is_even={even:?} num={num:?}"</span><span class="p">)</span> <span class="p">}</span> <span class="k">fn</span> <span class="nf">is_even</span><span class="p">(</span><span class="n">num</span><span class="p">:</span> <span class="o">&amp;</span><span class="nb">Num</span><span class="p">)</span> <span class="k">-&gt;</span> <span class="nb">bool</span> <span class="p">{</span> <span class="n">num</span><span class="na">.0</span> <span class="o">%</span> <span class="mi">2</span> <span class="o">==</span> <span class="mi">0</span> <span class="p">}</span> </code></pre> </div> <p><a href="https://play.rust-lang.org/?version=stable&amp;mode=debug&amp;edition=2021&amp;gist=3aa5d277ef7cd1a91c24c6c577c16f01">Try it!</a></p> <p>Under the covers, instead of copying the entire <code>Num(2, "two")</code> structure onto the stack, a pointer to this structure is placed on the stack, and we avoid copying.</p> <h2> Mutable Borrows </h2> <p>Let's say we want our <code>is_even()</code> function to have a side-effect of modifying the <code>String</code> associated with the <code>Num</code> borrowed in. Now that we are simply pushing a pointer onto the stack, we should be able to produce a side-effect:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight rust"><code><span class="nd">#[derive(Debug,</span> <span class="nd">Clone)]</span> <span class="k">struct</span> <span class="nf">Num</span><span class="p">(</span><span class="nb">i32</span><span class="p">,</span> <span class="nb">String</span><span class="p">);</span> <span class="k">fn</span> <span class="nf">main</span><span class="p">()</span> <span class="p">{</span> <span class="k">let</span> <span class="n">num</span> <span class="o">=</span> <span class="nf">Num</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="s">"two"</span><span class="nf">.into</span><span class="p">());</span> <span class="k">let</span> <span class="n">even</span> <span class="o">=</span> <span class="nf">is_even</span><span class="p">(</span><span class="o">&amp;</span><span class="n">num</span><span class="p">);</span> <span class="nd">print!</span><span class="p">(</span><span class="s">"is_even={even:?} num={num:?}"</span><span class="p">)</span> <span class="p">}</span> <span class="k">fn</span> <span class="nf">is_even</span><span class="p">(</span><span class="n">num</span><span class="p">:</span> <span class="o">&amp;</span><span class="nb">Num</span><span class="p">)</span> <span class="k">-&gt;</span> <span class="nb">bool</span> <span class="p">{</span> <span class="k">let</span> <span class="n">even</span> <span class="o">=</span> <span class="n">num</span><span class="na">.0</span> <span class="o">%</span> <span class="mi">2</span> <span class="o">==</span> <span class="mi">0</span><span class="p">;</span> <span class="n">num</span><span class="na">.1</span> <span class="o">=</span> <span class="k">if</span> <span class="n">even</span> <span class="p">{</span> <span class="s">"even"</span><span class="nf">.into</span><span class="p">()</span> <span class="p">}</span> <span class="k">else</span> <span class="p">{</span> <span class="s">"odd"</span><span class="nf">.into</span><span class="p">()</span> <span class="p">};</span> <span class="k">return</span> <span class="n">even</span><span class="p">;</span> <span class="p">}</span> </code></pre> </div> <p><a href="https://play.rust-lang.org/?version=stable&amp;mode=debug&amp;edition=2021&amp;gist=587851b0ce99efeba8cc600ef2391b6a">Try it!</a></p> <p>...but the compiler is angry again:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight plaintext"><code>error[E0594]: cannot assign to `num.1`, which is behind a `&amp;` reference --&gt; src/main.rs:12:5 </code></pre> </div> <p>This is because everything is immutable by default in Rust. To get over this, we need to declare our references to be mutable, and we need the <code>num</code> in main to also be declared <code>mut</code>:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight rust"><code><span class="nd">#[derive(Debug,</span> <span class="nd">Clone)]</span> <span class="k">struct</span> <span class="nf">Num</span><span class="p">(</span><span class="nb">i32</span><span class="p">,</span> <span class="nb">String</span><span class="p">);</span> <span class="k">fn</span> <span class="nf">main</span><span class="p">()</span> <span class="p">{</span> <span class="k">let</span> <span class="k">mut</span> <span class="n">num</span> <span class="o">=</span> <span class="nf">Num</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="s">"two"</span><span class="nf">.into</span><span class="p">());</span> <span class="k">let</span> <span class="n">even</span> <span class="o">=</span> <span class="nf">is_even</span><span class="p">(</span><span class="o">&amp;</span><span class="k">mut</span> <span class="n">num</span><span class="p">);</span> <span class="nd">print!</span><span class="p">(</span><span class="s">"is_even={even:?} num={num:?}"</span><span class="p">)</span> <span class="p">}</span> <span class="k">fn</span> <span class="nf">is_even</span><span class="p">(</span><span class="n">num</span><span class="p">:</span> <span class="o">&amp;</span><span class="k">mut</span> <span class="nb">Num</span><span class="p">)</span> <span class="k">-&gt;</span> <span class="nb">bool</span> <span class="p">{</span> <span class="k">let</span> <span class="n">even</span> <span class="o">=</span> <span class="n">num</span><span class="na">.0</span> <span class="o">%</span> <span class="mi">2</span> <span class="o">==</span> <span class="mi">0</span><span class="p">;</span> <span class="n">num</span><span class="na">.1</span> <span class="o">=</span> <span class="k">if</span> <span class="n">even</span> <span class="p">{</span> <span class="s">"even"</span><span class="nf">.into</span><span class="p">()</span> <span class="p">}</span> <span class="k">else</span> <span class="p">{</span> <span class="s">"odd"</span><span class="nf">.into</span><span class="p">()</span> <span class="p">};</span> <span class="k">return</span> <span class="n">even</span><span class="p">;</span> <span class="p">}</span> </code></pre> </div> <p><a href="https://play.rust-lang.org/?version=stable&amp;mode=debug&amp;edition=2021&amp;gist=c87955a6ae0dfb6bb336b530ca04f6bf">Try it!</a></p> <p>Easy!</p> <h2> The Borrow Check Angel </h2> <p>Let's switch it up and try implementing a function that splits a string on <code>:</code>.</p> <h3> Copying Split </h3> <p>One straight forward way to implement this is to take the owned <code>String</code> and return an owned <code>String</code>:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight rust"><code><span class="k">fn</span> <span class="nf">main</span><span class="p">()</span> <span class="p">{</span> <span class="k">let</span> <span class="n">key</span> <span class="o">=</span> <span class="nf">split_key</span><span class="p">(</span><span class="s">"left: right"</span><span class="nf">.into</span><span class="p">());</span> <span class="nd">print!</span><span class="p">(</span><span class="s">"key={key}"</span><span class="p">);</span> <span class="p">}</span> <span class="k">fn</span> <span class="nf">split_key</span><span class="p">(</span><span class="nb">str</span><span class="p">:</span> <span class="nb">String</span><span class="p">)</span> <span class="k">-&gt;</span> <span class="nb">String</span> <span class="p">{</span> <span class="k">if</span> <span class="k">let</span> <span class="nf">Some</span><span class="p">(</span><span class="n">colon</span><span class="p">)</span> <span class="o">=</span> <span class="nb">str</span><span class="nf">.find</span><span class="p">(</span><span class="sc">':'</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="nb">str</span><span class="p">[</span><span class="mi">0</span><span class="o">..</span><span class="n">colon</span><span class="p">]</span><span class="nf">.into</span><span class="p">();</span> <span class="p">}</span> <span class="k">return</span> <span class="s">""</span><span class="nf">.into</span><span class="p">();</span> <span class="p">}</span> </code></pre> </div> <p><a href="https://play.rust-lang.org/?version=stable&amp;mode=debug&amp;edition=2021&amp;gist=de5982a2dac6a2889a468c48e22ed23a">Try it!</a></p> <p>However, this has a bunch of copies when performing conversions using <code>.into()</code>.</p> <h3> Borrowing Split </h3> <p>It would be more efficient, if we borrowed the string we split on... and since the result is a substring of the input, we could also have the return type be borrowed too:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight rust"><code><span class="k">fn</span> <span class="nf">main</span><span class="p">()</span> <span class="p">{</span> <span class="c1">// Avoid .into() since "string" type is &amp;str by default:</span> <span class="k">let</span> <span class="n">key</span> <span class="o">=</span> <span class="nf">split_key</span><span class="p">(</span><span class="s">"left: right"</span><span class="p">);</span> <span class="nd">print!</span><span class="p">(</span><span class="s">"key={key}"</span><span class="p">);</span> <span class="p">}</span> <span class="c1">// param is now &amp;str, and result is &amp;str:</span> <span class="k">fn</span> <span class="nf">split_key</span><span class="p">(</span><span class="nb">str</span><span class="p">:</span> <span class="o">&amp;</span><span class="nb">str</span><span class="p">)</span> <span class="k">-&gt;</span> <span class="o">&amp;</span><span class="nb">str</span> <span class="p">{</span> <span class="k">if</span> <span class="k">let</span> <span class="nf">Some</span><span class="p">(</span><span class="n">colon</span><span class="p">)</span> <span class="o">=</span> <span class="nb">str</span><span class="nf">.find</span><span class="p">(</span><span class="sc">':'</span><span class="p">)</span> <span class="p">{</span> <span class="c1">// Avoid .into(), and use `&amp;` to borrow the result:</span> <span class="k">return</span> <span class="o">&amp;</span><span class="nb">str</span><span class="p">[</span><span class="mi">0</span><span class="o">..</span><span class="n">colon</span><span class="p">];</span> <span class="p">}</span> <span class="c1">// Avoid .into()</span> <span class="k">return</span> <span class="s">""</span><span class="p">;</span> <span class="p">}</span> </code></pre> </div> <p><a href="https://play.rust-lang.org/?version=stable&amp;mode=debug&amp;edition=2021&amp;gist=bcb704f2179539438d1663570d230fd7">Try it!</a></p> <p>This implementation completely removes all the string copies from the previous implementation.</p> <h3> Add Parens To Split Result </h3> <p>Requirements changed, and we now want square braces to always be added to the result of <code>split_key()</code>. The <code>format!</code> macro allows us to easily add the square braces. The first argument is our format string <code>"[{}]"</code>, the <code>{}</code> is a place holder for the <code>&amp;str[0..colon]</code> argument, and then we borrow the result:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight rust"><code><span class="k">fn</span> <span class="nf">main</span><span class="p">()</span> <span class="p">{</span> <span class="k">let</span> <span class="n">key</span> <span class="o">=</span> <span class="nf">split_key</span><span class="p">(</span><span class="s">"left: right"</span><span class="p">);</span> <span class="nd">print!</span><span class="p">(</span><span class="s">"key={key}"</span><span class="p">);</span> <span class="p">}</span> <span class="k">fn</span> <span class="nf">split_key</span><span class="p">(</span><span class="nb">str</span><span class="p">:</span> <span class="o">&amp;</span><span class="nb">str</span><span class="p">)</span> <span class="k">-&gt;</span> <span class="o">&amp;</span><span class="nb">str</span> <span class="p">{</span> <span class="k">if</span> <span class="k">let</span> <span class="nf">Some</span><span class="p">(</span><span class="n">colon</span><span class="p">)</span> <span class="o">=</span> <span class="nb">str</span><span class="nf">.find</span><span class="p">(</span><span class="sc">':'</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="o">&amp;</span><span class="nd">format!</span><span class="p">(</span><span class="s">"[{}]"</span><span class="p">,</span> <span class="o">&amp;</span><span class="nb">str</span><span class="p">[</span><span class="mi">0</span><span class="o">..</span><span class="n">colon</span><span class="p">]);</span> <span class="p">}</span> <span class="k">return</span> <span class="s">""</span><span class="p">;</span> <span class="p">}</span> </code></pre> </div> <p><a href="https://play.rust-lang.org/?version=stable&amp;mode=debug&amp;edition=2021&amp;gist=687fb0143be4f1139f21f9e7407769c2">Try it!</a></p> <p>The borrow check <strong>Angel</strong> points out the bug:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight plaintext"><code>error[E0515]: cannot return reference to temporary value --&gt; src/main.rs:9:16 </code></pre> </div> <p>The result of <code>format!</code> is an "owned" <code>String</code> which is a stack local variable, and so we can't just borrow it and return the result. If the compiler did not catch this, then we would have a "dangling" pointer which would be invalid after the <code>split_key()</code> function returns.</p> <p>To fix this, we need to change the function so it returns a <code>String</code> type:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight rust"><code><span class="k">fn</span> <span class="nf">main</span><span class="p">()</span> <span class="p">{</span> <span class="k">let</span> <span class="n">key</span> <span class="o">=</span> <span class="nf">split_key</span><span class="p">(</span><span class="s">"left: right"</span><span class="p">);</span> <span class="nd">print!</span><span class="p">(</span><span class="s">"key={key}"</span><span class="p">);</span> <span class="p">}</span> <span class="k">fn</span> <span class="nf">split_key</span><span class="p">(</span><span class="nb">str</span><span class="p">:</span> <span class="o">&amp;</span><span class="nb">str</span><span class="p">)</span> <span class="k">-&gt;</span> <span class="nb">String</span> <span class="p">{</span> <span class="k">if</span> <span class="k">let</span> <span class="nf">Some</span><span class="p">(</span><span class="n">colon</span><span class="p">)</span> <span class="o">=</span> <span class="nb">str</span><span class="nf">.find</span><span class="p">(</span><span class="sc">':'</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="nd">format!</span><span class="p">(</span><span class="s">"[{}]"</span><span class="p">,</span> <span class="o">&amp;</span><span class="nb">str</span><span class="p">[</span><span class="mi">0</span><span class="o">..</span><span class="n">colon</span><span class="p">]);</span> <span class="p">}</span> <span class="k">return</span> <span class="s">""</span><span class="nf">.into</span><span class="p">();</span> <span class="p">}</span> </code></pre> </div> <h2> Mutable Borrow Exclusivity Rule </h2> <p>One more rule to be aware of is that there can only be a single mutable borrowed value. Let's say that we want to write code that modifies a vector of numbers so that all numbers are odd.<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight rust"><code><span class="k">fn</span> <span class="nf">main</span><span class="p">()</span> <span class="p">{</span> <span class="k">let</span> <span class="k">mut</span> <span class="n">vec</span> <span class="o">=</span> <span class="nd">vec!</span><span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">];</span> <span class="k">for</span> <span class="p">(</span><span class="n">idx</span><span class="p">,</span> <span class="n">num</span><span class="p">)</span> <span class="k">in</span> <span class="n">vec</span><span class="nf">.iter</span><span class="p">()</span><span class="nf">.enumerate</span><span class="p">()</span> <span class="p">{</span> <span class="k">if</span> <span class="n">num</span> <span class="o">%</span> <span class="mi">2</span> <span class="o">==</span> <span class="mi">0</span> <span class="p">{</span> <span class="n">vec</span><span class="p">[</span><span class="n">idx</span><span class="p">]</span> <span class="o">=</span> <span class="n">num</span> <span class="o">+</span> <span class="mi">1</span><span class="p">;</span> <span class="p">}</span> <span class="p">}</span> <span class="p">}</span> </code></pre> </div> <p><a href="https://play.rust-lang.org/?version=stable&amp;mode=debug&amp;edition=2021&amp;gist=5927d6ddf8d4f3a13fd0e1cdb33078e3">Try it!</a></p> <p>The borrow checking Angel helped us out again:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight plaintext"><code>error[E0502]: cannot borrow `vec` as mutable because it is also borrowed as immutable --&gt; src/main.rs:6:13 </code></pre> </div> <p>In Java iterating over a collection and mutating at it the same time, could result in a <a href="https://docs.oracle.com/javase/8/docs/api/java/util/ConcurrentModificationException.html">ConcurrentModificationException</a> at runtime.</p> <p>To fix this, we just need to use <code>iter_mut()</code> instead which iterates over the <code>Vec</code> elements as a <code>&amp;mut</code> element type. The <code>*</code> syntax is needed to unwrap the borrow:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight rust"><code><span class="k">fn</span> <span class="nf">main</span><span class="p">()</span> <span class="p">{</span> <span class="k">let</span> <span class="k">mut</span> <span class="n">vec</span> <span class="o">=</span> <span class="nd">vec!</span><span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">];</span> <span class="k">for</span> <span class="n">num</span> <span class="k">in</span> <span class="n">vec</span><span class="nf">.iter_mut</span><span class="p">()</span> <span class="p">{</span> <span class="k">if</span> <span class="o">*</span><span class="n">num</span> <span class="o">%</span> <span class="mi">2</span> <span class="o">==</span> <span class="mi">0</span> <span class="p">{</span> <span class="o">*</span><span class="n">num</span> <span class="o">=</span> <span class="o">*</span><span class="n">num</span> <span class="o">+</span> <span class="mi">1</span><span class="p">;</span> <span class="p">}</span> <span class="p">}</span> <span class="nd">print!</span><span class="p">(</span><span class="s">"vec={vec:?}"</span><span class="p">)</span> <span class="p">}</span> </code></pre> </div> <p><a href="https://play.rust-lang.org/?version=stable&amp;mode=debug&amp;edition=2021&amp;gist=da43cf47fa128fd3ad84f17bd5d970df">Try it!</a></p> <h2> Borrowing Recap </h2> <p>To recap, we can increase our code performance by borrowing, which under the covers is just a fancy name for a pointer. There are two variations on borrowing, an immutable borrow using <code>&amp;</code> syntax and a mutable borrow which uses the <code>&amp;mut</code> syntax. Mutable borrows are exclusive, so no other borrowing of the same instance is allowed.</p> <p>We also saw how the "borrow checker" is actually very helpful in pointing out when you attempt to use a borrowed value outside of the bounds of the "owned" objects lifetime.</p> <p>So far, the lifetimes of all of our borrows have been implicit, but in <a href="https://dev.to/brimworks/rust-borrow-checker-explained-part-3-function-result-lifetimes-20j6">Part 3</a> we will discuss how to explicitly declare lifetimes.</p> rust tutorial Brian Maher Sun, 05 Nov 2023 04:18:24 +0000 https://forem.com/brimworks/rust-borrow-checker-explained-2ohj https://forem.com/brimworks/rust-borrow-checker-explained-2ohj <h2> Intro </h2> <p>One way to avoid borrowing completely is to make copies, which is the focus of this article:</p> <ul> <li>How memory is managed in Rust using the "stack".</li> <li>How the <code>Copy</code> marker trait is used to denote "trivial" types that are implicitly copied.</li> <li>How the <code>Clone</code> trait allows you to avoid borrowing completely, but at the expense if copying data around.</li> <li>"Moving" rules.</li> </ul> <h2> Stack Memory Management </h2> <p>All memory is managed by a stack per thread in Rust. When calling functions, the arguments are copied onto the stack. During execution of the function, any local variables are pushed onto the stack, too. Finally, when the function returns, any local variables and function arguments are popped off the stack and replaced with the return value(s) of the function.<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight rust"><code><span class="k">fn</span> <span class="nf">main</span><span class="p">()</span> <span class="p">{</span> <span class="k">let</span> <span class="n">num</span> <span class="o">=</span> <span class="mi">2</span><span class="p">;</span> <span class="k">let</span> <span class="n">even</span> <span class="o">=</span> <span class="nf">is_even</span><span class="p">(</span><span class="n">num</span><span class="p">);</span> <span class="nd">print!</span><span class="p">(</span><span class="s">"is_even={even} num={num}"</span><span class="p">)</span> <span class="p">}</span> <span class="k">fn</span> <span class="nf">is_even</span><span class="p">(</span><span class="n">num</span><span class="p">:</span> <span class="nb">i32</span><span class="p">)</span> <span class="k">-&gt;</span> <span class="nb">bool</span> <span class="p">{</span> <span class="n">num</span> <span class="o">%</span> <span class="mi">2</span> <span class="o">==</span> <span class="mi">0</span> <span class="p">}</span> </code></pre> </div> <p><a href="https://play.rust-lang.org/?version=stable&amp;mode=debug&amp;edition=2021&amp;gist=433165cf3591a1b6290ecfd3d7178af7">Try it!</a></p> <p>In this simple example, <code>main</code> is called with no arguments, so the stack is empty. Technically this isn't entirely true, since a "program counter" is always recorded into the stack on every function call so the code knows where to resume execution on return, but we will gloss over that detail for now.</p> <p>The first line of code in <code>main</code> pushes a local variable <code>num</code> onto this stack and assigns it the value <code>2</code>. So, now we have a stack of one value: <code>[2]</code>.</p> <p>TODO: Display a stack visual</p> <p>The second line of code copies <code>num</code> onto the stack and calls <code>is_even</code>. So, now our stack has two values: <code>[2, 2]</code>.</p> <p>TODO: Display a stack visual</p> <p>The <code>is_even</code> function checks if the top of the stack is an even value, and then returns this fact. So, at the end of this function, the stack is now <code>[2, true]</code> (the <code>2</code> function argument gets popped and the function result <code>true</code> is pushed).</p> <p>TODO: Display a stack visual</p> <p>The result of the function is stored in a local variable <code>even</code>, and so the stack continues to contain <code>[2, true]</code> after the second line completes.</p> <p>TODO: Display a stack visual</p> <p>The final line of code prints both the local variables stored on the stack.</p> <p>When <code>main</code> returns, the two local variables are popped off the stack.</p> <p>TODO: Display a stack visual</p> <h2> The <code>Copy</code> trait </h2> <p>In our first example, we worked with the <code>i32</code> type. Let's replace this with our own type the wraps the <code>i32</code> and see what happens:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight rust"><code><span class="nd">#[derive(Debug)]</span> <span class="k">struct</span> <span class="nf">Num</span><span class="p">(</span><span class="nb">i32</span><span class="p">);</span> <span class="k">fn</span> <span class="nf">main</span><span class="p">()</span> <span class="p">{</span> <span class="k">let</span> <span class="n">num</span> <span class="o">=</span> <span class="nf">Num</span><span class="p">(</span><span class="mi">2</span><span class="p">);</span> <span class="k">let</span> <span class="n">even</span> <span class="o">=</span> <span class="nf">is_even</span><span class="p">(</span><span class="n">num</span><span class="p">);</span> <span class="nd">print!</span><span class="p">(</span><span class="s">"is_even={even:?} num={num:?}"</span><span class="p">)</span> <span class="p">}</span> <span class="k">fn</span> <span class="nf">is_even</span><span class="p">(</span><span class="n">num</span><span class="p">:</span> <span class="nb">Num</span><span class="p">)</span> <span class="k">-&gt;</span> <span class="nb">bool</span> <span class="p">{</span> <span class="n">num</span><span class="na">.0</span> <span class="o">%</span> <span class="mi">2</span> <span class="o">==</span> <span class="mi">0</span> <span class="p">}</span> </code></pre> </div> <p><a href="https://play.rust-lang.org/?version=stable&amp;mode=debug&amp;edition=2021&amp;gist=1f5b4c14547adce39e7ce6c0a4c33641">Try it!</a></p> <p>The <code>#[derive(Debug)]</code> and extra <code>:?</code>s in the <code>print!</code> statement are to avoid implementing the <code>Display</code> trait, you can ignore that for now.</p> <p>Overall, this is the same code as our first example, but the <code>i32</code> is wrapped into a <code>Num</code> struct... but the compiler gives us this error:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight plaintext"><code>error[E0382]: borrow of moved value: `num` --&gt; src/main.rs:7:34 </code></pre> </div> <p>Note that this isn't the entire error message, since the Rust compiler tries very hard to give you more useful information on how to fix the problem.</p> <p>So, what is different about the <code>Num</code> struct vs the <code>i32</code>? The difference is that <code>i32</code> "implements" the <code>Copy</code> trait. So, let's change <code>Num</code> so it implements the <code>Copy</code> trait and see if it compiles:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight rust"><code><span class="c1">// Notice the "Clone" is also derived</span> <span class="nd">#[derive(Debug,</span> <span class="nd">Clone)]</span> <span class="k">struct</span> <span class="nf">Num</span><span class="p">(</span><span class="nb">i32</span><span class="p">);</span> <span class="c1">// Notice the "Copy" implementation:</span> <span class="k">impl</span> <span class="nb">Copy</span> <span class="k">for</span> <span class="nb">Num</span> <span class="p">{}</span> <span class="k">fn</span> <span class="nf">main</span><span class="p">()</span> <span class="p">{</span> <span class="k">let</span> <span class="n">num</span> <span class="o">=</span> <span class="nf">Num</span><span class="p">(</span><span class="mi">2</span><span class="p">);</span> <span class="k">let</span> <span class="n">even</span> <span class="o">=</span> <span class="nf">is_even</span><span class="p">(</span><span class="n">num</span><span class="p">);</span> <span class="nd">print!</span><span class="p">(</span><span class="s">"is_even={even:?} num={num:?}"</span><span class="p">)</span> <span class="p">}</span> <span class="k">fn</span> <span class="nf">is_even</span><span class="p">(</span><span class="n">num</span><span class="p">:</span> <span class="nb">Num</span><span class="p">)</span> <span class="k">-&gt;</span> <span class="nb">bool</span> <span class="p">{</span> <span class="n">num</span><span class="na">.0</span> <span class="o">%</span> <span class="mi">2</span> <span class="o">==</span> <span class="mi">0</span> <span class="p">}</span> </code></pre> </div> <p><a href="https://play.rust-lang.org/?version=stable&amp;mode=debug&amp;edition=2021&amp;gist=943c81c709a428143f86cae9d413082d">Try it!</a></p> <p>The <code>Copy</code> trait is a "marker" trait and thus it has no implementation body. In other languages this pattern of implementing a trait which has no code associated with it, might be called a "marker interface" or "tagging interface". </p> <p>Therefore, the <code>impl Copy for Num {}</code> is all that is needed to implement this trait. Note that this trait requires the <code>Clone</code> trait to be implemented, so I added that to the <code>#[derive(Debug, Clone)]</code>.</p> <p>Another way to implement both <code>Clone</code> and <code>Copy</code> is to derive this using: <code>#[derive(Debug, Copy)]</code>.</p> <p>Let's make one small change to the <code>Num</code> struct so it has an English string that describes the number:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight rust"><code><span class="c1">// Notice the extra `String` field:</span> <span class="nd">#[derive(Debug,</span> <span class="nd">Clone)]</span> <span class="k">struct</span> <span class="nf">Num</span><span class="p">(</span><span class="nb">i32</span><span class="p">,</span> <span class="nb">String</span><span class="p">);</span> <span class="k">impl</span> <span class="nb">Copy</span> <span class="k">for</span> <span class="nb">Num</span> <span class="p">{}</span> <span class="k">fn</span> <span class="nf">main</span><span class="p">()</span> <span class="p">{</span> <span class="k">let</span> <span class="n">num</span> <span class="o">=</span> <span class="nf">Num</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="s">"two"</span><span class="nf">.into</span><span class="p">());</span> <span class="k">let</span> <span class="n">even</span> <span class="o">=</span> <span class="nf">is_even</span><span class="p">(</span><span class="n">num</span><span class="p">);</span> <span class="nd">print!</span><span class="p">(</span><span class="s">"is_even={even:?} num={num:?}"</span><span class="p">)</span> <span class="p">}</span> <span class="k">fn</span> <span class="nf">is_even</span><span class="p">(</span><span class="n">num</span><span class="p">:</span> <span class="nb">Num</span><span class="p">)</span> <span class="k">-&gt;</span> <span class="nb">bool</span> <span class="p">{</span> <span class="n">num</span><span class="na">.0</span> <span class="o">%</span> <span class="mi">2</span> <span class="o">==</span> <span class="mi">0</span> <span class="p">}</span> </code></pre> </div> <p><a href="https://play.rust-lang.org/?version=stable&amp;mode=debug&amp;edition=2021&amp;gist=c18a7166c1e6ecafeb10202049fd4fe9">Try it!</a></p> <p>Now we get this error:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight plaintext"><code>error[E0204]: the trait `Copy` cannot be implemented for this type --&gt; src/main.rs:4:15 </code></pre> </div> <p>This is because <strong>all</strong> fields of the struct must implement <code>Copy</code>, but the <code>String</code> type does not implement this.</p> <p>Although it would be handy if <code>String</code> implemented <code>Copy</code>, it is also a potentially computationally expensive operation, since a <code>String</code> is not a fixed size. Imagine if you had a million character string that you passed around. Every time it was passed into a function, your program would need to copy the million characters.</p> <p>However, for simple types (like enums with no associated values), it is highly recommended that you just <code>#[derive(Copy)]</code>.</p> <h2> Cloning </h2> <p>One way to solve the problem of structures that can't implement <code>Copy</code> is to explicitly <code>clone()</code> them.<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight rust"><code><span class="c1">// Notice the Clone is derived and NOT Copy</span> <span class="nd">#[derive(Debug,</span> <span class="nd">Clone)]</span> <span class="k">struct</span> <span class="nf">Num</span><span class="p">(</span><span class="nb">i32</span><span class="p">,</span> <span class="nb">String</span><span class="p">);</span> <span class="k">fn</span> <span class="nf">main</span><span class="p">()</span> <span class="p">{</span> <span class="k">let</span> <span class="n">num</span> <span class="o">=</span> <span class="nf">Num</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="s">"two"</span><span class="nf">.into</span><span class="p">());</span> <span class="c1">// Notice the call to `.clone()`</span> <span class="k">let</span> <span class="n">even</span> <span class="o">=</span> <span class="nf">is_even</span><span class="p">(</span><span class="n">num</span><span class="nf">.clone</span><span class="p">());</span> <span class="nd">print!</span><span class="p">(</span><span class="s">"is_even={even:?} num={num:?}"</span><span class="p">)</span> <span class="p">}</span> <span class="k">fn</span> <span class="nf">is_even</span><span class="p">(</span><span class="n">num</span><span class="p">:</span> <span class="nb">Num</span><span class="p">)</span> <span class="k">-&gt;</span> <span class="nb">bool</span> <span class="p">{</span> <span class="n">num</span><span class="na">.0</span> <span class="o">%</span> <span class="mi">2</span> <span class="o">==</span> <span class="mi">0</span> <span class="p">}</span> </code></pre> </div> <p><a href="https://play.rust-lang.org/?version=stable&amp;mode=debug&amp;edition=2021&amp;gist=1ab53cc4fea8d66e29a192a0f2c0c035">Try it!</a></p> <p>Although this is a great "hammer" to have in your toolbox, you do need to be aware of the performance implications in case the thing being copied around is large.</p> <p>Cloning is also not great for any containers that are managing resources. For example, you probably shouldn't be <code>clone()</code>ing a file descriptor or a mutex.</p> <p>To manage resources, it is recommended to implement the <code>Drop</code> trait so that resources can automatically be "closed" just before their memory is released. The <code>Drop</code> trait is analogous to implementing Java's <code>AutoCloseable</code> interface, and using a <code>try-with-resource</code> block to ensure the resource is "closed", or Golang's <code>defer</code> statement. </p> <h2> Moving (aka shallow copy) </h2> <p>All datatypes in Rust can be "moved", which is just a fancy name for taking a shallow bit-for-bit copy of a datatype. Moving does come with a big restriction though: you can't continue to use the value, and thus in this final example, the <code>is_even()</code> function was modified so it returns the <code>Num</code> that was passed into it.<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight rust"><code><span class="nd">#[derive(Debug)]</span> <span class="k">struct</span> <span class="nf">Num</span><span class="p">(</span><span class="nb">i32</span><span class="p">,</span> <span class="nb">String</span><span class="p">);</span> <span class="k">fn</span> <span class="nf">main</span><span class="p">()</span> <span class="p">{</span> <span class="k">let</span> <span class="n">num</span> <span class="o">=</span> <span class="nf">Num</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="s">"two"</span><span class="nf">.into</span><span class="p">());</span> <span class="c1">// num is "moved" in here:</span> <span class="k">let</span> <span class="p">(</span><span class="n">even</span><span class="p">,</span> <span class="n">num</span><span class="p">)</span> <span class="o">=</span> <span class="nf">is_even</span><span class="p">(</span><span class="n">num</span><span class="p">);</span> <span class="c1">// ...which means we can NOT print it any more</span> <span class="nd">print!</span><span class="p">(</span><span class="s">"is_even={even:?} num={num:?}"</span><span class="p">)</span> <span class="p">}</span> <span class="k">fn</span> <span class="nf">is_even</span><span class="p">(</span><span class="n">num</span><span class="p">:</span> <span class="nb">Num</span><span class="p">)</span> <span class="k">-&gt;</span> <span class="p">(</span><span class="nb">bool</span><span class="p">,</span> <span class="nb">Num</span><span class="p">)</span> <span class="p">{</span> <span class="c1">// num is "moved" out here:</span> <span class="p">(</span><span class="n">num</span><span class="na">.0</span> <span class="o">%</span> <span class="mi">2</span> <span class="o">==</span> <span class="mi">0</span><span class="p">,</span> <span class="n">num</span><span class="p">)</span> <span class="p">}</span> </code></pre> </div> <p><a href="https://play.rust-lang.org/?version=stable&amp;mode=debug&amp;edition=2021&amp;gist=e3bfc3672ac6f1f441e239279883fc2d">Try it!</a></p> <p>If you try to remove the re-assignment to num:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight rust"><code><span class="nd">#[derive(Debug)]</span> <span class="k">struct</span> <span class="nf">Num</span><span class="p">(</span><span class="nb">i32</span><span class="p">,</span> <span class="nb">String</span><span class="p">);</span> <span class="k">fn</span> <span class="nf">main</span><span class="p">()</span> <span class="p">{</span> <span class="k">let</span> <span class="n">num</span> <span class="o">=</span> <span class="nf">Num</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="s">"two"</span><span class="nf">.into</span><span class="p">());</span> <span class="c1">// notice that we no longer re-assign to num!</span> <span class="k">let</span> <span class="p">(</span><span class="n">even</span><span class="p">,</span> <span class="n">_</span><span class="p">)</span> <span class="o">=</span> <span class="nf">is_even</span><span class="p">(</span><span class="n">num</span><span class="p">);</span> <span class="c1">// ...which means we can NOT print it any more</span> <span class="nd">print!</span><span class="p">(</span><span class="s">"is_even={even:?} num={num:?}"</span><span class="p">)</span> <span class="p">}</span> <span class="k">fn</span> <span class="nf">is_even</span><span class="p">(</span><span class="n">num</span><span class="p">:</span> <span class="nb">Num</span><span class="p">)</span> <span class="k">-&gt;</span> <span class="p">(</span><span class="nb">bool</span><span class="p">,</span> <span class="nb">Num</span><span class="p">)</span> <span class="p">{</span> <span class="c1">// num is "moved" out here:</span> <span class="p">(</span><span class="n">num</span><span class="na">.0</span> <span class="o">%</span> <span class="mi">2</span> <span class="o">==</span> <span class="mi">0</span><span class="p">,</span> <span class="n">num</span><span class="p">)</span> <span class="p">}</span> </code></pre> </div> <p>You will get this error:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight plaintext"><code>error[E0382]: borrow of moved value: `num` --&gt; src/main.rs:9:34 </code></pre> </div> <p>This is because line 7 is "stealing" the <code>num</code>, and thus all subsequent attempts to use <code>num</code> (like when it performs "print") will fail.</p> <p>Rust enforces this constraint, since a shallow copy could be stored in a global variable, but there is now multiple shallow copies that are potentially sharing data, since the "deep" parts of that data did not get copied. How would the borrow checker know when the "deep" parts of the data are no longer used?</p> <h2> Recursive Data Structures: <code>Box</code> </h2> <p>In order for the compiler to know how much space is needed to store a structure on the stack, it needs to know the exact size of that structure. Therefore if you try to define a recursive data structure like this:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight rust"><code><span class="nd">#[derive(Debug)]</span> <span class="k">struct</span> <span class="nf">Num</span><span class="p">(</span><span class="nb">i32</span><span class="p">,</span> <span class="nb">Option</span><span class="o">&lt;</span><span class="nb">Num</span><span class="o">&gt;</span><span class="p">);</span> <span class="k">fn</span> <span class="nf">main</span><span class="p">()</span> <span class="p">{</span> <span class="k">let</span> <span class="n">num</span> <span class="o">=</span> <span class="nf">Num</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="nb">None</span><span class="p">);</span> <span class="nd">print!</span><span class="p">(</span><span class="s">"num={num:?}"</span><span class="p">)</span> <span class="p">}</span> </code></pre> </div> <p><a href="https://play.rust-lang.org/?version=stable&amp;mode=debug&amp;edition=2021&amp;gist=7c2beb00d963077a322625d2c2c6cf61">Try it!</a></p> <p>You will get this error:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight plaintext"><code>error[E0072]: recursive type `Num` has infinite size --&gt; src/main.rs:2:1 </code></pre> </div> <p>To get around this limitation, you instead need to have the memory stored on the "heap", and instead just have a unique pointer stored on the stack. You can use the <a href="https://doc.rust-lang.org/std/boxed/struct.Box.html"><code>Box</code></a> datatype in Rust to do this.</p> <p>Let's try to modify the recursive data structure by using a <code>Box</code>:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight rust"><code><span class="nd">#[derive(Debug)]</span> <span class="k">struct</span> <span class="nf">Num</span><span class="p">(</span><span class="nb">i32</span><span class="p">,</span> <span class="nb">Option</span><span class="o">&lt;</span><span class="nb">Box</span><span class="o">&lt;</span><span class="nb">Num</span><span class="o">&gt;&gt;</span><span class="p">);</span> <span class="k">fn</span> <span class="nf">main</span><span class="p">()</span> <span class="p">{</span> <span class="k">let</span> <span class="n">num</span> <span class="o">=</span> <span class="nf">Num</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="nb">None</span><span class="p">);</span> <span class="nd">print!</span><span class="p">(</span><span class="s">"num={num:?}"</span><span class="p">)</span> <span class="p">}</span> </code></pre> </div> <p><a href="https://play.rust-lang.org/?version=stable&amp;mode=debug&amp;edition=2021&amp;gist=7c2beb00d963077a322625d2c2c6cf61">Try it!</a></p> <p>Note that all the same ownership constraints are the same for a <code>Box</code>. However, a <code>Box</code>s size doesn't need to be known at compile time since it dynamically allocates memory on the heap. Recursive data structures are just one example of where this is needed, but this is also needed when working with <code>dyn</code> traits, but this series won't get into the details of that.</p> <h2> Copy &amp; Clone Recap </h2> <p>To recap:</p> <ul> <li>Simple types (in Java these are called "primitives") should implement <code>Copy</code> in order to get implicit copy semantics.</li> <li>Other types, should implement <code>Clone</code>, and you can use the <code>.clone()</code> "hammer" to avoid borrowing. Notice how using this "hammer" is very explicit in our code, since it requires calling <code>.clone()</code>.</li> <li>Any non-memory resource should <strong>not</strong> implement <code>Clone</code> and should instead implement the <code>Drop</code> trait to have the resource automatically released.</li> <li>Rust allows "moving" values to make shallow clones, and if you use this, you will need to return the "moved" value if you want to subsequently make use of it.</li> </ul> <p>To learn how to actually borrow values, please go to <a href="https://dev.to/brimworks/rust-borrow-checker-explained-part-2-borrowing-4036">Part 2</a></p> rust tutorial