---
title: "let edit and edit parameters"
url: https://una-lang.org/en/docs/language/control-flow/let-edit/
release: v0.4.0
edition: "0.2 and later"
source: https://github.com/una-lang/una/blob/v0.4.0/docs/guide/language/control-flow/let-edit.md
---

# let edit and edit parameters

## What it does

From edition `0.2`, values stay values: there are no references (names that share one value, so that a change through one shows through the other) and no lifetimes (rules for how long such a sharing name stays valid), and an editable binding can be rebound, which means the name is given a new value.

Learn more: [Passing a value in and out: edit](https://una-lang.org/en/learn/memory/passing-a-value-in-and-out-edit/).

- **`let edit x = e`** declares a binding that assignments may rebind: `x = e`.
- **A place**, an editable binding or a path of fields inside one, as `t.last`, can be assigned too: `t.last = value` rebuilds `t` with that field changed.
- **An `edit` parameter** is passed in and out. The function receives the caller's value, and the caller's place receives its final value.

```una
module shop

pub kind Visits
  seen: Int
  last: Int

pub record(edit t: Visits, value: Int) -> Unit
  ensures t.seen == old(t).seen + 1
=
  t.seen = t.seen + 1
  t.last = value

pub visits_of(stamps: List[Int]) -> Visits
=
  let edit t = Visits(seen: 0, last: 0)
  for stamp in stamps
    edit t.record(value: stamp)
  t
```

## Forms

In the grammar below, each rule gives a name, `=`, what the name stands for and `;`, quoted words are written as shown, NEWLINE, INDENT and DEDENT stand for a line break and for one more or one less level of indentation, `[ ]` marks an optional part, `{ }` a part that may repeat, `|` separates alternatives, `( )` groups them, and `(* *)` holds a comment.

```ebnf
param           = [ "edit" | "take" ] lower_ident ":" type ;
arg             = [ lower_ident ":" ] ( "edit" place | "take" lower_ident | line_expr ) ;
place           = lower_ident { "." lower_ident } ;
let_stmt        = "let" [ "edit" ] lower_ident [ ":" type ] "=" ( handled | block_expr ) ;
assign_stmt     = place "=" ( handled | block_expr ) ;
postfix         = [ "edit" ] primary { "." lower_ident [ call_args ] | call_args } ;
```

- **`let edit x = e`**, or `let edit x: T = e` with a type that fixes a refinement as an invariant.
- **`p = e`**, where `p` is an editable binding or a field path of one.
- **`edit x: T`** in a parameter list, and **`edit p`** at the matching argument. A method receiver is written `edit t.record(...)`.
- **`old(x)`** in an `ensures` clause: the value of the `edit` parameter `x` on entry.

## Examples

A list's elements change through `set`, never by assignment:

```una
module shop

pub clear_first(prices: List[Int]) -> List[Int]
=
  let edit updated = prices
  if updated.len > 0
    edit updated.set(index: 0, item: 0)
  updated
```

Only an editable binding can be assigned:

```una
-- fails with U2019
module shop

pub next_order(last: Int) -> Int
=
  let order = last
  order = order + 1
  order
```

The caller writes `edit` exactly where the parameter is declared `edit`:

```una
-- fails with U2020
module shop

pub kind Visits
  seen: Int

pub record(edit t: Visits) -> Unit
=
  t.seen = t.seen + 1

pub log_visit(t: Visits) -> Visits
=
  let edit copy = t
  record(copy)
  copy
```

## A failed call rolls back edits, not completed effects

An `edit` argument is transactional for the caller: if the call fails, its local value is unchanged. An effect already performed through a capability is external and remains performed. This example uses a test handler to make that distinction visible:

```una
module demo

pub kind StoreError = | Rejected

pub capability Store
  op write(value: Int) -> Unit

pub update(edit current: Int) -> Unit
  uses @store: Store[write]
  fails StoreError
=
  current = current + 1
  @store.write(current)
  fail Rejected

pub scenario() -> Int
  uses @store: Store[write]
=
  let edit value = 10
  update(edit value)
    if error use unit
  value

handler store() for Store
  op write(value) = unit

example "local rollback preserves an already performed effect"
  given @store = store()
  do scenario()
  expect result == 10
  expect performed @store.write
```

Only the caller's `edit` arguments are restored (`spec/17 §7` rules 1 and 2). An operation performed before the failure stays performed, and the trace records it; Una rolls back nothing in an external system. Undoing it takes another operation, which can fail in turn.

## Edge cases

**Exclusivity.** An `edit p` argument excludes every other use of `p`'s root binding in the same call, even of a disjoint field:

```una
-- fails with U2018
module shop

pub kind Visits
  seen: Int
  last: Int

pub record(edit t: Visits, value: Int) -> Unit
=
  t.seen = t.seen + 1
  t.last = value

pub record_own_count(edit t: Visits) -> Unit
=
  record(edit t, value: t.seen)
```

**Not a value.** A function with an `edit` or `take` parameter can only be called, not passed or returned:

```una
-- fails with U2021
module shop

pub kind Visits
  seen: Int

pub record(edit t: Visits) -> Unit
=
  t.seen = t.seen + 1

pub recorder() -> fn(Visits) -> Unit = record
```

Further rules:

- **Fixed type.** An editable binding keeps its declared type, refinement and label at every rebind. Each rebind carries the obligation of an annotated `let`. Without an annotation, its type is its initial value's without the refinement. In edition `0.3`, it also drops the refinements of nested positions, as `let edit xs = [p]` is a `List[Int]`, and an annotation such as `let edit out: List[Pos] = []` keeps them.
- **Fields of records only.** A place's fields are fields of record kinds; a field of a variant payload is not a place.
- **No compound assignment**, and no assignment to a list element: elements change through `set`.
- **Lambdas capture values.** A lambda captures an editable binding's value when it is created, and cannot edit it (U2019).
- **Transactional.** A call that fails leaves its `edit` arguments unchanged for the caller. Effects already performed stay performed.
- **Labels are fixed.** A rebind under a program counter (the label of the conditions that decide whether the line runs; see [Branches and failures: implicit flows](https://una-lang.org/en/learn/information-flow/branches-and-failures-implicit-flows/)) above the binding's label is U4001, never a silent raise.
- **Not on operations.** Capability operations and handlers cannot declare `edit` or `take` parameters (U2020).
- **One effect per line.** A call with an `edit` argument is the whole expression of a statement or `let` (U3013).

## Diagnostics

- [U0103](https://una-lang.org/en/docs/errors/U0103/): `edit` in edition `0.1`, where it is reserved.
- [U2018](https://una-lang.org/en/docs/errors/U2018/): an `edit` argument used again in the same call.
- [U2019](https://una-lang.org/en/docs/errors/U2019/): an assignment to a binding that is not editable.
- [U2020](https://una-lang.org/en/docs/errors/U2020/): a missing or extra `edit` marker, or an `edit` argument that is not a place.
- [U2021](https://una-lang.org/en/docs/errors/U2021/): a function with conventions used as a value.
- [U3013](https://una-lang.org/en/docs/errors/U3013/): a call with an `edit` argument inside a larger expression.
- [U4001](https://una-lang.org/en/docs/errors/U4001/): a rebind under a program counter above the binding's label.

## Edition

`let edit`, assignments and `edit` parameters exist from edition `0.2` on. In edition `0.1`, `edit` is reserved:

```una
-- edition 0.1
-- fails with U0103
module shop

pub next_order(last: Int) -> Int
=
  let edit order = last
  order = order + 1
  order
```

## Normative source

- `spec/17 §1`: syntax; `spec/17 §2`: places and editable bindings; `spec/17 §3`: parameter conventions.
- `spec/17 §5`: static semantics; `spec/17 §6`: information flow; `spec/17 §7`: dynamic semantics.
- `spec/04 §2`: `old` in `ensures`.
- Decision record: [ADR 0056](https://github.com/una-lang/una/blob/v0.4.0/docs/adr/0056-memory-model.md), for the memory model of edition `0.2`; [ADR 0103](https://github.com/una-lang/una/blob/v0.4.0/docs/adr/0103-refined-elements-of-collections.md), for nested refinements in edition `0.3`.
