Functions

Ignoring elision, function signatures with lifetimes have a few constraints:

  • any reference must have an annotated lifetime.
  • any reference being returned must have the same lifetime as an input or
    be static.

Additionally, note that returning references without input is banned if it
would result in returning references to invalid data. The following example shows
off some valid forms of functions with lifetimes:

  1. // One input reference with lifetime `'a` which must live
  2. // at least as long as the function.
  3. fn print_one<'a>(x: &'a i32) {
  4.     println!("`print_one`: x is {}", x);
  5. }
  7. // Mutable references are possible with lifetimes as well.
  8. fn add_one<'a>(x: &'a mut i32) {
  9.     *x += 1;
  10. }
  12. // Multiple elements with different lifetimes. In this case, it
  13. // would be fine for both to have the same lifetime `'a`, but
  14. // in more complex cases, different lifetimes may be required.
  15. fn print_multi<'a, 'b>(x: &'a i32, y: &'b i32) {
  16.     println!("`print_multi`: x is {}, y is {}", x, y);
  17. }
  19. // Returning references that have been passed in is acceptable.
  20. // However, the correct lifetime must be returned.
  21. fn pass_x<'a, 'b>(x: &'a i32, _: &'b i32) -> &'a i32 { x }
  23. //fn invalid_output<'a>() -> &'a String { &String::from("foo") }
  24. // The above is invalid: `'a` must live longer than the function.
  25. // Here, `&String::from("foo")` would create a `String`, followed by a
  26. // reference. Then the data is dropped upon exiting the scope, leaving
  27. // a reference to invalid data to be returned.
  29. fn main() {
  30.     let x = 7;
  31.     let y = 9;
  33.     print_one(&x);
  34.     print_multi(&x, &y);
  36.     let z = pass_x(&x, &y);
  37.     print_one(z);
  39.     let mut t = 3;
  40.     add_one(&mut t);
  41.     print_one(&t);
  42. }

See also:

functions