Home / Learn / 3 Text and conditions

Release v0.4.0Edition 0.2

3.2 Working with text: the prelude's functions and method calls

Page 3 of 10

3.2.1 What the prelude's text functions are

Una comes with functions that every module can call without writing them: the prelude. Among them are the functions that work on text: remove the spaces around a text, change its letters to capitals, search it, replace a part of it, or cut a piece out of it. Think of the tools on a workbench that every workshop has: you do not make a ruler or scissors yourself, you pick them up.

You call most of them with a dot after the text, as typed.trim: that is the same call as trim(typed), written so that it reads from left to right. This way of writing a call is method syntax.

3.2.2 Why programs clean and search text

Texts come from people and from other systems, and they are messy. A SKU typed at the till arrives with a stray space and in small letters, and it does not equal the SKU of the catalog:

src/till.unacheckrununa
--- Compares the SKU typed at the till with the SKU of the catalog.
pub main() -> Unit
  uses @console: Console[print]
=
  let typed = " lamp-01"
  let catalog = "LAMP-01"
  @console.print("[{typed}] and [{catalog}]")
  @console.print("the same SKU: {typed == catalog}")
Output
[ lamp-01] and [LAMP-01]
the same SKU: false

The brackets show the space at the front of the typed SKU. To a reader both are the lamp; to == they are different texts. Before a program can compare such a value, it must clean it: remove the spaces around it and write it in one case. Before it can print a long name on a small label, it must cut it. The prelude's functions do this.

3.2.3 How to call a function with a dot

Here the same functions are called in each form a call can take:

src/till.unacheckrununa
module till

--- The SKU as labels print it: without the white space around it, in capital letters.
clean_sku(raw: Text) -> Text = raw.trim.to_upper

--- Calls the same functions in each form a call can take.
pub main() -> Unit
  uses @console: Console[print]
=
  let typed = " lamp-01"
  @console.print("[{trim(typed)}]")
  @console.print("[{typed.trim()}]")
  @console.print("[{typed.trim}]")
  @console.print("[{to_upper(trim(typed))}]")
  @console.print("[{typed.trim.to_upper}]")
  @console.print("[{clean_sku(typed)}] [{typed.clean_sku}]")
  let catalog = "LAMP-01"
  @console.print("the same SKU: {typed.clean_sku == catalog}")
Output
[lamp-01]
[lamp-01]
[lamp-01]
[LAMP-01]
[LAMP-01]
[LAMP-01] [LAMP-01]
the same SKU: true

3.2.3.1 The plain form: trim(typed)

The function's name, then its arguments in parentheses, as in chapter 1. trim takes one text and gives back the text without the spaces around it.

3.2.3.2 Method syntax: typed.trim()

The first argument goes in front, followed by a dot and the function's name; the other arguments, if any, go in the parentheses. typed.trim() is exactly the call trim(typed), and una check treats the two alike.

3.2.3.3 Without parentheses: typed.trim

When the value before the dot is the only argument, you may leave out the empty parentheses. typed.trim is the same call again, and this is how the book writes such calls. The methods of the fixed-width integers must keep their parentheses, as to_int() does in section 2.3. Without them, copies.to_int names the prelude's to_int for texts, and the check refuses it.

3.2.3.4 A chain: typed.trim.to_upper

Calls written with a dot can follow each other. typed.trim.to_upper first trims typed, then writes the result in capital letters. A chain reads in the order the work is done; the plain form, to_upper(trim(typed)), gives the same text, but is read from the inside out.

3.2.3.5 Your own functions: typed.clean_sku

Method syntax works for every function, the ones you write included. clean_sku takes a text, so typed.clean_sku is the call clean_sku(typed). Section 6.1 covers calls in depth.

A call with more arguments keeps their labels inside the parentheses: sku.starts_with(prefix: "LAMP-") is starts_with(sku, prefix: "LAMP-"), with the value before the dot as the first argument.

3.2.4 Trimming: trim, trim_start and trim_end

trim removes the white space, the characters that print as blank space, such as spaces, tabs and new lines, at both ends of a text. trim_start removes it at the start only, and trim_end at the end only:

src/trimming.unacheckrununa
--- Prints what the three trimming functions leave of a few texts.
pub main() -> Unit
  uses @console: Console[print]
=
  let padded = "  oak desk  "
  @console.print("[{padded}]")
  @console.print("[{padded.trim}]")
  @console.print("[{padded.trim_start}]")
  @console.print("[{padded.trim_end}]")
  let typed = "\t RUG-07 \n"
  @console.print("[{typed.trim}]")
  let blank = "   "
  @console.print("[{blank.trim}] has {blank.trim.len} characters")
Output
[  oak desk  ]
[oak desk]
[oak desk  ]
[  oak desk]
[RUG-07]
[] has 0 characters

The space between oak and desk stays: trimming touches the ends only. The tab and the new line around RUG-07 go, as spaces do. A text of spaces alone trims to the empty text, of length 0.

3.2.5 Changing case: to_upper and to_lower

to_upper writes the letters a to z as A to Z, and to_lower does the reverse:

src/case.unacheckrununa
--- Prints texts written in capital and in small letters.
pub main() -> Unit
  uses @console: Console[print]
=
  let typed = "lamp-01"
  @console.print(typed.to_upper)
  let shouted = "WOOL RUG, Natural"
  @console.print(shouted.to_lower)
  let cafe = "Café crème"
  @console.print("{cafe.to_upper}: {cafe.len} characters, then {cafe.to_upper.len}")
Output
LAMP-01
wool rug, natural
CAFé CRèME: 10 characters, then 10

Only the 26 letters of the English alphabet change: é and è stay as they are. The rule is the same on every computer, whatever its language settings, and the length of the text never changes.

3.2.6 Searching: starts_with, ends_with, contains_text and is_digits

These four answer a question about a text, with true or false:

src/search.unacheckrununa
--- Prints what the search functions answer about a SKU and a few typed texts.
pub main() -> Unit
  uses @console: Console[print]
=
  let sku = "COFFEE-05"
  let food = sku.starts_with(prefix: "COFFEE-")
  let small = sku.ends_with(suffix: "-05")
  let dash = sku.contains_text(part: "-")
  @console.print("starts with COFFEE-: {food}, ends with -05: {small}, has a dash: {dash}")
  let lower = sku.starts_with(prefix: "coffee-")
  @console.print("starts with coffee-: {lower}")
  let count = "0042"
  let typed = "42 "
  let empty = ""
  @console.print("only digits: {count.is_digits}, {typed.is_digits}, {empty.is_digits}")
Output
starts with COFFEE-: true, ends with -05: true, has a dash: true
starts with coffee-: false
only digits: true, false, true

The search is exact: "coffee-" is not found at the start of "COFFEE-05", since the case differs. "42 " is not all digits, because of its space. is_digits of the empty text is true: it has no character that is not a digit.

Each answer is named with let before it is printed, such as let food = sku.starts_with(prefix: "COFFEE-"). The call holds a text literal, "COFFEE-", and a text literal cannot stand inside the braces of an interpolation; the name can.

3.2.7 Replacing: replace

t.replace(pattern: p, by: r) gives back t with every place where p appears replaced by r, from left to right:

src/names.unacheckrununa
--- Prints a product name and a SKU with parts replaced.
pub main() -> Unit
  uses @console: Console[print]
=
  let name = "Oak desk, oak legs"
  @console.print(name.replace(pattern: "oak", by: "walnut"))
  @console.print(name.replace(pattern: "Oak", by: "Walnut"))
  @console.print(name.replace(pattern: "pine", by: "walnut"))
  let typed = "lamp 01"
  @console.print(typed.replace(pattern: " ", by: "-"))
  let draft = "RUG-07 (draft)"
  @console.print(draft.replace(pattern: " (draft)", by: ""))
Output
Oak desk, walnut legs
Walnut desk, oak legs
Oak desk, oak legs
lamp-01
RUG-07

The search for the pattern is exact, as for contains_text: "oak" replaces the small oak, and "Oak" the capital one. A pattern that does not appear leaves the text as it was. Replacing with the empty text, by: "", removes the pattern.

3.2.7.1 The pattern must not be empty

An empty pattern would appear between every two characters, so replace requires a pattern of at least one character. A literal pattern, as here, shows its length to the checker. A pattern that comes from a parameter does not, and una check refuses the call:

src/names.unauna
--- A name with every `part` replaced by a dash.
dashed(name: Text, part: Text) -> Text = name.replace(pattern: part, by: "-")
Diagnostic
[U5001] Error: precondition `part.len > 0` of this call is refuted
   ╭─[ src/names.una:4:42 ]
   │
 4 │ dashed(name: Text, part: Text) -> Text = name.replace(pattern: part, by: "-")
   │                                          ──────────────────┬─────────────────
   │                                                            ╰─────────────────── precondition `part.len > 0` of this call is refuted
   │ Note 2: counterexample: part = Text#0, part.len = 0

The message names what the call needs, part.len > 0, and says that the checker found a case where it does not hold: the call is refuted. The counterexample on the last line is that case: part is a text whose length is 0. Text#0 stands for "some text"; the checker names it, and the facts after it, here its length, are the ones that matter. The repairs come in section 3.4, which guards a call with if, and in chapter 5, which passes the need on to the callers with requires.

3.2.8 Cutting: slice

t.slice(start: a, end: b) gives back the characters of t from position a up to, but not including, position b. Positions count characters from 0: in "COFFEE-05", C is at position 0, the dash at 6, and the last 5 at 8.

src/cuts.unacheckrununa
--- Prints the parts of a SKU, cut out with `slice`.
pub main() -> Unit
  uses @console: Console[print]
=
  let sku = "COFFEE-05"
  @console.print(sku.slice(start: 0, end: 6))
  @console.print(sku.slice(start: 7, end: 9))
  @console.print(sku.slice(start: 7, end: sku.len))
  @console.print("[{sku.slice(start: 3, end: 3)}]")
  @console.print(sku.slice(start: 0, end: sku.len))
Output
COFFEE
05
05
[]
COFFEE-05

Read the cuts as fences between characters: start: 0, end: 6 takes the six characters before fence 6, COFFEE. start: 7, end: sku.len takes everything from position 7 to the end. Equal positions take nothing, the empty text. start: 0, end: sku.len takes the whole text. The length of a piece is always end - start.

3.2.8.1 A cut must stay inside the text

slice requires 0 <= start, start <= end and end <= t.len: a cut cannot start before the text, end before it starts, or end past the last character. The checker proves this at every call, before the program runs. Here it can, since sku names a literal, whose length the checker knows. For a parameter it cannot, and a label that cuts every name to its first 24 characters does not check:

src/labels.unauna
--- A product name cut to the 24 characters a label has room for.
pub fit_name(name: Text) -> Text = name.slice(start: 0, end: 24)
Diagnostic
[U5001] Error: precondition `0 <= 0 and 0 <= 24 and 24 <= name.len` of this call is refuted
   ╭─[ src/labels.una:4:36 ]
   │
 4 │ pub fit_name(name: Text) -> Text = name.slice(start: 0, end: 24)
   │                                    ──────────────┬──────────────
   │                                                  ╰──────────────── precondition `0 <= 0 and 0 <= 24 and 24 <= name.len` of this call is refuted
   │ Note 2: counterexample: name = Text#0, name.len = 0

The message writes out what slice needs, with the call's own values in place of start and end: 0 <= 0 and 0 <= 24 and 24 <= name.len. The counterexample is an empty name, whose length is 0: no 24 characters can be cut from it, and neither from any name shorter than 24. Another language might stop the program here while it runs, or cut less without a word; Una refuses the program and shows the input that would break it. Section 3.4 fixes fit_name with an if.

3.2.9 The text functions at a glance

Function Gives What it needs
t.len, built in, with no parentheses Int, the number of characters nothing
t.trim, t.trim_start, t.trim_end Text without the white space at both ends, the start or the end nothing
t.to_upper, t.to_lower Text with the letters a to z changed nothing
t.starts_with(prefix: p), t.ends_with(suffix: s), t.contains_text(part: p) Bool nothing
t.is_digits Bool, whether every character is a digit nothing
t.replace(pattern: p, by: r) Text p is not empty
t.slice(start: a, end: b) Text, the characters from a up to b 0 <= a, a <= b, b <= t.len

The prelude has a few more text functions, whose results are values of later chapters. split, chars and bytes give a list, a sequence of values (chapter 10). find and to_int give an Option, a value that may be missing, as when a text holds no number (chapter 7). Most of the text functions of this section came with edition 0.2, the edition of every package in this book.

The search box of a store's website matches what a customer types against product names. Customers type in any case, with stray spaces, so the search cleans what they typed and compares in small letters. The module also writes the last part of a product's web address from its name:

src/search_box.unacheckrununa
module search_box

-- The search box of the store's website: what a customer types, and the product names.

--- What the customer typed, as the search compares it: trimmed, in small letters.
pub tidy(typed: Text) -> Text = typed.trim.to_lower

--- Whether a product name holds what the customer typed, whatever the case of its letters.
pub matches(name: Text, typed: Text) -> Bool = name.to_lower.contains_text(part: tidy(typed))

--- The last part of a product's web address: the name in small letters, with dashes for the
--- comma and the spaces.
pub web_name(name: Text) -> Text = name.trim.to_lower.replace(pattern: ",", by: "").replace(pattern: " ", by: "-")

--- The line the search shows for one product and one search.
pub search_line(name: Text, typed: Text) -> Text = "[{typed}] in {name}: {matches(name, typed: typed)}"

--- Prints four searches, and the web address of a product.
pub main() -> Unit
  uses @console: Console[print]
=
  let lamp = "Desk lamp, Brass"
  let rug = "Wool rug, natural"
  @console.print(search_line(lamp, typed: "LAMP "))
  @console.print(search_line(rug, typed: "LAMP "))
  @console.print(search_line(rug, typed: " wool"))
  @console.print(search_line(lamp, typed: "brass"))
  @console.print("example.invalid/products/{web_name(lamp)}")
Output
[LAMP ] in Desk lamp, Brass: true
[LAMP ] in Wool rug, natural: false
[ wool] in Wool rug, natural: true
[brass] in Desk lamp, Brass: true
example.invalid/products/desk-lamp-brass

Each function does one step, and its name says which, so a reader can check each one alone.

3.2.11 Which text function to use

Which to use:

You want to… Use
Remove the stray spaces around a typed value trim, or trim_start or trim_end for one end
Compare texts whatever the case of their letters to_lower (or to_upper) on both sides, then ==
Ask whether a text begins, ends with or holds another starts_with, ends_with, contains_text
Change every place where a part appears replace, with a pattern that is not empty
Take a piece at known positions slice, with positions the checker can prove
Do several of these in a row a chain: typed.trim.to_upper

3.2.12 Check yourself: text functions

A product name is typed with stray spaces:

src/chains.unauna
--- Prints a typed product name after a chain of text functions, and two facts about it.
pub main() -> Unit
  uses @console: Console[print]
=
  let typed = "  Wool Rug "
  @console.print(typed.trim.to_lower.replace(pattern: " ", by: "-"))
  let code = typed.trim.to_upper
  let wool = code.starts_with(prefix: "WOOL")
  @console.print("{code.len} {wool}")

What does una run . print?

Show the answer
Output
wool-rug
8 true

The chain runs left to right: trim gives Wool Rug, to_lower gives wool rug, and replace puts a dash in place of the space. In the second line, code is WOOL RUG, 8 characters with its inner space, and it starts with WOOL.

Next:3.3 Conditions: Bool