# Strings and formatting

> Transform and search text, convert values, split lines, and format output.

Canonical: https://alice-lang.org/documentation/library/strings/

[Documentation index](https://alice-lang.org/documentation/llms.txt) · [Complete book](https://alice-lang.org/llms-full.txt)

## Strings are .NET text

Alice strings are `System.String` values. A transformation returns a new string rather than changing the original. CLR character and indexing behavior uses UTF-16; a character is not necessarily a complete user-perceived Unicode grapheme.

```alice
name = "  Alice  ".strip
puts "Hello, #{name.upcase}!"
puts "red,white,red".split(",").uniq.join(" / ")
puts "rabbit42".match?(/\d+/)
```

Expected output:

```text
Hello, ALICE!
red / white
true
```

[Edit and run in the Alice playground](https://playground.alice-lang.org/#code=u.bmFtZSA9ICIgIEFsaWNlICAiLnN0cmlwCnB1dHMgIkhlbGxvLCAje25hbWUudXBjYXNlfSEiCnB1dHMgInJlZCx3aGl0ZSxyZWQiLnNwbGl0KCIsIikudW5pcS5qb2luKCIgLyAiKQpwdXRzICJyYWJiaXQ0MiIubWF0Y2g_KC9cZCsvKQ)

Use interpolation for readable messages: `"Hello, #{name}!"`. For repeated appends, consider `System.Text.StringBuilder` rather than constructing a growing chain of temporary strings.

## Common transformations

| Methods                                                 | Purpose                                                 |
| ------------------------------------------------------- | ------------------------------------------------------- |
| `upcase`, `downcase`, `capitalize`, `swapcase`, `title` | Change case                                             |
| `strip`, `chomp`, `chop`                                | Trim whitespace, a line ending, or the last character   |
| `center(width)`, `ljust(width)`, `rjust(width)`         | Pad to a width                                          |
| `squeeze`                                               | Collapse repeated characters                            |
| `reverse`, `succ`                                       | Reverse or advance text according to the helper's rules |
| `sub`, `gsub`                                           | Replace the first or all matching occurrences           |
| `tr`, `delete`                                          | Translate or remove characters                          |
| `repeat(n)`, `text * n`                                 | Repeat a string                                         |

`sub` and `gsub` accept string or supported regex patterns. Use [regex](https://alice-lang.org/documentation/library/regex.md) when matching has structure rather than a literal substring.

## Search and split

| Methods                       | Purpose                             |
| ----------------------------- | ----------------------------------- |
| `size`, `empty?`              | Length and emptiness                |
| `includes?`, `include?`       | Containment                         |
| `starts_with?`, `ends_with?`  | Prefix and suffix                   |
| `index`, `rindex`             | Find a position                     |
| `count(set)`                  | Count characters from a set         |
| `split(separator)`            | Split text into fields              |
| `lines`, `each_line`          | Work line by line                   |
| `chars`, `each_char`, `bytes` | Enumerate characters or bytes       |
| `match?`, `scan`              | Regex matching and repeated matches |

String `index` and `rindex` return `-1` when the substring is absent; they are not nullable positions. `split` removes empty entries in its current prelude implementation. Splitting and materializing lines/characters can allocate arrays.

## Conversions

`to_s` converts to text; `to_i` and `to_f` parse numeric text. `hex` and `oct` read hexadecimal and octal forms. `to_sym` produces the supported symbol-like representation. Validate external data and handle conversion failures rather than assuming all user input is numeric.

## Formatting

Interpolation is often enough:

```alice
count = 3
puts "#{count} cups of tea"
puts format("%05d | %.2f", 42, 3.14)
```

`format` supports `%d`, `%i`, `%s`, `%f`, `%.Nf`, `%e`, `%x`, `%X`, `%o`, `%b`, `%c`, and `%%`. Flags include `-`, `0`, `+`, and a space; a width controls padding. String `%` formatting can pass an array of values, such as `"%05d" % [42]`.

Use the .NET formatting APIs directly when a library requires a specific culture or format contract.

## Continue reading

- Previous: [Hashes and dictionaries](https://alice-lang.org/documentation/library/hashes.md)
- Next: [Numbers, ranges, and math](https://alice-lang.org/documentation/library/numbers.md)