106 lines
4.1 KiB
Mojo
Generated
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)
|