Home / Learn / 16 Memory

Release v0.4.0Edition 0.2

16.1 Values, not references

Page 2 of 10

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) or let edit (section 9.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 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 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/01-values/src/shelf.unacheckrununa
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, 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. set requires an index inside the list, and the verifier proves it here from the list's length.

una run . prints:

Output
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 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, where an edit argument must be a place too. This step shows each form:

steps/02-places/src/places.unathe kindsuna
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
steps/02-places/src/places.unamainuna
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}")
Output
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 changes one element, and since it changes the list it is given, it takes the list as an edit parameter, which section 16.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), 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 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 showed for a number. The rule holds for every place, a field included. Assign a text to points:

src/places.unadiff
--- a/src/places.una
+++ b/src/places.una
@@ -27 +27 @@
-  points = points + 30
+  points = "150 points"
Diagnostic
[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, keeps its condition only when you write the type: let edit total: Cents = 0, as section 9.3 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; Assigning a plain let shows the message). A lambda keeps a copy of each value it captures when it is made (section 10.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 covers both).

16.1.4.5 What a copy means when the program runs

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

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:

steps/02-places/src/places.unauna
--- 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.

Show the answer
Output
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.

Next:16.2 Passing a value in and out: edit