---
title: "16.3 Giving a value up: take"
url: https://una-lang.org/en/learn/memory/giving-a-value-up-take/
release: v0.4.0
edition: "0.2"
---

# 16.3 Giving a value up: take

## 16.3.1 What `take` is

At the till, a customer hands over a gift voucher. The clerk keeps it, and the customer no longer has it: they cannot hand the same voucher over again. A **`take`** parameter is that hand-over. The function receives the argument for good, and after the call the caller's binding is **taken**: no line may use it until it is given a new value.

## 16.3.2 Why some values must not be used again

A cart that has been checked out should not take more items, or the order and the cart disagree. Here `checkout` takes a plain parameter, so the caller keeps the cart, and adds to it after the order was made:

```una include="steps/08-no-take/src/checkout.una#checkout..main" title="steps/08-no-take/src/checkout.una"
--- Turns the cart into an order. The caller keeps the cart, and can still add to it.
checkout(cart: Cart, number: Int) -> Order = Order(number: number, customer: cart.customer, lines: cart.skus.len, cents: cart.cents)

pub main() -> Unit
  uses @console: Console[print]
=
  let edit cart = Cart(customer: "C-1042", skus: [], cents: 0)
  edit cart.add(sku: "LAMP-01", cents: 1990)
  edit cart.add(sku: "DESK-02", cents: 12900)
  let order = checkout(cart, number: 1001)
  edit cart.add(sku: "RUG-07", cents: 4500)
  @console.print("order {order.number}: {order.lines} lines, {order.cents} cents")
  @console.print("the cart: {cart.skus.len} lines, {cart.cents} cents")
```

```text include="steps/08-no-take/expected/output.txt"
order 1001: 2 lines, 14890 cents
the cart: 3 lines, 19390 cents
```

The customer sees three items in the cart, and the order has two. The rug was never ordered, and nothing says so. A comment that says "do not use the cart after checkout" is easy to miss. `take` makes it a rule the checker enforces.

## 16.3.3 How to write `take`

This step redeems gift vouchers, which can each be used once:

```una include="steps/09-take-forms/src/vouchers.una" title="steps/09-take-forms/src/vouchers.una" verified="check, run"
module vouchers

--- A gift voucher: a code and what it takes off an order, in cents.
kind Voucher
  code: Text
  cents: Int

--- Redeems a voucher. It takes the voucher, so the same voucher cannot be redeemed twice.
redeem(take voucher: Voucher) -> Int = voucher.cents

--- Redeems a voucher and says so. It takes its parameter, and passes it on with `take`.
redeem_text(take voucher: Voucher) -> Text
=
  let code = voucher.code
  let cents = redeem(take voucher)
  "{code}: {cents} off"

--- Redeems one voucher for each code: each turn makes its own voucher and takes it.
redeem_codes(codes: List[Text]) -> Int
=
  let edit total = 0
  for code in codes
    let voucher = Voucher(code: code, cents: 200)
    let cents = redeem(take voucher)
    total = total + cents
  total

pub main() -> Unit
  uses @console: Console[print]
=
  let gift = Voucher(code: "GIFT-10", cents: 1000)
  let first = redeem(take gift)
  @console.print("first: {first} off")
  let edit spare = Voucher(code: "SPRING-5", cents: 500)
  let second = redeem(take spare)
  spare = Voucher(code: "SUMMER-5", cents: 500)
  let third = redeem_text(take spare)
  @console.print("second: {second} off, then {third}")
  let codes = ["A-1", "A-2", "A-3"]
  @console.print("three codes: {redeem_codes(codes)} off")
```

```text include="steps/09-take-forms/expected/output.txt"
first: 1000 off
second: 500 off, then SUMMER-5: 500 off
three codes: 600 off
```

### 16.3.3.1 The `take` parameter and the call

`redeem(take voucher: Voucher)` declares the parameter with `take`, and the call writes `take` before the argument: `redeem(take gift)`. The argument is a binding, never a field: `redeem(take order.voucher)` is U2020.

### 16.3.3.2 Any local binding can be taken

A plain `let` (`gift`), a `let edit` (`spare`) and a parameter can each be taken. `redeem_text` takes its own parameter and passes it on to `redeem` with `take`, after reading the code it needs.

### 16.3.3.3 A new value revives a binding

`spare = Voucher(…)` gives a taken `let edit` binding a new value, and it can be used again: `redeem_text(take spare)` redeems the new voucher. A plain `let` binding cannot be assigned, so once taken, it stays taken.

### 16.3.3.4 A binding declared inside a loop

`redeem_codes` makes a new voucher at each turn of its loop, and takes it in the same turn. Each turn has its own `voucher`, so nothing is taken twice.

## 16.3.4 Checking out a cart

Back to the cart, with `take`:

:::steps
```una include="steps/10-take/src/checkout.una" title="steps/10-take/src/checkout.una" verified="check, run"
module checkout

--- A customer's cart: the SKUs in it and their total in cents.
kind Cart
  customer: Text
  skus: List[Text]
  cents: Int

--- An order, made from a cart at checkout.
kind Order
  number: Int
  customer: Text
  lines: Int
  cents: Int

--- Puts one unit of `sku` in the cart.
add(edit cart: Cart, sku: Text, cents: Int) -> Unit
  ensures cart.skus.len == old(cart).skus.len + 1
=
  cart.skus = cart.skus.append(item: sku)
  cart.cents = cart.cents + cents

--- Turns the cart into an order. It takes the cart, so nothing can add to it afterwards.
checkout(take cart: Cart, number: Int) -> Order = Order(number: number, customer: cart.customer, lines: cart.skus.len, cents: cart.cents)

pub main() -> Unit
  uses @console: Console[print]
=
  let edit cart = Cart(customer: "C-1042", skus: [], cents: 0)
  edit cart.add(sku: "LAMP-01", cents: 1990)
  edit cart.add(sku: "DESK-02", cents: 12900)
  let order = checkout(take cart, number: 1001)
  cart = Cart(customer: "C-1042", skus: [], cents: 0)
  @console.print("order {order.number}: {order.lines} lines, {order.cents} cents")
  @console.print("the new cart has {cart.skus.len} lines")
```

1. **`add(edit cart: Cart, sku: Text, cents: Int)`.** Adding to the cart changes it, so the cart is an `edit` parameter. Its `ensures` promises one more SKU.
2. **`checkout(take cart: Cart, number: Int) -> Order`.** The cart goes in and an order comes out. `take` states that the cart is used up.
3. **`let order = checkout(take cart, number: 1001)`.** The call writes `take`, as `edit` is written for an `edit` parameter. From here on, `cart` is taken.
4. **`cart = Cart(…)`.** The customer starts a new cart: an assignment revives the binding.
:::

`una run .` prints:

```text include="steps/10-take/expected/output.txt"
order 1001: 2 lines, 14890 cents
the new cart has 0 lines
```

Adding the rug to the old cart after the checkout is now U2017, at the line that uses it. [Using a value after `take`](https://una-lang.org/en/learn/memory/common-mistakes/#using-a-value-after-take-u2017) shows the diagnostic.

## 16.3.5 How the checker follows a taken binding

### 16.3.5.1 After an `if` or a `when`

A binding taken in one branch of an `if` or a `when` counts as taken after it, since the checker cannot know which branch ran. Redeem the gift voucher only on a large order, and print its code afterwards:

```diff include="steps/09-take-forms..steps/11-taken-branch:src/vouchers.una" context="0" title="src/vouchers.una"
--- a/src/vouchers.una
+++ b/src/vouchers.una
@@ -32,2 +32,5 @@
-  let first = redeem(take gift)
-  @console.print("first: {first} off")
+  let order_cents = 4500
+  let edit first = 0
+  if order_cents >= 3000
+    first = redeem(take gift)
+  @console.print("first: {first} off, with {gift.code}")
```

```text include="steps/11-taken-branch/expected/rendered.txt"
[U2017] Error: `gift` was passed by `take`, so it cannot be used afterwards
    ╭─[ src/vouchers.una:36:45 ]
    │
 35 │     first = redeem(take gift)
    │                         ──┬─
    │                           ╰─── passed by `take` here
 36 │   @console.print("first: {first} off, with {gift.code}")
    │                                             ──┬─
    │                                               ╰─── `gift` was passed by `take`, so it cannot be used afterwards
    │
    │ Note: run `una explain U2017` for an explanation
────╯
```

The first mark is where the binding was taken, and the second where it is used. Read `gift.code` into a binding of its own before the `if`, and print that.

### 16.3.5.2 In a loop

A binding taken in a loop body is taken in every turn after the first. So a binding taken in a loop body must get a new value before the body ends, or be declared inside it, as in `redeem_codes`.

### 16.3.5.3 What `take` means at run time

`take` also tells the backend, the part of una that runs the program, the interpreter or an executable ([section 15.3](https://una-lang.org/en/learn/concurrency/what-the-result-can-depend-on-failures-and-order/#s15-3)), that the value is not needed after the call, so it can reuse the value's memory. The program behaves the same either way: `take` is checked before the program runs, and leaves no trace in what it computes. A plain argument that nothing reads after the call can be given up the same way, so choose `take` for the rule it enforces, not for speed.

## 16.3.6 Choosing between a plain parameter, `edit` and `take`

Three ways compete for a function that turns one value into another:

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

| You want… | Use |
| --- | --- |
| A new value, and the caller keeps the old one | A plain parameter, and return the new value |
| To change the caller's value, with the change visible at the call | An `edit` parameter |
| To use the value up, so that nothing can use it afterwards | A `take` parameter |
| To change a value only when the whole update succeeds | An `edit` parameter and `fails`: a failure leaves the argument as it was |
:::

## 16.3.7 Check yourself: taking in a loop

This version of `redeem_codes` makes one voucher before the loop:

```diff include="steps/09-take-forms..steps/12-taken-loop:src/vouchers.una" context="1" title="src/vouchers.una"
--- a/src/vouchers.una
+++ b/src/vouchers.una
@@ -17,8 +17,8 @@
 
---- Redeems one voucher for each code: each turn makes its own voucher and takes it.
+--- Redeems a voucher for each code.
 redeem_codes(codes: List[Text]) -> Int
 =
+  let voucher = Voucher(code: "A-1", cents: 200)
   let edit total = 0
   for code in codes
-    let voucher = Voucher(code: code, cents: 200)
     let cents = redeem(take voucher)
```

Does it check? If not, which line does `una check .` point at?

:::answer Show the answer
It does not:

```text include="steps/12-taken-loop/expected/rendered.txt"
[U2017] Error: `voucher` is taken in every iteration of this loop; give it a new value before the end of the body, or declare it inside the loop
    ╭─[ src/vouchers.una:24:29 ]
    │
 24 │     let cents = redeem(take voucher)
    │                             ───┬───
    │                                ╰───── `voucher` is taken in every iteration of this loop; give it a new value before the end of the body, or declare it inside the loop
    │
    │ Note: run `una explain U2017` for an explanation
────╯
```

The first turn takes `voucher`, and the second would use it again. The message gives both fixes: assign it a new value before the end of the body, or declare it inside the loop, as the original does.
:::
