Change:
This gives you flexibility without sacrificing performance. You may think that this gives us terrible performance: return a value and then <del> immediately box it up ?! Isn't that the worst of both worlds? Rust is smarter than that. There is no copy in this code. `main` allocates enough room for the `box`, passes a pointer to that memory into `foo` as `x`, and then `foo` writes the value straight into that pointer. This writes the return value directly into the allocated box. </del> <ins> immediately box it up ?! Isn't this pattern the worst of both worlds? Rust is smarter than that. There is no copy in this code. `main` allocates enough room for the `box`, passes a pointer to that memory into `foo` as `x`, and then `foo` writes the value straight into the `Box<T>`. </ins> This is important enough that it bears repeating: pointers are not for optimizing returning values from your code. Allow the caller to choose how they

Discussion:
is as follows: I was by the second to last paragraph of this section. The paragraph uses the word "that" when referencing a memory location and a pointer. The first reference is clear, but the second isn't. This isn't helped by the fact that in the example the label is used for both the variable passed into the function and the parameter inside the function, making it hard to clearly express where and when values are being assigned. It also says the same thing twice The disambiguation should make it clear that both the pointer to x and the pointer to y are being used in the function, where x is explicity passed as a parameter and y is implicitly passed as the return location. The general idea the paragraph expresses is already communicated, but I think it could be more explicit about the mechanics. Currently it almost makes it sound like is returning a value via the passed parameter, or that it is moving the value rather than copying from one heap location to another. Also someone mentioned that the "".
That's wrong / doesn't work / is not implemented. There might be a copy even if the function gets inlined.
seems to disagree. According to the poster it works as described.
It doesn't:
as written, the code does. This is the unoptimised IR of : In particular, there is only one stack slot used which is storing a pointer to , not itself, and the is from the input box straight into the out pointer.
I'm not saying that there are not (trivial) functions where this will work, e.g., does work as expected without a copy. But this is not what the guide is saying: This is wrong once gets even a little complicated, e.g., the function in the other issue. Furthermore, is likely to copy the returned value twice: Once from to the stack of (even if Arc::new is inlined) and then onto the heap. Saying that "Rust is smarter than that" is misleading.
I wrote this section under 's advisement, I'd like his thoughts here.
Correct me if I'm mistaken, but I think the behaviour described here is distinctly different from named return value optimization. The point being made here is that the returned value is immediately placed on the heap and not temporarily on the stack. E.g.

: This will only take 1k of stack space + 1k of heap space, instead of 2k of stack space + 1k of heap space as would be the case without this optimization. With named return value optimization it would only take 1k of heap space. exists precisely to prevent the issue you're describing with . Eventually we hope to have (or at least I think that is the plan).