1 % The Rust Pointer Guide
3 Rust's pointers are one of its more unique and compelling features. Pointers
4 are also one of the more confusing topics for newcomers to Rust. They can also
5 be confusing for people coming from other languages that support pointers, such
6 as C++. This guide will help you understand this important topic.
8 Be sceptical of non-reference pointers in Rust: use them for a deliberate
9 purpose, not just to make the compiler happy. Each pointer type comes with an
10 explanation about when they are appropriate to use. Default to references
11 unless you're in one of those specific situations.
13 You may be interested in the [cheat sheet](#cheat-sheet), which gives a quick
14 overview of the types, names, and purpose of the various pointers.
18 If you aren't familiar with the concept of pointers, here's a short
19 introduction. Pointers are a very fundamental concept in systems programming
20 languages, so it's important to understand them.
24 When you create a new variable binding, you're giving a name to a value that's
25 stored at a particular location on the stack. (If you're not familiar with the
26 "heap" vs. "stack", please check out [this Stack Overflow
27 question](http://stackoverflow.com/questions/79923/what-and-where-are-the-stack-and-heap),
28 as the rest of this guide assumes you know the difference.) Like this:
39 We're making up memory locations here, they're just sample values. Anyway, the
40 point is that `x`, the name we're using for our variable, corresponds to the
41 memory location `0xd3e030`, and the value at that location is `5`. When we
42 refer to `x`, we get the corresponding value. Hence, `x` is `5`.
44 Let's introduce a pointer. In some languages, there is just one type of
45 'pointer,' but in Rust, we have many types. In this case, we'll use a Rust
46 **reference**, which is the simplest kind of pointer.
54 |-------- |----------|
57 |0xd3e020 | 0xd3e028 |
59 See the difference? Rather than contain a value, the value of a pointer is a
60 location in memory. In this case, the location of `y`. `x` and `y` have the
61 type `int`, but `z` has the type `&int`. We can print this location using the
72 This would print `0xd3e028`, with our fictional memory addresses.
74 Because `int` and `&int` are different types, we can't, for example, add them
82 println!("{}", x + z);
85 This gives us an error:
88 hello.rs:6:24: 6:25 error: mismatched types: expected `int` but found `&int` (expected int but found &-ptr)
89 hello.rs:6 println!("{}", x + z);
93 We can **dereference** the pointer by using the `*` operator. Dereferencing a
94 pointer means accessing the value at the location stored in the pointer. This
102 println!("{}", x + *z);
107 That's it! That's all pointers are: they point to some memory location. Not
108 much else to them. Now that we've discussed the 'what' of pointers, let's
109 talk about the 'why.'
113 Rust's pointers are quite useful, but in different ways than in other systems
114 languages. We'll talk about best practices for Rust pointers later in
115 the guide, but here are some ways that pointers are useful in other languages:
117 In C, strings are a pointer to a list of `char`s, ending with a null byte.
118 The only way to use strings is to get quite familiar with pointers.
120 Pointers are useful to point to memory locations that are not on the stack. For
121 example, our example used two stack variables, so we were able to give them
122 names. But if we allocated some heap memory, we wouldn't have that name
123 available. In C, `malloc` is used to allocate heap memory, and it returns a
126 As a more general variant of the previous two points, any time you have a
127 structure that can change in size, you need a pointer. You can't tell at
128 compile time how much memory to allocate, so you've gotta use a pointer to
129 point at the memory where it will be allocated, and deal with it at run time.
131 Pointers are useful in languages that are pass-by-value, rather than
132 pass-by-reference. Basically, languages can make two choices (this is made
133 up syntax, it's not Rust):
143 // what is the value of i here?
147 In languages that are pass-by-value, `foo` will get a copy of `i`, and so
148 the original version of `i` is not modified. At the comment, `i` will still be
149 `1`. In a language that is pass-by-reference, `foo` will get a reference to `i`,
150 and therefore, can change its value. At the comment, `i` will be `5`.
152 So what do pointers have to do with this? Well, since pointers point to a
153 location in memory...
163 // what is the value of i here?
167 Even in a language which is pass by value, `i` will be `5` at the comment. You
168 see, because the argument `x` is a pointer, we do send a copy over to `foo`,
169 but because it points at a memory location, which we then assign to, the
170 original value is still changed. This pattern is called
171 'pass-reference-by-value.' Tricky!
173 ## Common pointer problems
175 We've talked about pointers, and we've sung their praises. So what's the
176 downside? Well, Rust attempts to mitigate each of these kinds of problems,
177 but here are problems with pointers in other languages:
179 Uninitialized pointers can cause a problem. For example, what does this program
187 Who knows? We just declare a pointer, but don't point it at anything, and then
188 set the memory location that it points at to be `5`. But which location? Nobody
189 knows. This might be harmless, and it might be catastrophic.
191 When you combine pointers and functions, it's easy to accidentally invalidate
192 the memory the pointer is pointing to. For example:
195 func make_pointer(): &int {
202 &int i = make_pointer();
207 `x` is local to the `make_pointer` function, and therefore, is invalid as soon
208 as `make_pointer` returns. But we return a pointer to its memory location, and
209 so back in `main`, we try to use that pointer, and it's a very similar
210 situation to our first one. Setting invalid memory locations is bad.
212 As one last example of a big problem with pointers, **aliasing** can be an
213 issue. Two pointers are said to alias when they point at the same location
214 in memory. Like this:
217 func mutate(&int i, int j) {
224 z = &x; //y and z are aliased
227 run_in_new_thread(mutate, y, 1);
228 run_in_new_thread(mutate, z, 100);
230 // what is the value of x here?
234 In this made-up example, `run_in_new_thread` spins up a new thread, and calls
235 the given function name with its arguments. Since we have two threads, and
236 they're both operating on aliases to `x`, we can't tell which one finishes
237 first, and therefore, the value of `x` is actually non-deterministic. Worse,
238 what if one of them had invalidated the memory location they pointed to? We'd
239 have the same problem as before, where we'd be setting an invalid location.
243 That's a basic overview of pointers as a general concept. As we alluded to
244 before, Rust has different kinds of pointers, rather than just one, and
245 mitigates all of the problems that we talked about, too. This does mean that
246 Rust pointers are slightly more complicated than in other languages, but
247 it's worth it to not have the problems that simple pointers have.
251 The most basic type of pointer that Rust has is called a 'reference.' Rust
252 references look like this:
263 We'd say "`y` is a reference to `x`." The first `println!` prints out the
264 value of `y`'s referent by using the dereference operator, `*`. The second
265 one prints out the memory location that `y` points to, by using the pointer
266 format string. The third `println!` *also* prints out the value of `y`'s
267 referent, because `println!` will automatically dereference it for us.
269 Here's a function that takes a reference:
272 fn succ(x: &int) -> int { *x + 1 }
275 You can also use `&` as an operator to create a reference, so we can
276 call this function in two different ways:
279 fn succ(x: &int) -> int { *x + 1 }
286 println!("{}", succ(y));
287 println!("{}", succ(&x));
291 Both of these `println!`s will print out `6`.
293 Of course, if this were real code, we wouldn't bother with the reference, and
297 fn succ(x: int) -> int { x + 1 }
300 References are immutable by default:
306 *y = 5; // error: cannot assign to immutable dereference of `&`-pointer `*y`
309 They can be made mutable with `mut`, but only if its referent is also mutable.
321 let y = &mut x; // error: cannot borrow immutable local variable `x` as mutable
324 Immutable pointers are allowed to alias:
332 Mutable ones, however, are not:
337 let z = &mut x; // error: cannot borrow `x` as mutable more than once at a time
340 Despite their complete safety, a reference's representation at runtime is the
341 same as that of an ordinary pointer in a C program. They introduce zero
342 overhead. The compiler does all safety checks at compile time. The theory that
343 allows for this was originally called **region pointers**. Region pointers
344 evolved into what we know today as **lifetimes**.
346 Here's the simple explanation: would you expect this code to compile?
355 Probably not. That's because you know that the name `x` is valid from where
356 it's declared to when it goes out of scope. In this case, that's the end of
357 the `main` function. So you know this code will cause an error. We call this
358 duration a 'lifetime'. Let's try a more complex example:
367 println!("Oh no: {}", y);
373 println!("Oh no: {}", x);
377 Here, we're borrowing a pointer to `x` inside of the `if`. The compiler, however,
378 is able to determine that that pointer will go out of scope without `x` being
379 mutated, and therefore, lets us pass. This wouldn't work:
389 println!("Oh no: {}", y);
395 println!("Oh no: {}", x);
402 test.rs:5:8: 5:10 error: cannot assign to `*x` because it is borrowed
405 test.rs:4:16: 4:18 note: borrow of `*x` occurs here
406 test.rs:4 let y = &x;
410 As you might guess, this kind of analysis is complex for a human, and therefore
411 hard for a computer, too! There is an entire [guide devoted to references, ownership,
412 and lifetimes](guide-ownership.html) that goes into this topic in
413 great detail, so if you want the full details, check that out.
417 In general, prefer stack allocation over heap allocation. Using references to
418 stack allocated information is preferred whenever possible. Therefore,
419 references are the default pointer type you should use, unless you have a
420 specific reason to use a different type. The other types of pointers cover when
421 they're appropriate to use in their own best practices sections.
423 Use references when you want to use a pointer, but do not want to take ownership.
424 References just borrow ownership, which is more polite if you don't need the
425 ownership. In other words, prefer:
428 fn succ(x: &int) -> int { *x + 1 }
434 fn succ(x: Box<int>) -> int { *x + 1 }
437 As a corollary to that rule, references allow you to accept a wide variety of
438 other pointers, and so are useful so that you don't have to write a number
439 of variants per pointer. In other words, prefer:
442 fn succ(x: &int) -> int { *x + 1 }
450 fn box_succ(x: Box<int>) -> int { *x + 1 }
452 fn rc_succ(x: Rc<int>) -> int { *x + 1 }
455 Note that the caller of your function will have to modify their calls slightly:
458 # use std::boxed::Box;
461 fn succ(x: &int) -> int { *x + 1 }
464 let box_x = Box::new(5i);
465 let rc_x = Rc::new(5i);
472 The initial `*` dereferences the pointer, and then `&` takes a reference to
477 `Box<T>` is Rust's 'boxed pointer' type. Boxes provide the simplest form of
478 heap allocation in Rust. Creating a box looks like this:
481 # use std::boxed::Box;
482 let x = Box::new(5i);
485 Boxes are heap allocated and they are deallocated automatically by Rust when
486 they go out of scope:
489 # use std::boxed::Box;
491 let x = Box::new(5i);
495 } // x is destructed and its memory is free'd here
498 However, boxes do _not_ use reference counting or garbage collection. Boxes are
499 what's called an **affine type**. This means that the Rust compiler, at compile
500 time, determines when the box comes into and goes out of scope, and inserts the
501 appropriate calls there. Furthermore, boxes are a specific kind of affine type,
502 known as a **region**. You can read more about regions [in this paper on the
504 language](http://www.cs.umd.edu/projects/cyclone/papers/cyclone-regions.pdf).
506 You don't need to fully grok the theory of affine types or regions to grok
507 boxes, though. As a rough approximation, you can treat this Rust code:
510 # use std::boxed::Box;
512 let x = Box::new(5i);
518 As being similar to this C code:
523 x = (int *)malloc(sizeof(int));
532 Of course, this is a 10,000 foot view. It leaves out destructors, for example.
533 But the general idea is correct: you get the semantics of `malloc`/`free`, but
534 with some improvements:
536 1. It's impossible to allocate the incorrect amount of memory, because Rust
537 figures it out from the types.
538 2. You cannot forget to `free` memory you've allocated, because Rust does it
540 3. Rust ensures that this `free` happens at the right time, when it is truly
541 not used. Use-after-free is not possible.
542 4. Rust enforces that no other writeable pointers alias to this heap memory,
543 which means writing to an invalid pointer is not possible.
545 See the section on references or the [ownership guide](guide-ownership.html)
546 for more detail on how lifetimes work.
548 Using boxes and references together is very common. For example:
551 # use std::boxed::Box;
552 fn add_one(x: &int) -> int {
557 let x = Box::new(5i);
559 println!("{}", add_one(&*x));
563 In this case, Rust knows that `x` is being 'borrowed' by the `add_one()`
564 function, and since it's only reading the value, allows it.
566 We can borrow `x` multiple times, as long as it's not simultaneous:
569 # use std::boxed::Box;
570 fn add_one(x: &int) -> int {
575 let x = Box::new(5i);
577 println!("{}", add_one(&*x));
578 println!("{}", add_one(&*x));
579 println!("{}", add_one(&*x));
583 Or as long as it's not a mutable borrow. This will error:
586 # use std::boxed::Box;
587 fn add_one(x: &mut int) -> int {
592 let x = Box::new(5i);
594 println!("{}", add_one(&*x)); // error: cannot borrow immutable dereference
595 // of `&`-pointer as mutable
599 Notice we changed the signature of `add_one()` to request a mutable reference.
603 Boxes are appropriate to use in two situations: Recursive data structures,
604 and occasionally, when returning data.
606 ### Recursive data structures
608 Sometimes, you need a recursive data structure. The simplest is known as a
613 # use std::boxed::Box;
616 Cons(T, Box<List<T>>),
621 let list: List<int> = List::Cons(1, Box::new(List::Cons(2, Box::new(List::Cons(3, Box::new(List::Nil))))));
622 println!("{:?}", list);
629 Cons(1, Box(Cons(2, Box(Cons(3, Box(Nil))))))
632 The reference to another `List` inside of the `Cons` enum variant must be a box,
633 because we don't know the length of the list. Because we don't know the length,
634 we don't know the size, and therefore, we need to heap allocate our list.
636 Working with recursive or other unknown-sized data structures is the primary
641 This is important enough to have its own section entirely. The TL;DR is this:
642 you don't generally want to return pointers, even when you might in a language
645 See [Returning Pointers](#returning-pointers) below for more.
649 This part is coming soon.
653 This part is coming soon.
657 This part is coming soon.
661 This part is coming soon.
665 In many languages with pointers, you'd return a pointer from a function
666 so as to avoid copying a large data structure. For example:
669 # use std::boxed::Box;
677 fn foo(x: Box<BigStruct>) -> Box<BigStruct> {
682 let x = Box::new(BigStruct {
692 The idea is that by passing around a box, you're only copying a pointer, rather
693 than the hundred `int`s that make up the `BigStruct`.
695 This is an antipattern in Rust. Instead, write this:
698 # use std::boxed::Box;
706 fn foo(x: Box<BigStruct>) -> BigStruct {
711 let x = Box::new(BigStruct {
717 let y = Box::new(foo(x));
721 This gives you flexibility without sacrificing performance.
723 You may think that this gives us terrible performance: return a value and then
724 immediately box it up ?! Isn't that the worst of both worlds? Rust is smarter
725 than that. There is no copy in this code. `main` allocates enough room for the
726 `box`, passes a pointer to that memory into `foo` as `x`, and then `foo` writes
727 the value straight into that pointer. This writes the return value directly into
730 This is important enough that it bears repeating: pointers are not for
731 optimizing returning values from your code. Allow the caller to choose how they
732 want to use your output.
734 # Creating your own Pointers
736 This part is coming soon.
740 This part is coming soon.
744 When you're trying to match something that's stored in a pointer, there may be
745 a situation where matching directly isn't the best option available. Let's see
746 how to properly handle this:
749 fn possibly_print(x: &Option<String>) {
751 // BAD: cannot move out of a `&`
752 Some(s) => println!("{}", s)
754 // GOOD: instead take a reference into the memory of the `Option`
755 Some(ref s) => println!("{}", *s),
761 The `ref s` here means that `s` will be of type `&String`, rather than type
764 This is important when the type you're trying to get access to has a destructor
765 and you don't want to move it, you just want a reference to it.
769 Here's a quick rundown of Rust's pointer types:
771 | Type | Name | Summary |
772 |--------------|---------------------|---------------------------------------------------------------------|
773 | `&T` | Reference | Allows one or more references to read `T` |
774 | `&mut T` | Mutable Reference | Allows a single reference to read and write `T` |
775 | `Box<T>` | Box | Heap allocated `T` with a single owner that may read and write `T`. |
776 | `Rc<T>` | "arr cee" pointer | Heap allocated `T` with many readers |
777 | `Arc<T>` | Arc pointer | Same as above, but safe sharing across threads |
778 | `*const T` | Raw pointer | Unsafe read access to `T` |
779 | `*mut T` | Mutable raw pointer | Unsafe read and write access to `T` |
783 * [API documentation for Box](std/boxed/index.html)
784 * [Ownership guide](guide-ownership.html)
785 * [Cyclone paper on regions](http://www.cs.umd.edu/projects/cyclone/papers/cyclone-regions.pdf), which inspired Rust's lifetime system