Files
pplus-library/mojo/corpus/manual/snippets/manual-values-ownership-1.mojo
alexm 568474d52f
Test (in pplus-core) / in-core (push) Failing after 28m44s
Initial commit
2026-11-12 22:23:48 -05:00

106 lines
4.1 KiB
Mojo
Generated

ref value_ref = list[0]
```
## Argument conventions
In all programming languages, code quality and performance is heavily dependent
upon how functions treat argument values. That is, whether a value received by
a function is a unique value or a reference, and whether it's mutable or
immutable, has a series of consequences that define the readability,
performance, and safety of the language.
In Mojo, we want to provide full [value
semantics](/docs/manual/values/value-semantics) by default, which provides
consistent and predictable behavior. But as a systems programming language, we
also need to offer full control over memory optimizations, which generally
requires reference semantics. The trick is to introduce reference semantics in
a way that ensures all code is memory safe by tracking the lifetime of every
value and destroying each one at the right time (and only once). All of this is
made possible in Mojo through the use of argument conventions that ensure every
value has only one owner at a time.
An argument convention specifies whether an argument is mutable or immutable,
and whether the function owns the value. Each convention is defined by a
keyword at the beginning of an argument declaration:
- default: The function receives an **immutable reference**. This means the
function can read the original value (it's *not* a copy), but it can't
mutate (modify) it.
- `mut`: The function receives a **mutable reference**. This means the
function can read and mutate the original value (it's *not* a copy).
- `var`: The function takes **ownership** of a value. This means the function
has exclusive ownership of the argument. The caller might choose to transfer
ownership of an existing value to this function, but that's not always what
happens. The callee might receive a newly-created value, or a copy of an
existing value.
- `ref`: The function gets a reference with a parametric mutability: that is,
it follows the mutability of the referenced value.
`ref` arguments are an advanced topic, and they're described in more detail in
[Lifetimes, origins, and references](/docs/manual/values/lifetimes/).
- `out`: A special convention used for the `self` argument in
[initializers](/docs/manual/lifecycle/life/#constructor) and for
[named results](/docs/manual/functions/#named-results). An `out`
argument is uninitialized at the beginning of the function, and must be
initialized before the function returns. Although `out` arguments show up in
the argument list, they're never passed in by the caller.
- `deinit`: A special convention used in the deinitializer and consuming-move
lifecycle methods. A `deinit` argument is initialized at the beginning of the
function, and uninitialized when the function returns.
For example, this function has one argument that's a mutable
reference and one that's immutable:
```mojo
def add(mut x: Int, y: Int):
x += y
def main():
var a = 1
var b = 2
add(a, b)
print(a) # 3
```
You've probably already seen some function arguments that don't declare a
convention. By default, all arguments use the default convention of an
immutable read-only reference. In the following sections, we'll explain
each of these conventions in more detail.
### Deinitializing arguments (`deinit`)
The `deinit` convention isn't limited to `self`. You can write methods
and functions that destruct other instances:
```mojo
struct Pair:
def destroy_other(self, deinit other: Self):
# Can take from fields of `other` here
```
Like `deinit self`, the `deinit` convention in this example tells the
compiler that `other` is tagged for destruction.
Using `deinit` means `other` is logically deinitialized at the end of the
method. Because of this, it's safe to move values out of `other`, since
the instance's lifetime is guaranteed to complete.
## Immutable arguments (default)
The default convention is an immutable read-only reference. The callee
receives an immutable reference to the argument value.
For example:
```mojo
def print_list(list: List[Int]):
print(list.__str__())
def main():
var values: List[Int] = [1, 2, 3, 4]
print_list(values)