References

[IGI-111]

This is a tracking issue for the RFC References.
The experimental feature flag for the issue is references.

Description

For detailed description see the RFC References.

For detailed examples of syntax and semantics see the file 0010-references.sw.

Breaking Changes

Replace ref mut function parameters with &mut

To replace ref mut with &mut the following needs to be done:

• In the function definition, every ref mut parameter must be replaced with &mut. E.g.: ref mut x: u64 becomes x: &mut u64.
• When a function is called, the passed parameter must also be marked as &mut. E.g., instead of just passing the parameter p we need to pass &mut p.
• In the function body, depending on the usage and the type of the parameter, it might be needed to dereference the parameter.

Let's take a look on a detailed example:

fn fn_with_ref_mut(ref mut x: u64, ref mut s: MyStruct) {
    x += 1;
    s.some_mutable_method();
}

fn main() {
    let mut x = 0;
    let mut s = MyStruct { ... }

    fn_with_ref_mut(x, s);
}

After the change, the above code will become:

// All `ref mut`s are replaced with `&mut`.
fn fn_with_ref_mut(x: &mut u64, s: &mut MyStruct) {
    // We must dereference `x` (`u64`) to change the referenced value.
    *x += 1;

    // Dereferencing happens automatically for struct method
    // access, so there is no need to dereference `s` here.  
    s.some_mutable_method();
}

fn main() {
    let mut x = 0;
    let mut s = MyStruct { ... }

    // When calling the function, we must pass references
    // to mutable values.
    fn_with_ref_mut(&mut x, &mut s);
}

Steps

• References
  • References and mutability
    • Immutable references to immutable values
    • Mutable references to immutable values
    • Immutable references to mutable values
    • Mutable references to mutable values
  • Referencing expressions
    • Referencing all expressions that can be referenced
    • Referencing references
    • Emitting errors when referencing non-referenceable expressions
  • Embedding references in aggregates
    • Support recursive types
  • Referencing parts of aggregates
  • References in ASM blocks
    • Passing references to ASM blocks
    • Returning references from ASM blocks
  • Impls for reference types
    • For non-generic reference types
    • For generic reference types
  • Trait impls for reference types
    • For non-generic reference types
    • For generic reference types
  • References and generics
  • Dereferencing
    • * operator
    • [] operator
    • . operator
    • Dereferencing as LHS in reassignments
  • References in pattern matching
    • match expression
    • let statement
  • Passing references to functions
    • Remove usages of ref mut #5064
    • self parameter
    • Passing t: &T
    • Passing mut t: &T
    • Passing t: &mut T
    • Passing mut t: &mut T
  • Returning references from functions
    • Returning &Self
    • Returning &mut Self
    • Returning &T
    • Returning &mut T
  • const references
  • References and type aliases
  • Equality of references (core::ops::Eq)
  • __addr_of for references
  • Allocating values on the heap when using references
    • Initial basic escape analysis
    • Allocating values on the heap
  • Forbid references
    • In the storage
    • In the ABI (TODO: Re-discuss this decision.)
    • In the main methods (TODO: Re-discuss this decision.)
• Pointers
  • *mut typed pointer #5066
  • Remove raw_ptr #5067
  • __ptr_cast intrinsic #5068
• Slices
  • New typed slice syntax #5069
  • __slice intrinsic #5070
  • __slice_elem intrinsic #5071
  • str slices #5072
  • Remove raw_slice #5073
• Incorporate the References RFC into the Sway book #5061