---
title: "3.2 Working with text: the prelude's functions and method calls"
url: https://una-lang.org/en/learn/text-and-conditions/working-with-text-the-preludes-functions-and-method-calls/
release: v0.4.0
edition: "0.2"
---

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

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

```una include="steps/07-messy-sku/src/till.una#main" title="src/till.una" verified="check, run"
--- 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}")
```

```text include="steps/07-messy-sku/expected/output.txt"
[ 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:

```una include="steps/08-method-syntax/src/till.una" title="src/till.una" verified="check, run"
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}")
```

```text include="steps/08-method-syntax/expected/output.txt"
[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](https://una-lang.org/en/learn/hello/writing-a-function/#s1-4). `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](https://una-lang.org/en/learn/numbers/fixed-width-integers/#s2-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](https://una-lang.org/en/learn/functions/calls-in-depth-labels-the-order-of-evaluation-method-calls-on-your-own-kinds/#s6-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:

```una include="steps/09-trim/src/trimming.una#main" title="src/trimming.una" verified="check, run"
--- 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")
```

```text include="steps/09-trim/expected/output.txt"
[  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:

```una include="steps/10-case/src/case.una#main" title="src/case.una" verified="check, run"
--- 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}")
```

```text include="steps/10-case/expected/output.txt"
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`:

- `t.starts_with(prefix: p)`: whether `t` begins with `p`;
- `t.ends_with(suffix: s)`: whether `t` ends with `s`;
- `t.contains_text(part: p)`: whether `p` appears anywhere in `t`;
- `t.is_digits`: whether every character of `t` is a digit from `0` to `9`.

```una include="steps/11-search/src/search.una#main" title="src/search.una" verified="check, run"
--- 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}")
```

```text include="steps/11-search/expected/output.txt"
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:

```una include="steps/12-replace/src/names.una#main" title="src/names.una" verified="check, run"
--- 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: ""))
```

```text include="steps/12-replace/expected/output.txt"
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:

```una include="steps/13-empty-pattern/src/names.una#dashed" title="src/names.una"
--- A name with every `part` replaced by a dash.
dashed(name: Text, part: Text) -> Text = name.replace(pattern: part, by: "-")
```

```text include="steps/13-empty-pattern/expected/rendered.txt#L1-L6,L18"
[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](https://una-lang.org/en/learn/text-and-conditions/choosing-between-two-values-if/#s3-4), which guards a call with `if`, and in [chapter 5](https://una-lang.org/en/learn/contracts/preconditions-requires/#s5-1), 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.

```una include="steps/14-slice/src/cuts.una#main" title="src/cuts.una" verified="check, run"
--- 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))
```

```text include="steps/14-slice/expected/output.txt"
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:

```una include="steps/15-cut-name/src/labels.una#fit_name" title="src/labels.una"
--- 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)
```

```text include="steps/15-cut-name/expected/rendered.txt#L1-L6,L16"
[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](https://una-lang.org/en/learn/text-and-conditions/choosing-between-two-values-if/#s3-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](https://una-lang.org/en/learn/collections/lists/#s10-1)). `find` and `to_int` give an `Option`, a value that may be missing, as when a text holds no number ([chapter 7](https://una-lang.org/en/learn/failure/a-value-that-may-be-missing-option/#s7-1)). Most of the text functions of this section came with edition `0.2`, the edition of every package in this book.

## 3.2.10 A search box

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:

```una include="steps/16-search-box/src/search_box.una" title="src/search_box.una" verified="check, run"
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)}")
```

```text include="steps/16-search-box/expected/output.txt"
[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
```

- **`tidy`** trims what was typed and writes it in small letters, so that `"LAMP "` becomes `"lamp"`.
- **`matches`** writes the name in small letters too, then searches it for the tidied text. Both sides are in one case, so `"brass"` finds `"Brass"`.
- **`web_name`** is a chain of four calls: trim, small letters, remove the comma, then a dash for each space. `"Desk lamp, Brass"` becomes `desk-lamp-brass`.
- **`search_line`** puts the typed text, the name and the answer into one line. The brackets show the stray spaces of what was typed.

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

:::decide
**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:

```una include="steps/17-chain-check/src/chains.una#main" title="src/chains.una"
--- 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?

:::answer Show the answer
```text include="steps/17-chain-check/expected/output.txt"
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`.
:::
