Home / Learn / 6 Functions and their results

Release v0.4.0Edition 0.2

6.4 Day-to-day: shipping quotes

Page 5 of 9

6.4.1 What the program must do

Every order needs a shipping charge before it can be paid. The charge depends on the parcel's weight and on how far it travels, large orders within the country ship for free, and this weekend one order gets half off its shipping. The report at the end of the day lists the charge of each order.

Each rule is a function, and each function's header states what its callers may rely on. The program is one module, shipping, and each part uses one idea of this chapter:

6.4.2 The kinds: zones, parcels and orders

day-to-day/src/shipping.unathe kindsuna
--- How far a parcel travels: within the country, to a neighboring country, or farther.
kind Zone = Home | Neighbor | World

--- A parcel: its weight in grams and the zone it ships to.
kind Parcel
  grams: Int
  zone: Zone

--- An order of the day: its number, the price of its goods in cents, and its parcel.
kind Order
  number: Int
  goods: Int
  parcel: Parcel

Zone is a sum kind (section 4.2): a parcel ships within the country, to a neighboring country, or farther. A Parcel is a record of its weight and its zone, and an Order holds its number, the price of its goods in cents, and its parcel. With these kinds, a function about an order takes one argument, the order, and reads what it needs from it.

6.4.3 The rates

day-to-day/src/shipping.unathe ratesuna
--- The rate for `grams` grams within the country, in cents: 790 up to 2 kg, and 250 more
--- for each kilogram or part of one above 2 kg.
pub base_rate(grams: Int) -> Int
  requires grams > 0
  ensures result >= 790
=
  let extra_kilos = (grams - 2_000 + 999) / 1_000
  if grams <= 2_000 then 790 else 790 + extra_kilos * 250

--- What a zone adds to the rate, in cents.
pub surcharge(zone: Zone) -> Int
  ensures result >= 0
=
  when zone
    is Home -> 0
    is Neighbor -> 600
    is World -> 1_800

--- The rate of a parcel: the rate for its weight, and the surcharge of its zone.
pub rate(parcel: Parcel) -> Int
  requires parcel.grams > 0
  ensures result >= 790
=
  base_rate(parcel.grams) + parcel.zone.surcharge

base_rate gives the rate for a weight: 790 cents up to 2 kg, and 250 more for each kilogram or part of one above that. Its first line names extra_kilos, the started kilograms above 2 kg, and its last line, a one-line if, is the result. requires grams > 0 rules out an empty parcel, and ensures result >= 790 promises the lowest rate to every caller.

surcharge takes a zone apart with when (section 4.3), one arm per zone. Its ensures result >= 0 looks obvious from the body, and it matters all the same: the callers of surcharge see its header, not its body.

rate puts the two together for a parcel. Its last line calls base_rate with a plain call, and surcharge with method syntax: parcel.zone.surcharge reads the zone of the parcel, then its surcharge. The verifier proves rate's promise from the headers alone: at least 790 from base_rate, and at least 0 from surcharge. It also proves the precondition of base_rate at the call, from rate's own requires parcel.grams > 0.

6.4.4 The quote

day-to-day/src/shipping.unathe quoteuna
--- Whether an order ships free: 10000 cents of goods or more, within the country.
pub ships_free(order: Order) -> Bool = order.goods >= 10_000 and order.parcel.zone is Home

--- What shipping costs for an order, in cents.
pub quote(order: Order) -> Int
  requires order.parcel.grams > 0
  ensures result >= 0
=
  if order.ships_free then 0 else order.parcel.rate

ships_free answers a question about an order with a Bool: 10000 cents of goods or more, and a parcel that stays in the country. The is test of section 4.2 checks the zone.

quote reads as the rule itself: if the order ships free, nothing, else the rate of its parcel. Both calls are method calls, order.ships_free and order.parcel.rate. Its requires passes the weight rule on to its own callers, and its ensures result >= 0 follows from rate's promise: 0 when the order ships free, at least 790 otherwise.

6.4.5 The weekend offer

day-to-day/src/shipping.unathe offeruna
--- The weekend offer: half the charge, rounded up to a whole cent. It never raises the charge.
pub weekend_price(charge: Int) -> Int
  requires charge >= 0
  ensures result >= 0 and result <= charge
=
  (charge + 1) / 2

weekend_price halves a charge, rounding up to a whole cent: adding 1 before dividing by 2 rounds a half cent up. Its header promises two facts: the price is never negative, and never more than the charge. The verifier proves both for every charge that is not negative, the only charges a quote gives.

6.4.6 The report

day-to-day/src/shipping.unathe reportcheckrununa
--- Cents as an amount with two decimals, for an amount that is not negative.
pub money(cents: Int) -> Text = "{cents / 100}.{cents mod 100 / 10}{cents mod 10}"

--- The line of the report for one order.
pub report_line(order: Order, charge: Int) -> Text = if charge == 0 then "order {order.number}: ships free" else "order {order.number}: {money(charge)}"

--- Prints one line of the report.
show(order: Order, charge: Int) -> Unit
  uses @console: Console[print]
=
  @console.print(report_line(order, charge))

--- Prints the shipping report of the orders of the day.
pub main() -> Unit
  uses @console: Console[print]
=
  let lamp = Order(number: 1042, goods: 3_980, parcel: Parcel(grams: 1_200, zone: Home))
  show(lamp, charge: lamp.quote)
  let desk = Order(number: 1043, goods: 15_900, parcel: Parcel(grams: 24_000, zone: Home))
  show(desk, charge: desk.quote)
  let rug = Order(number: 1044, goods: 4_500, parcel: Parcel(grams: 3_200, zone: World))
  show(rug, charge: rug.quote)
  let chair = Order(number: 1045, goods: 4_500, parcel: Parcel(grams: 3_200, zone: World))
  show(chair, charge: weekend_price(chair.quote))
  let mugs = Order(number: 1046, goods: 2_500, parcel: Parcel(grams: 800, zone: Neighbor))
  show(mugs, charge: mugs.quote)

money writes cents as an amount with two decimals, and report_line chooses the text of one line with a one-line if. Both are pure, so examples can check them. show prints one line, and is private. main builds five orders and prints a line for each.

Every call in main that prints stands on a line of its own, and every argument only computes: lamp.quote and weekend_price(chair.quote) are evaluated before show runs. weekend_price(chair.quote) checks because of a header: weekend_price requires a charge that is not negative, and the verifier knows that chair.quote is not negative from quote's ensures. The promise of one function is what makes the call of the next one safe.

6.4.7 Running it

In the day-to-day directory:

sh
una check .
una run .

una check . prints nothing, and una run . prints the report shown in What you'll build. Order 1044 ships 3200 g abroad: 790 for the first 2 kg, 500 for two started kilograms above them, and 1800 for the zone, 30.90 in all. Order 1045 is the same parcel on the weekend: half of 3090, 15.45.

una contract shipping.quote prints the header that every caller of quote relies on, with its doc comment:

Output
--- What shipping costs for an order, in cents.
pub quote(order: Order) -> Int
  requires order.parcel.grams > 0
  ensures result >= 0

Security

Of the ten functions in the file, only show and main touch the console, and both say so in their headers. Every other function has no uses line, so it cannot have an effect of any kind: a change to a rate cannot start printing, writing files or sending data without a change to its header that a reviewer sees.

6.4.8 The whole program

The whole file, to read in one piece or to copy:

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

-- Shipping quotes: what each order of the day costs to ship, by weight and zone.

--- How far a parcel travels: within the country, to a neighboring country, or farther.
kind Zone = Home | Neighbor | World

--- A parcel: its weight in grams and the zone it ships to.
kind Parcel
  grams: Int
  zone: Zone

--- An order of the day: its number, the price of its goods in cents, and its parcel.
kind Order
  number: Int
  goods: Int
  parcel: Parcel

--- The rate for `grams` grams within the country, in cents: 790 up to 2 kg, and 250 more
--- for each kilogram or part of one above 2 kg.
pub base_rate(grams: Int) -> Int
  requires grams > 0
  ensures result >= 790
=
  let extra_kilos = (grams - 2_000 + 999) / 1_000
  if grams <= 2_000 then 790 else 790 + extra_kilos * 250

--- What a zone adds to the rate, in cents.
pub surcharge(zone: Zone) -> Int
  ensures result >= 0
=
  when zone
    is Home -> 0
    is Neighbor -> 600
    is World -> 1_800

--- The rate of a parcel: the rate for its weight, and the surcharge of its zone.
pub rate(parcel: Parcel) -> Int
  requires parcel.grams > 0
  ensures result >= 790
=
  base_rate(parcel.grams) + parcel.zone.surcharge

--- Whether an order ships free: 10000 cents of goods or more, within the country.
pub ships_free(order: Order) -> Bool = order.goods >= 10_000 and order.parcel.zone is Home

--- What shipping costs for an order, in cents.
pub quote(order: Order) -> Int
  requires order.parcel.grams > 0
  ensures result >= 0
=
  if order.ships_free then 0 else order.parcel.rate

--- The weekend offer: half the charge, rounded up to a whole cent. It never raises the charge.
pub weekend_price(charge: Int) -> Int
  requires charge >= 0
  ensures result >= 0 and result <= charge
=
  (charge + 1) / 2

--- Cents as an amount with two decimals, for an amount that is not negative.
pub money(cents: Int) -> Text = "{cents / 100}.{cents mod 100 / 10}{cents mod 10}"

--- The line of the report for one order.
pub report_line(order: Order, charge: Int) -> Text = if charge == 0 then "order {order.number}: ships free" else "order {order.number}: {money(charge)}"

--- Prints one line of the report.
show(order: Order, charge: Int) -> Unit
  uses @console: Console[print]
=
  @console.print(report_line(order, charge))

--- Prints the shipping report of the orders of the day.
pub main() -> Unit
  uses @console: Console[print]
=
  let lamp = Order(number: 1042, goods: 3_980, parcel: Parcel(grams: 1_200, zone: Home))
  show(lamp, charge: lamp.quote)
  let desk = Order(number: 1043, goods: 15_900, parcel: Parcel(grams: 24_000, zone: Home))
  show(desk, charge: desk.quote)
  let rug = Order(number: 1044, goods: 4_500, parcel: Parcel(grams: 3_200, zone: World))
  show(rug, charge: rug.quote)
  let chair = Order(number: 1045, goods: 4_500, parcel: Parcel(grams: 3_200, zone: World))
  show(chair, charge: weekend_price(chair.quote))
  let mugs = Order(number: 1046, goods: 2_500, parcel: Parcel(grams: 800, zone: Neighbor))
  show(mugs, charge: mugs.quote)

example "a parcel up to 2 kg ships at the lowest rate"
  do base_rate(2_000)
  expect result == 790

example "each started kilogram above 2 kg adds 250 cents"
  do base_rate(3_200)
  expect result == 1_290

example "the rest of the world adds 1800 cents"
  do surcharge(World)
  expect result == 1_800

example "a large order within the country ships free"
  do quote(Order(number: 1, goods: 15_900, parcel: Parcel(grams: 24_000, zone: Home)))
  expect result == 0

example "a large order abroad pays shipping"
  do quote(Order(number: 2, goods: 15_900, parcel: Parcel(grams: 24_000, zone: Neighbor)))
  expect result == 6_890

example "the weekend offer rounds up to a whole cent"
  do weekend_price(3_091)
  expect result == 1_546

example "the weekend offer of nothing is nothing"
  do weekend_price(0)
  expect result == 0

example "an amount keeps its zero cents"
  do money(705)
  expect result == "7.05"

example "a free order says so"
  do report_line(Order(number: 1043, goods: 15_900, parcel: Parcel(grams: 24_000, zone: Home)), charge: 0)
  expect result == "order 1043: ships free"

Next:6.5 Testing it