---
title: "16.1 Values, not references"
url: https://una-lang.org/en/learn/memory/values-not-references/
release: v0.4.0
edition: "0.2"
---

# 16.1 Values, not references

## 16.1.1 What a value is

A **value** is a piece of data: the number 4, the text `"LAMP-01"`, a list `[4, 0, 7]`, or a record such as a shelf with its SKU and its units. A **binding** is a name for a value, made with `let` ([section 2.1](https://una-lang.org/en/learn/numbers/values-types-and-names-let/#s2-1)) or `let edit` ([section 9.2](https://una-lang.org/en/learn/loops/names-that-change-let-edit/#s9-2)), and a parameter is a binding too. You have used values and bindings since chapter 2. This section says what happens when one binding is made from another.

Think of a stock sheet on paper. When a clerk photocopies it and writes on the copy, the original does not change: the copy is a sheet of its own. Una's values work like the photocopy. Writing `let snapshot = current` gives `snapshot` its own copy of `current`'s value, and nothing that later happens to `current` reaches it.

Many languages work like a shared whiteboard instead. There, a name holds a **reference**, an address where the data lives, and two names can hold the same address. Two such names share the data: write through one, and the other sees the change. Una has no references, so two bindings never share a value that changes. To **mutate** a value, meaning to change it after it was made, you rebind a name that you declared editable, and only that name sees the change.

Each example of this chapter is a package, made as [chapter 2](https://una-lang.org/en/learn/numbers/values-types-and-names-let/#each-step-is-a-package) explains, and the chapter's download, `16-memory.tar.gz`, holds them all. Every package of this chapter uses edition `0.2`, the edition that brings `let edit`, loops and the parameter modes `edit` and `take`; a package of edition `0.1` has none of them ([chapter 19](https://una-lang.org/en/learn/editions/) covers editions).

## 16.1.2 Why Una has no shared references

With aliases, a change in one place shows up somewhere else. A report reads a shelf's count, some other code changes the shelf, and the report now prints a number it never computed. Finding the cause means finding every name that could hold the same data. With values, the cause of every change is a line that names the binding it changes.

This module declares a shelf, takes a copy at the start of the day, changes the shelf twice, and keeps a snapshot between the changes:

:::steps
```una include="steps/01-values/src/shelf.una" title="steps/01-values/src/shelf.una" verified="check, run"
module shelf

--- A shelf of the store: the SKU it holds and how many units are on it.
kind Shelf
  sku: Text
  units: Int

pub main() -> Unit
  uses @console: Console[print]
=
  let opening = Shelf(sku: "LAMP-01", units: 4)
  let edit current = opening
  current.units = current.units + 6
  let snapshot = current
  current.units = current.units - 3
  let edit counts = [4, 0, 7]
  edit counts.set(index: 1, item: 12)
  @console.print("opening {opening.units}, snapshot {snapshot.units}, now {current.units}")
  @console.print("counts {counts}")
  @console.print("{current}")
```

1. **`let opening = Shelf(…)`.** A plain `let` binds a value for good. Assigning `opening` later is U2019, the code of an assignment to a binding that is not editable.
2. **`let edit current = opening`.** An editable binding, as in [section 9.2](https://una-lang.org/en/learn/loops/names-that-change-let-edit/#s9-2), starts as a copy of `opening`'s value. Its type is fixed by that first value: it stays a `Shelf`.
3. **`current.units = current.units + 6`.** Assigning a field of an editable record rebinds `current` to a record with that field changed. `opening` keeps its own value, since it is another binding.
4. **`let snapshot = current`.** The snapshot is the value `current` has on this line. The next assignment to `current` does not reach it.
5. **`edit counts.set(index: 1, item: 12)`.** A list element changes through `set`, never by assignment, and the call says `edit`, as in [section 10.1](https://una-lang.org/en/learn/collections/lists/#s10-1). `set` requires an index inside the list, and the verifier proves it here from the list's length.
:::

`una run .` prints:

```text include="steps/01-values/expected/output.txt"
opening 4, snapshot 10, now 7
counts [4, 12, 7]
Shelf(sku: "LAMP-01", units: 7)
```

Three numbers, three values: the opening count, 4; the snapshot, 10; and the shelf now, 7. In a language where `current`, `opening` and `snapshot` were references to one shelf, all three would print 7. The last line prints the whole record: in edition `0.2`, interpolation writes out a whole record, list or map, a record of several fields as its name and the names and values of its fields, as here.

## 16.1.3 How to change a binding

[Section 9.2](https://una-lang.org/en/learn/loops/names-that-change-let-edit/#s9-2) taught the **assignment**: the binding, then `=`, then the new value. Only an editable binding changes, and only by an assignment or by a call that says `edit`. The part on the left of `=` is a **place**: an editable binding, or a field of one, as deep as the record goes. The word matters in [section 16.2](https://una-lang.org/en/learn/memory/passing-a-value-in-and-out-edit/#s16-2), where an `edit` argument must be a place too. This step shows each form:

```una include="steps/02-places/src/places.una#L1-L12" title="steps/02-places/src/places.una" caption="the kinds"
module places

--- Where a customer's orders are shipped.
kind Address
  street: Text
  city: Text

--- A customer of the store, with the loyalty points they hold.
kind Customer
  number: Text
  address: Address
  points: Int
```

```una include="steps/02-places/src/places.una#L23-L35" title="steps/02-places/src/places.una" caption="main"
pub main() -> Unit
  uses @console: Console[print]
=
  let edit points = 120
  points = points + 30
  @console.print("points: {points}")
  let edit customer = Customer(number: "C-1042", address: Address(street: "1 Elm Row", city: "Porto"), points: points)
  customer.points = customer.points + 10
  customer.address.city = "Braga"
  @console.print("customer: {customer.points} points, ships to {customer.address.city}")
  let edit shelves = [4, 0, 7]
  edit shelves.set(index: 1, item: 12)
  @console.print("shelves: {shelves}")
```

```text include="steps/02-places/expected/output.txt#L1-L3"
points: 150
customer: 160 points, ships to Braga
shelves: [4, 12, 7]
```

### 16.1.3.1 A whole binding

`points = points + 30` gives `points` a new value computed from its old one. The right side is read first, with the old value, and then the binding takes the result: 120 + 30 is 150.

### 16.1.3.2 A field of a record, at any depth

`customer.points = customer.points + 10` changes one field. `customer.address.city = "Braga"` changes a field of a field: the address inside the customer. In both, una builds a new record with that field changed and rebinds `customer` to it; every other field keeps its value. Each field in the path must be a field of a record kind, and the path must start at an editable binding.

### 16.1.3.3 An element of a list: `set`

A list has no assignable positions: `shelves[1] = 12` is not Una. The prelude function `set` of [section 10.1](https://una-lang.org/en/learn/collections/lists/#s10-1) changes one element, and since it changes the list it is given, it takes the list as an `edit` parameter, which [section 16.2](https://una-lang.org/en/learn/memory/passing-a-value-in-and-out-edit/#s16-2) explains. You write `edit` before the list: `edit shelves.set(index: 1, item: 12)`. Positions count from 0, so index 1 is the second element. A map changes the same way, with `edit stock.set(key: …, value: …)` or `edit stock.remove(key: …)` ([section 10.4](https://una-lang.org/en/learn/collections/maps/#s10-4)), or by assigning the new map that `with` gives back.

## 16.1.4 How values behave

### 16.1.4.1 A copy is its own value

`let snapshot = current` copies, and so does passing a value to a function, putting it in a list, or storing it in a record. After the copy, the two are separate: assigning one never changes the other, as the snapshot of [Why Una has no shared references](#why-una-has-no-shared-references) showed.

### 16.1.4.2 An editable binding keeps its type

A `let edit` binding takes its type from its first value, and every later value must have that type, as [section 9.2](https://una-lang.org/en/learn/loops/names-that-change-let-edit/#an-editable-name-keeps-its-type) showed for a number. The rule holds for every place, a field included. Assign a text to `points`:

```diff include="steps/02-places..steps/03-fixed-type:src/places.una" context="0" title="src/places.una"
--- a/src/places.una
+++ b/src/places.una
@@ -27 +27 @@
-  points = points + 30
+  points = "150 points"
```

```text include="steps/03-fixed-type/expected/rendered.txt"
[U2001] Error: expected `Int`, found `Text`
    ╭─[ src/places.una:27:12 ]
    │
 27 │   points = "150 points"
    │            ──────┬─────
    │                  ╰─────── expected `Int`, found `Text`
    │
    │ Note: run `una explain U2001` for an explanation
────╯
```

The mark points at the new value: the binding is an `Int`, and the value is a `Text`. A binding that holds a refined kind, such as `Cents` of [chapter 5](https://una-lang.org/en/learn/contracts/refined-kinds-and-predicates/#s5-3), keeps its condition only when you write the type: `let edit total: Cents = 0`, as [section 9.3](https://una-lang.org/en/learn/loops/what-a-loop-keeps-and-what-the-verifier-knows/#keeping-a-fact-through-the-loop-a-refined-type) did with `Units`. Without it, the binding is a plain `Int`.

### 16.1.4.3 Only an editable binding changes

Assigning a plain `let` binding, a parameter declared without `edit`, the variable of a `for` loop or, inside a lambda, a binding it captured is U2019 ([section 9.2](https://una-lang.org/en/learn/loops/names-that-change-let-edit/#s9-2); [Assigning a plain `let`](https://una-lang.org/en/learn/loops/common-mistakes/#assigning-a-plain-let-u2019) shows the message). A lambda keeps a copy of each value it captures when it is made ([section 10.2](https://una-lang.org/en/learn/collections/functions-as-values-and-lambdas/#s10-2)), so a later assignment outside it does not reach it either.

### 16.1.4.4 No `+=` and no `while`

There are no compound assignments such as `+=`: write `points = points + 30`. And there is no `while` loop: a `for` loop, or **recursion**, a function that calls itself, does the repeating ([section 9.1](https://una-lang.org/en/learn/loops/for-over-ranges-and-texts/#s9-1) covers both).

### 16.1.4.5 What a copy means when the program runs

> [!NOTE] A copy is a rule about results.
> The rules of this section say what a program computes: each binding has its own value. They do not say how una lays out the memory. The specification lets una share a value's memory between bindings and update a value in place when nothing else holds it. None of this is observable: the output is always the output of the copies.

## 16.1.5 `let` or `let edit`

:::decide
**Which to use:**

| You want… | Use |
| --- | --- |
| A name for a value that never changes | `let` |
| A running total, a list built step by step, or a record updated field by field | `let edit` |
| The value a binding had at some point, kept while it changes | A plain `let` copy, as `snapshot` |
| To change one element of a list | `let edit` for the list, then `edit list.set(index: …, item: …)` |
:::

Prefer `let`. A reader who sees `let` knows the value never changes; `let edit` asks them to follow every assignment.

## 16.1.6 Check yourself: copies

`markdown` builds a price tag, keeps the original price, and then lowers the price:

```una include="steps/02-places/src/places.una#markdown" title="steps/02-places/src/places.una"
--- The price on a tag, before and after a markdown of 500 cents.
markdown() -> Text
=
  let edit price = 1990
  let tag = "LAMP-01 at {price}"
  let original = price
  price = price - 500
  "{tag}; was {original}; now {price}"
```

What does `markdown()` return? Decide what `tag` holds before you open the answer.

:::answer Show the answer
```text include="steps/02-places/expected/output.txt#L4"
LAMP-01 at 1990; was 1990; now 1490
```

`tag` was made from `price` when `price` was 1990, and a text holds its characters, not a link to `price`. `original` is a copy of 1990. Only `price` changes, to 1490.
:::
