Home / Learn / 3 Text and conditions

Release v0.4.0Edition 0.2

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:

Diagnostic
[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:

src/delivery.unacheckrununa
--- 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}")
Output
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). 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:

src/texts.unacheckrununa
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:

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

src/receipt.unacheckrununa
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}")
Output
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:

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.

src/lengths.unacheckrununa
--- 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}")
Output
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

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:

src/receipt.unauna
--- 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
Output
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.

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