# `Predicator.Functions.SystemFunctions`
[🔗](https://github.com/riddler/predicator-ex/blob/v9.5.0/lib/predicator/functions/system_functions.ex#L1)

Built-in helper functions for use in predicator expressions.

This module provides a collection of utility functions that can be called
within predicator expressions using function call syntax. These functions
operate on values from the evaluation context and return computed results.

## Available Functions

### String Functions
- `len(string)` - Returns the length of a string
- `upper(string)` - Converts string to uppercase
- `lower(string)` - Converts string to lowercase
- `trim(string)` - Removes leading and trailing whitespace
- `starts_with(string, prefix)` - Tests whether a string starts with a prefix
- `ends_with(string, suffix)` - Tests whether a string ends with a suffix
- `substring(string, start[, len])` - Extracts a substring from a start index
- `index_of(string, sub)` - Finds the index of a substring, or -1

### List Functions
- `concat(list1, list2)` - Concatenates two lists

## Examples

    iex> Predicator.evaluate("len('hello')", %{})
    {:ok, 5}

    iex> Predicator.evaluate("upper('world')", %{})
    {:ok, "WORLD"}

    iex> Predicator.evaluate("starts_with('hello world', 'hello')", %{})
    {:ok, true}

    iex> Predicator.evaluate("ends_with('hello world', 'world')", %{})
    {:ok, true}

    iex> Predicator.evaluate("substring('hello world', 6)", %{})
    {:ok, "world"}

    iex> Predicator.evaluate("substring('hello world', 0, 5)", %{})
    {:ok, "hello"}

    iex> Predicator.evaluate("index_of('hello world', 'world')", %{})
    {:ok, 6}

    iex> Predicator.evaluate("index_of('hello world', 'nope')", %{})
    {:ok, -1}

    iex> Predicator.evaluate("concat([1, 2], [3])", %{})
    {:ok, [1, 2, 3]}

# `function_result`

```elixir
@type function_result() :: {:ok, Predicator.Types.value()} | {:error, binary()}
```

# `call_concat`

```elixir
@spec call_concat([Predicator.Types.value()], Predicator.Context.t()) ::
  function_result()
```

Concatenates two lists.

# `call_ends_with`

```elixir
@spec call_ends_with([Predicator.Types.value()], Predicator.Context.t()) ::
  function_result()
```

Tests whether a string ends with a suffix.

# `call_index_of`

```elixir
@spec call_index_of([Predicator.Types.value()], Predicator.Context.t()) ::
  function_result()
```

Finds the index of a substring, or -1 if it is not present.

# `call_len`

```elixir
@spec call_len([Predicator.Types.value()], Predicator.Context.t()) ::
  function_result()
```

Returns the length of a string.

# `call_lower`

```elixir
@spec call_lower([Predicator.Types.value()], Predicator.Context.t()) ::
  function_result()
```

Converts a string to lowercase.

# `call_starts_with`

```elixir
@spec call_starts_with([Predicator.Types.value()], Predicator.Context.t()) ::
  function_result()
```

Tests whether a string starts with a prefix.

# `call_substring`

```elixir
@spec call_substring([Predicator.Types.value()], Predicator.Context.t()) ::
  function_result()
```

Extracts a substring from a start index, with an optional length.

# `call_trim`

```elixir
@spec call_trim([Predicator.Types.value()], Predicator.Context.t()) ::
  function_result()
```

Removes leading and trailing whitespace from a string.

# `call_upper`

```elixir
@spec call_upper([Predicator.Types.value()], Predicator.Context.t()) ::
  function_result()
```

Converts a string to uppercase.

# `functions`

```elixir
@spec functions() :: %{
  required(Predicator.FunctionProvider.name()) =>
    Predicator.FunctionProvider.entry()
}
```

Returns all system functions as a `Predicator.FunctionProvider` map.

## Returns

A map where keys are function names and values are `{arity, atom}` pairs -
`atom` naming a public `call_*/2` function on this module.

## Examples

    iex> functions = Predicator.Functions.SystemFunctions.functions()
    iex> Map.has_key?(functions, "len")
    true
    iex> {arity, _atom} = functions["len"]
    iex> arity
    1

---

*Consult [api-reference.md](api-reference.md) for complete listing*