---
title: "Text"
url: https://una-lang.org/en/docs/guides/text/
release: v0.4.0
source: https://github.com/una-lang/una/blob/v0.4.0/docs/guide/una-for-agents.md
---

# Text

Edition `0.2` adds functions that take a text apart, search it, change it and parse it (`spec/22`). Each is a prelude function called with method syntax.

- **Positions** count Unicode scalar values from 0, as `.len` does; there are no byte offsets or graphemes.
- **The functions:**
  - `split(on:)`, which keeps empty parts, and `join(separator:)`, its inverse.
  - `find(text:)`, `Some` of the first position or `None`, which is `Some` exactly when `contains_text(part:)` holds; the position and the match lie in the text, so it bounds a `slice`. `ends_with(suffix:)`.
  - `replace(pattern:, by:)`, every non-overlapping occurrence, left to right.
  - `slice(start:, end:)`, whose precondition `0 <= start and start <= end and end <= t.len` you prove at each call.
  - `chars()`, one text per scalar value; `bytes()`, the UTF-8 encoding as `List[U8]`.
  - `to_upper()` and `to_lower()`, which change ASCII letters only and keep the length.
  - `trim_start()` and `trim_end()`, as `trim` at one end.
  - `parse_int()`, which fails with `ParseError`: `Empty`, `NoDigits` for `-` alone, `NotADigit(at: i)` at the first wrong position, or `TooLong` for more than 4300 digits. Handle it as any failure. The prelude's `to_int(t)` gives an `Option[Int]` instead, `None` for any text that is not an integer or has more than 4300 digits.
- **Cost:** `find`, `split` and `replace` are linear in the text; `.len` is O(1).
- **Proofs:** the contracts are hypotheses after each call, such as `split`'s `result.len >= 1` and `slice`'s `result.len == end - start`. There is no theory of strings beyond them.
- **Labels:** every result carries every label of every argument, including the top and the elements of `split`'s and `chars`' lists. Whether a secret parses is secret too.

```una
module csv

--- The fields of a line, without the spaces around them.
pub fields(line: Text) -> List[Text]
=
  let comma = ","
  let parts = line.split(on: comma)
  parts.map(each: fn(part) -> part.trim())

--- The number at the start of a field, or 0.
pub leading_number(field: Text) -> Int
=
  let space = " "
  let end = field.find(text: space)
    if none use field.len
  let digits = field.slice(start: 0, end: end)
  let n = digits.parse_int()
    if error use 0
  n
```
