Home / Learn / 9 Repeating: for

Release v0.4.0Edition 0.2

9.4 Day-to-day: a weekly restock plan

Page 5 of 9

9.4.1 What the program must do

Every week, a store sells some units of each product, and when a shelf runs low, it orders more. A restock plan looks ahead: for the next weeks, it follows the stock of each product and shows when to order. For each product, the plan knows:

For each week, the plan prints the units left after the week's sales and the order, if any. For each product, it ends with the units ordered and the number of weeks that started with too few units for the week's sales. The program is one module, restock, in a package whose una.toml names it as the entry and grants the console:

day-to-day/una.tomltoml
[package]
name = "restock"
version = "0.1.0"
edition = "0.2"

[run]
entry = "restock"
grants = ["console"]

9.4.2 The kinds and the products

day-to-day/src/restock.unathe kinds and the productscheckuna
--- A number of units. It is never negative.
kind Units = Int where it >= 0

--- What the plan knows about one product: its stock today, how many units sell in a week,
--- the stock below which the store orders more, and how many units one order brings.
kind Product
  sku: Text
  on_hand: Units
  weekly_sales: Units
  reorder_at: Units
  batch: Units

--- The desk lamp, which sells fast.
pub lamp() -> Product = Product(sku: "LAMP-01", on_hand: 14, weekly_sales: 5, reorder_at: 6, batch: 10)

--- The wool rug, which sells slowly.
pub rug() -> Product = Product(sku: "RUG-07", on_hand: 3, weekly_sales: 2, reorder_at: 2, batch: 4)

--- The oak desk, whose orders are too small for its sales.
pub desk() -> Product = Product(sku: "DESK-02", on_hand: 2, weekly_sales: 3, reorder_at: 3, batch: 2)

Units is a refined kind: a number of units is never negative. Every number of Product is a Units, so a product with a negative stock cannot be built. The three products are functions that give back a record, so that main and the examples share them. The desk is set up to show a problem: it sells 3 a week, and an order brings only 2.

9.4.3 The department of a SKU: a loop over characters

The plan prints each product's department, the part of its SKU before the first dash:

day-to-day/src/restock.unacheckuna
--- The department of a SKU: its characters before the first dash, such as `LAMP` for
--- `LAMP-01`.
pub department(sku: Text) -> Text
=
  let edit code = ""
  let edit past_dash = false
  for character in sku.chars()
    if character == "-"
      past_dash = true
    if not past_dash
      code = "{code}{character}"
  code

Two accumulators work together. code is a text that grows, and past_dash is a flag. Each turn first looks at its character: a dash sets the flag. Then, while the flag is still false, the character joins the code. The dash itself is not added, since the flag is already set when the second if reads it. A SKU without a dash, such as GIFTCARD, never sets the flag, so the whole SKU is its department.

9.4.4 One week: selling and ordering

Two small functions say what one week does:

day-to-day/src/restock.unacheckuna
--- The stock after one week of sales. A shelf cannot sell more than it holds.
pub sell_week(stock: Units, sales: Units) -> Units = if stock >= sales then stock - sales else 0

--- The units to order at the end of a week: a batch when the stock is below the reorder
--- point, and nothing otherwise.
pub order_for(product: Product, stock: Units) -> Units
=
  if stock < product.reorder_at
    product.batch
  else
    0

sell_week is the guard of Each assignment is proved, made a function of its own: a shelf cannot sell more than it holds, so the result is never below 0 and is a Units. order_for gives a batch when the stock is below the reorder point, and 0 otherwise. Neither has a loop: each is one step, which the loops call and the examples test on its own.

9.4.5 The plan: loops over the weeks

Three functions walk the weeks, each for one result:

day-to-day/src/restock.unathree loops over the weekscheckuna
--- The stock at the end of `weeks` weeks. Each week sells, then the week's order arrives.
pub stock_after(product: Product, weeks: Int) -> Units
=
  let edit stock: Units = product.on_hand
  for week in 1..weeks
    stock = sell_week(stock, sales: product.weekly_sales)
    stock = stock + order_for(product, stock: stock)
  stock

--- The units ordered over `weeks` weeks.
pub units_ordered(product: Product, weeks: Int) -> Units
=
  let edit stock: Units = product.on_hand
  let edit ordered: Units = 0
  for week in 1..weeks
    stock = sell_week(stock, sales: product.weekly_sales)
    let order = order_for(product, stock: stock)
    stock = stock + order
    ordered = ordered + order
  ordered

--- How many of the `weeks` weeks start with too few units for the week's sales.
pub weeks_short(product: Product, weeks: Int) -> Int
=
  let edit stock: Units = product.on_hand
  let edit short = 0
  for week in 1..weeks
    if stock < product.weekly_sales
      short = short + 1
    stock = sell_week(stock, sales: product.weekly_sales)
    stock = stock + order_for(product, stock: stock)
  short

Each has the same accumulator: let edit stock: Units = product.on_hand, the stock today, which each turn sells from and then restocks. The type Units is what lets the verifier prove each function's result. In stock_after, the result is stock, a Units at every turn. In units_ordered, a second accumulator, ordered, adds each week's order, and it is a Units too: without that type, the loop would forget that it is never negative, as An accumulator without its refined type shows.

Each turn uses sell_week and order_for rather than writing their steps again, so the rule for one week lives in one place. units_ordered names the week's order with a let in the body, new at each turn, because it uses it twice. weeks_short counts with a plain Int, since its result is a plain Int and needs no fact. Its if looks at the stock before the week's sales.

None of the three uses the loop variable week: each turn is one week, and only the number of turns matters. With 0 weeks, each loop runs no turn and gives back its first value.

9.4.6 Printing the plan

day-to-day/src/restock.unathe functions that printcheckrununa
--- One line of the plan: the week, the units left after its sales, and its order, if any.
pub plan_line(week: Int, left: Units, order: Units) -> Text
=
  if order > 0
    "  week {week}: {left} left, order {order}"
  else
    "  week {week}: {left} left"

--- Prints the plan of one product, week by week, then its totals.
print_plan(product: Product, weeks: Int) -> Unit
  uses @console: Console[print]
=
  @console.print("{product.sku}, {department(product.sku)}")
  let edit stock: Units = product.on_hand
  for week in 1..weeks
    stock = sell_week(stock, sales: product.weekly_sales)
    let order = order_for(product, stock: stock)
    @console.print(plan_line(week, left: stock, order: order))
    stock = stock + order
  let ordered = units_ordered(product, weeks: weeks)
  let short = weeks_short(product, weeks: weeks)
  @console.print("  {ordered} units ordered, {short} weeks short")

--- Prints the restock plan of the next four weeks.
pub main() -> Unit
  uses @console: Console[print]
=
  let weeks = 4
  @console.print("Restock plan, {weeks} weeks")
  print_plan(lamp(), weeks: weeks)
  print_plan(rug(), weeks: weeks)
  print_plan(desk(), weeks: weeks)

plan_line builds the text of one week, with the order only when there is one. print_plan walks the weeks once more, with the same accumulator, and prints a line at each turn: the week's number, from the loop variable, the units left and the order. After the loop, it prints the totals, which units_ordered and weeks_short compute. main sets the number of weeks once, in weeks, and plans each product.

9.4.7 Running it

In the day-to-day directory:

sh
una check .
una run .

una check . prints nothing, and una run . prints the plan:

Output
Restock plan, 4 weeks
LAMP-01, LAMP
  week 1: 9 left
  week 2: 4 left, order 10
  week 3: 9 left
  week 4: 4 left, order 10
  20 units ordered, 0 weeks short
RUG-07, RUG
  week 1: 1 left, order 4
  week 2: 3 left
  week 3: 1 left, order 4
  week 4: 3 left
  8 units ordered, 0 weeks short
DESK-02, DESK
  week 1: 0 left, order 2
  week 2: 0 left, order 2
  week 3: 0 left, order 2
  week 4: 0 left, order 2
  8 units ordered, 4 weeks short

Read the lamp's plan: 14 units, minus 5, leave 9, which is not below 6, so no order. The next week leaves 4, below 6, so the store orders 10, and the third week starts with 14 again. The desk's plan shows the problem it was set up for: it starts every week with 2 units, fewer than the 3 it sells, so it is short all 4 weeks. A larger batch fixes it.

9.4.8 The whole program

day-to-day/src/restock.unathe whole programcheckruntestuna
module restock

-- The weekly restock plan of the store: for each product, the stock at the end of each week,
-- and the orders that keep its shelf from running empty.

--- A number of units. It is never negative.
kind Units = Int where it >= 0

--- What the plan knows about one product: its stock today, how many units sell in a week,
--- the stock below which the store orders more, and how many units one order brings.
kind Product
  sku: Text
  on_hand: Units
  weekly_sales: Units
  reorder_at: Units
  batch: Units

--- The desk lamp, which sells fast.
pub lamp() -> Product = Product(sku: "LAMP-01", on_hand: 14, weekly_sales: 5, reorder_at: 6, batch: 10)

--- The wool rug, which sells slowly.
pub rug() -> Product = Product(sku: "RUG-07", on_hand: 3, weekly_sales: 2, reorder_at: 2, batch: 4)

--- The oak desk, whose orders are too small for its sales.
pub desk() -> Product = Product(sku: "DESK-02", on_hand: 2, weekly_sales: 3, reorder_at: 3, batch: 2)

--- The department of a SKU: its characters before the first dash, such as `LAMP` for
--- `LAMP-01`.
pub department(sku: Text) -> Text
=
  let edit code = ""
  let edit past_dash = false
  for character in sku.chars()
    if character == "-"
      past_dash = true
    if not past_dash
      code = "{code}{character}"
  code

--- The stock after one week of sales. A shelf cannot sell more than it holds.
pub sell_week(stock: Units, sales: Units) -> Units = if stock >= sales then stock - sales else 0

--- The units to order at the end of a week: a batch when the stock is below the reorder
--- point, and nothing otherwise.
pub order_for(product: Product, stock: Units) -> Units
=
  if stock < product.reorder_at
    product.batch
  else
    0

--- The stock at the end of `weeks` weeks. Each week sells, then the week's order arrives.
pub stock_after(product: Product, weeks: Int) -> Units
=
  let edit stock: Units = product.on_hand
  for week in 1..weeks
    stock = sell_week(stock, sales: product.weekly_sales)
    stock = stock + order_for(product, stock: stock)
  stock

--- The units ordered over `weeks` weeks.
pub units_ordered(product: Product, weeks: Int) -> Units
=
  let edit stock: Units = product.on_hand
  let edit ordered: Units = 0
  for week in 1..weeks
    stock = sell_week(stock, sales: product.weekly_sales)
    let order = order_for(product, stock: stock)
    stock = stock + order
    ordered = ordered + order
  ordered

--- How many of the `weeks` weeks start with too few units for the week's sales.
pub weeks_short(product: Product, weeks: Int) -> Int
=
  let edit stock: Units = product.on_hand
  let edit short = 0
  for week in 1..weeks
    if stock < product.weekly_sales
      short = short + 1
    stock = sell_week(stock, sales: product.weekly_sales)
    stock = stock + order_for(product, stock: stock)
  short

--- One line of the plan: the week, the units left after its sales, and its order, if any.
pub plan_line(week: Int, left: Units, order: Units) -> Text
=
  if order > 0
    "  week {week}: {left} left, order {order}"
  else
    "  week {week}: {left} left"

--- Prints the plan of one product, week by week, then its totals.
print_plan(product: Product, weeks: Int) -> Unit
  uses @console: Console[print]
=
  @console.print("{product.sku}, {department(product.sku)}")
  let edit stock: Units = product.on_hand
  for week in 1..weeks
    stock = sell_week(stock, sales: product.weekly_sales)
    let order = order_for(product, stock: stock)
    @console.print(plan_line(week, left: stock, order: order))
    stock = stock + order
  let ordered = units_ordered(product, weeks: weeks)
  let short = weeks_short(product, weeks: weeks)
  @console.print("  {ordered} units ordered, {short} weeks short")

--- Prints the restock plan of the next four weeks.
pub main() -> Unit
  uses @console: Console[print]
=
  let weeks = 4
  @console.print("Restock plan, {weeks} weeks")
  print_plan(lamp(), weeks: weeks)
  print_plan(rug(), weeks: weeks)
  print_plan(desk(), weeks: weeks)

example "a department is the part of the SKU before its dash"
  do department("LAMP-01")
  expect result == "LAMP"

example "a SKU without a dash is its own department"
  do department("GIFTCARD")
  expect result == "GIFTCARD"

example "a week sells its sales from the stock"
  do sell_week(9, sales: 5)
  expect result == 4

example "a shelf cannot sell more than it holds"
  do sell_week(3, sales: 5)
  expect result == 0

example "a stock below the reorder point orders a batch"
  do order_for(lamp(), stock: 4)
  expect result == 10

example "a stock at the reorder point orders nothing"
  do order_for(lamp(), stock: 6)
  expect result == 0

example "a plan of no weeks leaves the stock as it is"
  do stock_after(lamp(), weeks: 0)
  expect result == 14

example "the lamp ends four weeks with 14 units"
  do stock_after(lamp(), weeks: 4)
  expect result == 14

example "the lamp orders two batches in four weeks"
  do units_ordered(lamp(), weeks: 4)
  expect result == 20

example "the lamp is never short"
  do weeks_short(lamp(), weeks: 4)
  expect result == 0

example "the desk is short every week"
  do weeks_short(desk(), weeks: 4)
  expect result == 4

example "a week with an order says how many units"
  do plan_line(2, left: 4, order: 10)
  expect result == "  week 2: 4 left, order 10"

Next:9.5 Testing it