This commit is contained in:
commit
568474d52f
1591 files changed
+528213
No files matched your search
@@ -0,0 +1,105 @@
|
||||
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)
|
||||
Reference in new issue
Block a user