---
title: String Built-ins
sidebar_label: Strings
---

<BuiltinTable category={"strings"}/>

:::info
When using `sprintf`, values are pre-processed and may have an unexpected type. For example,
`%T` evaluates to `string` for both `string` and `boolean` types. In such cases, use `type_name` to
accurately evaluate the underlying type.
:::

## Examples

### `contains`

`contains` is a commonly used Rego built-in function that checks if a string contains a substring. The function returns `true` if the string contains the substring and `false` otherwise.

Some examples of policy use cases where `contains` might be used include:

- Simple validation, such as checking if an email contains a `@` symbol.
- Checking if user input contains restricted words or phrases for content moderation.

:::caution

If you're looking to check a string that's expected to be at the start or end of a value, you might be better served by one of the following functions:

- [Starts With](#builtin-strings-startswith): Checks if a string starts with a specified prefix.
- [Any Prefix Match](#builtin-strings-stringsany_prefix_match): Checks if a string starts with any of the specified prefixes.
- [Ends With](#builtin-strings-endswith): Checks if a string ends with a specified suffix.
- [Any Suffix Match](#builtin-strings-stringsany_suffix_match): Checks if a string ends with any of the specified suffixes.

These are safer and potentially faster too.
:::

:::danger
`contains` only operates on strings, if you're looking to check for the presence of a value in a list you cannot use this function.
:::

:::note
If you're looking for the Rego keyword `contains` for building multi-value rules, you can read
about it in the [keywords section](/docs/policy-reference/keywords/contains).
:::

<PlaygroundExample dir={require.context('../_examples/strings/contains/email-validation')} />

<PlaygroundExample dir={require.context('../_examples/strings/contains/content-moderation')} />

### `startswith`

`startswith` reports whether a string begins with a given prefix. Prefer it
over `contains` when the match must be at the front of the value (HTTP paths,
registry prefixes, file paths).

<PlaygroundExample dir={require.context('../_examples/strings/startswith/api-path-prefix')} />

### `sprintf`

`sprintf` builds a string from a format and a list of values. Deny rules use
it to put the failing field and value into the message returned to the caller.

See also the note at the top of this page about how `sprintf` pre-processes
values (for example with `%T`).

<PlaygroundExample dir={require.context('../_examples/strings/sprintf/deny-message')} />

### `split`

`split` returns a list of substrings separated by a delimiter. Use it when a
path, hostname, or other structured string needs to be broken into parts.

<PlaygroundExample dir={require.context('../_examples/strings/split/team-from-path')} />

### `lower`

`lower` converts a string to lowercase. It is useful for normalisation and
formatting when values may arrive in mixed case.

<PlaygroundExample dir={require.context('../_examples/strings/lower/normalize-role')} />

### `endswith`

`endswith` reports whether a string ends with a given suffix. Use this function to valid matches at the ends of string values (file extensions, email domains, path suffixes etc.).

<PlaygroundExample dir={require.context('../_examples/strings/endswith/file-extension')} />

### `replace`

`replace` returns a string with every occurrence of a substring swapped for
another. A common policy use is redacting sensitive values.

<PlaygroundExample dir={require.context('../_examples/strings/replace/redact-token')} />

