1 //! Builds MIR from expressions. As a caller into this module, you 2 //! have many options, but the first thing you have to decide is 3 //! whether you are evaluating this expression for its *value*, its 4 //! *location*, or as a *constant*. 5 //! 6 //! Typically, you want the value: e.g., if you are doing `expr_a + 7 //! expr_b`, you want the values of those expressions. In that case, 8 //! you want one of the following functions. Note that if the expr has 9 //! a type that is not `Copy`, then using any of these functions will 10 //! "move" the value out of its current home (if any). 11 //! 12 //! - `expr_into_dest` -- writes the value into a specific location, which 13 //! should be uninitialized 14 //! - `as_operand` -- evaluates the value and yields an `Operand`, 15 //! suitable for use as an argument to an `Rvalue` 16 //! - `as_temp` -- evaluates into a temporary; this is similar to `as_operand` 17 //! except it always returns a fresh place, even for constants 18 //! - `as_rvalue` -- yields an `Rvalue`, suitable for use in an assignment; 19 //! as of this writing, never needed outside of the `expr` module itself 20 //! 21 //! Sometimes though want the expression's *location*. An example 22 //! would be during a match statement, or the operand of the `&` 23 //! operator. In that case, you want `as_place`. This will create a 24 //! temporary if necessary. 25 //! 26 //! Finally, if it's a constant you seek, then call 27 //! `as_constant`. This creates a `Constant<H>`, but naturally it can 28 //! only be used on constant expressions and hence is needed only in 29 //! very limited contexts. 30 //! 31 //! ### Implementation notes 32 //! 33 //! For any given kind of expression, there is generally one way that 34 //! can be lowered most naturally. This is specified by the 35 //! `Category::of` function in the `category` module. For example, a 36 //! struct expression (or other expression that creates a new value) 37 //! is typically easiest to write in terms of `as_rvalue` or `into`, 38 //! whereas a reference to a field is easiest to write in terms of 39 //! `as_place`. (The exception to this is scope and paren 40 //! expressions, which have no category.) 41 //! 42 //! Therefore, the various functions above make use of one another in 43 //! a descending fashion. For any given expression, you should pick 44 //! the most suitable spot to implement it, and then just let the 45 //! other fns cycle around. The handoff works like this: 46 //! 47 //! - `into(place)` -> fallback is to create a rvalue with `as_rvalue` and assign it to `place` 48 //! - `as_rvalue` -> fallback is to create an Operand with `as_operand` and use `Rvalue::use` 49 //! - `as_operand` -> either invokes `as_constant` or `as_temp` 50 //! - `as_constant` -> (no fallback) 51 //! - `as_temp` -> creates a temporary and either calls `as_place` or `into` 52 //! - `as_place` -> for rvalues, falls back to `as_temp` and returns that 53 //! 54 //! As you can see, there is a cycle where `into` can (in theory) fallback to `as_temp` 55 //! which can fallback to `into`. So if one of the `ExprKind` variants is not, in fact, 56 //! implemented in the category where it is supposed to be, there will be a problem. 57 //! 58 //! Of those fallbacks, the most interesting one is `into`, because 59 //! it discriminates based on the category of the expression. This is 60 //! basically the point where the "by value" operations are bridged 61 //! over to the "by reference" mode (`as_place`). 62 63 pub(crate) mod as_constant; 64 mod as_operand; 65 pub mod as_place; 66 mod as_rvalue; 67 mod as_temp; 68 pub mod category; 69 mod into; 70 mod stmt; 71