Home / Learn / 16 Memory

Release v0.4.0Edition 0.2

16.3 Giving a value up: take

Page 4 of 10

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:

steps/08-no-take/src/checkout.unauna
--- 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")
Output
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:

steps/09-take-forms/src/vouchers.unacheckrununa
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")
Output
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/10-take/src/checkout.unacheckrununa
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:

Output
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 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:

src/vouchers.unadiff
--- 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}")
Diagnostic
[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), 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:

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:

src/vouchers.unadiff
--- 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?

Show the answer

It does not:

Diagnostic
[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.

Next:16.4 Limits: call depth and memory