# Predicates: Key-Value

Refer to [Terminology](./terminology.md) for information about specific terms.

[[_TOC_]]

## Description

These predicates are focused on reasoning about keys and their associated
(or not associated) values.

## Input

All key-value predicates accept a single input: some key-value provider. This
is the state referenced by the predicates.

This provider can answer two questions:

- Does the given key exist?
- What is the value associated with a given key?

## Predicate: Key Exists

Matches if the key-value provider contains the given key.

## Predicate: Value Equals

Given some key `K` and expected value `EV`, this predicate matches if:

- There is some value `V` associated with `K`.
- `V` is equal to `EV`.

## Predicate: Value Not Equals

Given some key `K` and unexpected value `UV`, this predicate matches if:

- There is some value `V` associated with `K`.
- `V` is not equal to `UV`.

## Predicate: String Contains

> [!important]
> This predicate is only supported for string values.

Given some key `K` and string `S`, this predicate matches if:

- There is some value `V` associated with `K`.
- `V` contains the substring `S`.

### Examples

| `S`     | `V`     | Result  |
| ------- | ------- | ------- |
| `""`    | `""`    | `match` |
| `""`    | `"a"`   | `match` |
| `"a"`   | `""`    | `miss`  |
| `"a"`   | `"abc"` | `match` |
| `"ab"`  | `"abc"` | `match` |
| `"b"`   | `"abc"` | `match` |
| `"bc"`  | `"abc"` | `match` |
| `"c"`   | `"abc"` | `match` |
| `"d"`   | `"abc"` | `miss`  |
| `"abc"` | `"abc"` | `match` |

## Predicate: String Starts With

> [!important]
> This predicate is only supported for string values.

Given some key `K` and prefix `P`, this predicate matches if:

- There is some value `V` associated with `K`.
- `V` starts with the prefix `P`.

### Examples

| `P`     | `V`     | Result  |
| ------- | ------- | ------- |
| `""`    | `""`    | `match` |
| `""`    | `"a"`   | `match` |
| `"a"`   |  `""`   | `miss`  |
| `"a"`   | `"abc"` | `match` |
| `"ab"`  | `"abc"` | `match` |
| `"b"`   | `"abc"` | `miss`  |
| `"d"`   | `"abc"` | `miss`  |
| `"abc"` | `"abc"` | `match` |

## Predicate: String Ends With

> [!important]
> This predicate is only supported for string values.

Given some key `K` and suffix `S`, this predicate matches if:

- There is some value `V` associated with `K`.
- `V` ends with the suffix `S`.

### Examples

| `S`     | `V`     | Result  |
| ------- | ------- | ------- |
| `""`    | `""`    | `match` |
| `""`    | `"a"`   | `match` |
| `"a"`   |  `""`   | `miss`  |
| `"a"`   | `"abc"` | `miss`  |
| `"bc"`  | `"abc"` | `match` |
| `"c"`   | `"abc"` | `match` |
| `"d"`   | `"abc"` | `miss`  |
| `"abc"` | `"abc"` | `match` |