---
title: "3.1 Text"
url: https://una-lang.org/en/learn/text-and-conditions/text/
release: v0.4.0
edition: "0.2"
---

# 3.1 Text

## 3.1.1 What a text is

A **text** is a piece of writing that a program holds as a value: a product name, a SKU, a line of a label, a greeting. A text is a sequence of **characters**, in order: letters, digits, spaces, punctuation and symbols. You met texts in [chapter 1](https://una-lang.org/en/learn/hello/writing-a-function/#s1-4), between double quotes, and the type of a text is `Text`.

Think of a text as the letters on a strip of paper. You can read them, count them, compare two strips, or write a new strip from parts of old ones. But a strip is not a number, even when it shows digits: "02134" on a parcel is a postal code, and nobody adds two postal codes.

A text can hold the characters of any language, `é`, `ü` and `×` included, since Una texts are **Unicode**: the standard that gives a number to every character of every writing system.

## 3.1.2 Why a text is not a number

Some values are written in digits but are not amounts: a postal code, a phone number, the digits of a SKU. You never add them, and every character counts, a leading zero included. Keep a postal code as an `Int`, with `let postal_code = 02134`, and `una check .` refuses it:

```text include="steps/01-postal-number/expected/rendered.txt#L1"
[U0007] Error: malformed integer literal `02134`
```

This is the error of [A number with a leading zero](https://una-lang.org/en/learn/numbers/common-mistakes/#a-number-with-a-leading-zero-u0007) in chapter 2: an `Int` literal never starts with a zero. What this section adds is the way out. A code whose zeros matter is a `Text`, and a text keeps every character:

```una include="steps/02-postal-text/src/delivery.una#main" title="src/delivery.una" verified="check, run"
--- Prints where a parcel goes, with the postal code as a text.
pub main() -> Unit
  uses @console: Console[print]
=
  let postal_code = "02134"
  @console.print("Deliver to {postal_code}")
```

```text include="steps/02-postal-text/expected/output.txt"
Deliver to 02134
```

The rule of thumb: if you compute with it, it is a number; if you only show it, compare it or take it apart, it is a text.

## 3.1.3 How to write a text

### 3.1.3.1 A text literal

A **literal** is a value written out in the code ([section 2.1](https://una-lang.org/en/learn/numbers/values-types-and-names-let/#s2-1)). A text literal is the characters of the text between double quotes, `"Desk lamp, brass"`, on one line. The quotes are not part of the text: `"LAMP-01"` holds seven characters, from `L` to `1`. Two quotes with nothing between them, `""`, are the **empty text**: a text with no characters at all, as a strip of paper with nothing written on it.

### 3.1.3.2 Escapes

A few characters cannot be typed between the quotes as they are. A double quote would end the text, and a brace starts an interpolation, as the next part shows. For these, you write an **escape**: a backslash, `\`, followed by one more character, which together stand for one character of the text.

| Write | For |
| --- | --- |
| `\"` | a double quote |
| `\\` | a backslash |
| `\{` and `\}` | a brace |
| `\n` | a new line: what follows starts a new line when the text is printed |
| `\t` | a tab, a wide space that lines up columns |
| `\u{e9}` | the character whose Unicode number is written between the braces, in hexadecimal (base 16), here `é` |

This module prints one text of each form:

```una include="steps/03-literals/src/texts.una" title="src/texts.una" verified="check, run"
module texts

--- Prints one text of each form: plain, empty, and with each escape.
pub main() -> Unit
  uses @console: Console[print]
=
  @console.print("Desk lamp, brass")
  @console.print("Café table, 2 × 1 m")
  @console.print("")
  @console.print("The sign says \"SALE\"")
  @console.print("A backslash: \\")
  @console.print("Braces: \{ and \}")
  @console.print("Aisle 4\nAisle 5")
  @console.print("LAMP-01\t19.90")
  @console.print("Caf\u{e9} table")
```

`una run .` prints:

```text include="steps/03-literals/expected/output.txt"
Desk lamp, brass
Café table, 2 × 1 m

The sign says "SALE"
A backslash: \
Braces: { and }
Aisle 4
Aisle 5
LAMP-01	19.90
Café table
```

Each `print` gives one line of output, except the seventh: `"Aisle 4\nAisle 5"` is one text with a new line inside it, so it prints as two lines. The empty text prints as an empty line. `\u{e9}` gives the same `é` as the one typed in the second line.

### 3.1.3.3 Putting values into a text: interpolation

You met interpolation in [section 2.1](https://una-lang.org/en/learn/numbers/values-types-and-names-let/#s2-1): a name or a computation in braces, inside a text, puts its value into the text, as in `"{units} x {sku}"`. Here is the rest of what the braces can hold:

```una include="steps/04-interpolation/src/receipt.una" title="src/receipt.una" verified="check, run"
module receipt

--- The SKU of the desk lamp.
lamp_sku() -> Text = "LAMP-01"

--- Prints the lines of a receipt, each built with interpolation.
pub main() -> Unit
  uses @console: Console[print]
=
  let units = 3
  let unit_cents = 1_990
  let sku = lamp_sku()
  let gift = true
  let copies: U8 = 2
  @console.print("{units} x {sku}")
  @console.print("{units} x {unit_cents} cents = {units * unit_cents} cents")
  @console.print("SKU: {lamp_sku()}")
  @console.print("Gift wrap: {gift}")
  @console.print("Receipts to print: {copies}")
  @console.print("{sku}{sku}")
```

```text include="steps/04-interpolation/expected/output.txt"
3 x LAMP-01
3 x 1990 cents = 5970 cents
SKU: LAMP-01
Gift wrap: true
Receipts to print: 2
LAMP-01LAMP-01
```

Besides a name and a computation, such as `{units * unit_cents}`, the braces can hold:

- a call, such as `{lamp_sku()}`, whose result goes into the text;
- a value of other types than `Int`: a fixed-width type such as `U8` ([section 2.3](https://una-lang.org/en/learn/numbers/fixed-width-integers/#s2-3)), which goes in as its decimal digits, as an `Int` does; a `Bool`, as `true` or `false`; and a `Text`, as its characters.

The braces add nothing of their own: `"{sku}{sku}"` is the two texts side by side, with no space between them. A brace you want printed is escaped, `\{` and `\}`, and a text literal cannot stand between the braces, as [How text behaves](#how-text-behaves) says.

### 3.1.3.4 Joining texts

Interpolation is also how you join texts. To put a SKU, a bar and a name in one text, write `"{sku} | {name}"`. Una has no operator that joins texts: `+` adds numbers only, and `sku + " | "` does not check, as [Joining texts with `+`](https://una-lang.org/en/learn/text-and-conditions/common-mistakes/#joining-texts-with-u2001) shows.

## 3.1.4 The length of a text, and comparing texts

`.len`, written right after a text or a name that holds one, gives the text's **length**: how many characters it has. It is built into the language, and written without parentheses. It has no other form: `sku.len()` and `len(sku)` are both U1001, since neither names a function. `==` asks whether two values are equal, and gives `true` or `false`, which [section 3.3](https://una-lang.org/en/learn/text-and-conditions/conditions-bool/#s3-3) covers.

```una include="steps/05-lengths/src/lengths.una#main" title="src/lengths.una" verified="check, run"
--- Prints the length of four texts, and compares texts.
pub main() -> Unit
  uses @console: Console[print]
=
  let sku = "LAMP-01"
  let cafe = "Café"
  let empty = ""
  let space = " "
  @console.print("{sku.len} {cafe.len} {empty.len} {space.len}")
  let typed = "lamp-01"
  let escaped = "Caf\u{e9}"
  @console.print("{sku == typed} {cafe == escaped}")
```

```text include="steps/05-lengths/expected/output.txt"
7 4 0 1
false true
```

`"LAMP-01"` has 7 characters, `"Café"` has 4, the empty text has 0, and a text of one space has 1: a space is a character like any other. `"LAMP-01" == "lamp-01"` is `false`, since a capital letter and a small letter are different characters. `"Café" == "Caf\u{e9}"` is `true`: the escape and the typed `é` are the same character, so the two texts are equal.

## 3.1.5 How text behaves

- **A text never changes.** Once a text exists, its characters stay as they are. The functions of [section 3.2](https://una-lang.org/en/learn/text-and-conditions/working-with-text-the-preludes-functions-and-method-calls/#s3-2) that clean or change a text give back a new text, and leave the old one as it was.
- **Lengths count characters, not bytes.** Una stores `é` in two bytes, small units of storage, and `A` in one, but counts each as one character. A few symbols that look like one character on the screen, such as some emoji, are made of several Unicode characters, and count as that many.
- **Equality is exact.** Two texts are equal when they have the same characters in the same order: case, spaces and punctuation all count.
- **A text literal is one line.** A text that is not closed by `"` on its own line is U0004. For a text of several lines, write `\n` where each new line starts.
- **An unknown escape is refused.** `\q` is not an escape, and `una check` reports U0005; a backslash itself is written `\\`.
- **A brace in a text is an interpolation, or escaped.** A `{` that cannot start an interpolation, such as one followed by a quote, and a `}` outside an interpolation, are U0007, with a repair that writes `\{` or `\}`.
- **No text literal inside braces.** The quotes of a literal would end the outer text, so `una check` refuses a literal between the braces of an interpolation. Name the text with `let` first, then put the name in the braces, as [A text inside an interpolation](https://una-lang.org/en/learn/text-and-conditions/common-mistakes/#a-text-inside-an-interpolation-u0006) shows.

## 3.1.6 When to use a text

:::decide
**Which to use:**

| You want to… | Use |
| --- | --- |
| Show words, codes or labels to people | a `Text` |
| Hold digits you never compute with, such as a postal code or a phone number | a `Text`, which keeps every character, leading zeros included |
| Count or compute, such as units or cents | an `Int` ([section 2.2](https://una-lang.org/en/learn/numbers/whole-numbers-int/#s2-2)) |
| Build a text from values | interpolation, `"{units} x {sku}"` |
| Put a quote, a backslash, a brace, a new line or a tab in a text | an escape: `\"`, `\\`, `\{`, `\}`, `\n`, `\t` |
:::

## 3.1.7 Check yourself: text

A gift receipt is printed by this `main`:

```una include="steps/06-text-check/src/receipt.una#main" title="src/receipt.una"
--- Prints a line of a gift receipt, and two more lines.
pub main() -> Unit
  uses @console: Console[print]
=
  let sku = "RUG-07"
  let units = 2
  let empty = ""
  @console.print("{units} x {sku} \{gift\}")
  @console.print("[{empty}] has {empty.len} characters, {sku} has {sku.len}")
  @console.print("Thank you\nCome again")
```

What does `una run .` print?

:::answer Show the answer
```text include="steps/06-text-check/expected/output.txt"
2 x RUG-07 {gift}
[] has 0 characters, RUG-07 has 6
Thank you
Come again
```

The first line puts `units` and `sku` into the text, and `\{gift\}` writes the braces themselves, so `gift` is printed as a word, not looked up as a name. The second line puts the empty text between the brackets, with nothing in it, and gives the lengths 0 and 6. The third `print` is one text with `\n` inside, so it prints as two lines.
:::
