> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ubiquex.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Built-in Functions

> The 34 built-in functions XCL provides, with signatures and examples.

XCL provides **34 built-in functions**, called with standard call syntax: `name(arg1, arg2, …)`. Every engine supports all of them. The Pulumi backends (Python, TypeScript, Go) implement them as small helper functions injected into the generated program, and the Terraform / OpenTofu backend maps them to native HCL functions. There is no "generated vs advisory" split — all 34 code-generate on every engine.

<Note>
  Three aliases are accepted and normalized before code generation: `len` → `length`, `str` → `tostring`, `int` → `tonumber`.
</Note>

## String functions

| Function     | Signature               | Description                                           |
| ------------ | ----------------------- | ----------------------------------------------------- |
| `lower`      | `lower(s)`              | Lowercase a string                                    |
| `upper`      | `upper(s)`              | Uppercase a string                                    |
| `replace`    | `replace(s, old, new)`  | Replace all occurrences of `old` with `new`           |
| `trim`       | `trim(s)`               | Trim surrounding whitespace                           |
| `trimprefix` | `trimprefix(s, prefix)` | Remove `prefix` if the string starts with it          |
| `trimsuffix` | `trimsuffix(s, suffix)` | Remove `suffix` if the string ends with it            |
| `split`      | `split(sep, s)`         | Split `s` on `sep` into a list of strings             |
| `join`       | `join(sep, list)`       | Join a list into a string with `sep` between elements |
| `format`     | `format(spec, ...args)` | Printf-style formatting (`%s`, `%d`, `%v`, `%%`)      |
| `strlen`     | `strlen(s)`             | Number of characters in a string                      |

<Note>
  `split` and `join` take the separator **first**: `split(sep, s)` and `join(sep, list)`, matching HCL.
</Note>

## Collection functions

| Function   | Signature                   | Description                                       |
| ---------- | --------------------------- | ------------------------------------------------- |
| `length`   | `length(x)`                 | Length of a string, list, or map                  |
| `keys`     | `keys(obj)`                 | Sorted list of an object's keys                   |
| `values`   | `values(obj)`               | List of an object's values, ordered by sorted key |
| `merge`    | `merge(a, b)`               | Merge two objects; keys in `b` win                |
| `contains` | `contains(list, val)`       | `true` if `list` contains `val`                   |
| `lookup`   | `lookup(obj, key, default)` | Value at `key`, or `default` if absent            |
| `flatten`  | `flatten(list)`             | Flatten a nested list by one level                |
| `distinct` | `distinct(list)`            | Remove duplicates, preserving order               |

## Conversion & encoding functions

| Function       | Signature         | Description                                             |
| -------------- | ----------------- | ------------------------------------------------------- |
| `tostring`     | `tostring(v)`     | Convert to a string (bools become `"true"` / `"false"`) |
| `tonumber`     | `tonumber(v)`     | Parse a value to a number                               |
| `tobool`       | `tobool(v)`       | Coerce a value to a boolean                             |
| `jsonencode`   | `jsonencode(v)`   | Encode a value as a JSON string                         |
| `jsondecode`   | `jsondecode(s)`   | Decode a JSON string to a value                         |
| `base64encode` | `base64encode(s)` | Base64-encode a string                                  |
| `base64decode` | `base64decode(s)` | Decode a base64 string                                  |

## Numeric functions

| Function | Signature        | Description                       |
| -------- | ---------------- | --------------------------------- |
| `min`    | `min(a, b, ...)` | Smallest of the arguments         |
| `max`    | `max(a, b, ...)` | Largest of the arguments          |
| `abs`    | `abs(n)`         | Absolute value                    |
| `ceil`   | `ceil(n)`        | Round up to the nearest integer   |
| `floor`  | `floor(n)`       | Round down to the nearest integer |

## Network / CIDR functions

| Function      | Signature                           | Description                               |
| ------------- | ----------------------------------- | ----------------------------------------- |
| `cidrsubnet`  | `cidrsubnet(cidr, newbits, netnum)` | Compute a subnet CIDR within `cidr`       |
| `cidrhost`    | `cidrhost(cidr, hostnum)`           | Host IP at `hostnum` within `cidr`        |
| `cidrnetmask` | `cidrnetmask(cidr)`                 | Netmask (e.g. `255.255.255.0`) for `cidr` |
| `cidrprefix`  | `cidrprefix(cidr)`                  | Prefix length (the number after `/`)      |

## Examples

Functions can be used anywhere an expression is allowed — in `locals` and in resource properties:

```xcl theme={"theme":"css-variables","languages":{"custom":["/languages/xcl.json"]}}
locals naming {
  name        = lower(input.env)
  bucket_name = lower(join("-", [input.env, input.project, "data"]))
  az_count    = length(input.azs)
}
```

```xcl theme={"theme":"css-variables","languages":{"custom":["/languages/xcl.json"]}}
locals network {
  app_subnet = cidrsubnet(input.vpc_cidr, 8, 2)
  gateway_ip = cidrhost(input.vpc_cidr, 1)
  netmask    = cidrnetmask(input.vpc_cidr)
}
```

The `secret(…)` expression and f-strings are language constructs, not functions — see [Expressions](/v1/xcl/language/expressions).