Home / Learn / 3 Text and conditions
3.1 Text
Page 2 of 10
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, 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:
[U0007] Error: malformed integer literal `02134`This is the error of A number with a leading zero 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:
--- 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}")Deliver to 02134The 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). 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:
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:
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é tableEach 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: 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:
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}")3 x LAMP-01
3 x 1990 cents = 5970 cents
SKU: LAMP-01
Gift wrap: true
Receipts to print: 2
LAMP-01LAMP-01Besides 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 asU8(section 2.3), which goes in as its decimal digits, as anIntdoes; aBool, astrueorfalse; and aText, 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 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 + 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 covers.
--- 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}")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 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, andAin 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\nwhere each new line starts. - An unknown escape is refused.
\qis not an escape, anduna checkreports 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 checkrefuses a literal between the braces of an interpolation. Name the text withletfirst, then put the name in the braces, as A text inside an interpolation shows.
3.1.6 When to use a text
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) |
| 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:
--- 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?
Show the answer
2 x RUG-07 {gift}
[] has 0 characters, RUG-07 has 6
Thank you
Come againThe 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.
Next:3.2 Working with text: the prelude's functions and method calls