---
title: "text"
description: "String conversion and manipulation"
weight: 10
type: "docs"
---

The `text` function is an intrinsic (always available, no `use()` needed). It is **polymorphic** — its behavior depends on the type of the first argument.

To split text into characters, use `array(text)` — see [array](/docs/library/array/).

## From an Array

### text(array, separator)

Join array elements into text with a separator (default: empty string).

```javascript
text(["h", "e", "l", "l", "o"])  // "hello"
text([1, 2, 3], ", ")            // "1, 2, 3"
text(["a", "b"], "-")            // "a-b"
```

## From a Number

### text(number, radix)

Convert a number to text. Radix is 2-36 (default: 10).

```javascript
text(255)        // "255"
text(255, 16)    // "ff"
text(255, 2)     // "11111111"
```

## From Text

### text(text, from, to)

Extract a substring from index `from` to `to`. Negative indices count from end.

```javascript
text("hello world", 0, 5)   // "hello"
text("hello world", 6)      // "world"
text("hello", -3)            // "llo"
```

## Methods

### text.lower(text)

Convert to lowercase.

```javascript
text.lower("HELLO")  // "hello"
```

### text.upper(text)

Convert to uppercase.

```javascript
text.upper("hello")  // "HELLO"
```

### text.trim(text, reject)

Remove characters from both ends. Default removes whitespace.

```javascript
text.trim("  hello  ")      // "hello"
text.trim("xxhelloxx", "x") // "hello"
```

### text.search(text, target, from)

Find the position of `target` in `text`. Returns `null` if not found.

```javascript
text.search("hello world", "world")     // 6
text.search("hello world", "xyz")       // null
text.search("hello hello", "hello", 1)  // 6
```

### text.replace(text, target, replacement, cap)

Replace occurrences of `target` with `replacement`. If `cap` is not specified, replaces all occurrences.

```javascript
text.replace("hello", "l", "L")      // "heLLo" (replaces all)
text.replace("hello", "l", "L", 1)   // "heLlo" (replaces first only)

// With function
text.replace("hello", "l", function(match, pos) {
  return pos == 2 ? "L" : match
})  // "heLLo" (replaces all by default)
```

### text.format(text, collection, transformer)

Substitute `{key}` placeholders with values from a collection.

```javascript
text.format("Hello, {name}!", {name: "World"})
// "Hello, World!"

text.format("{0} + {1} = {2}", [1, 2, 3])
// "1 + 2 = 3"
```

### text.normalize(text)

Unicode normalize the text (NFC form).

```javascript
text.normalize("cafe\u0301")  // normalized form
```

### text.codepoint(text)

Get the Unicode codepoint of the first character.

```javascript
text.codepoint("A")  // 65
```

### text.extract(text, pattern, from, to)

Match a pattern and extract named groups.

```javascript
text.extract("2024-01-15", /(\d+)-(\d+)-(\d+)/)
// Returns match info
```