# `Predicator.Undefined`
[🔗](https://github.com/riddler/predicator-ex/blob/v9.4.1/lib/predicator/undefined.ex#L1)

The `:undefined` sentinel: predicator's representation of an unbound or
missing value.

The atom stays the runtime representation - it is pervasive in tests and
the Ruby/JavaScript siblings, JSON-adjacent, and cheap. A struct sentinel
would break instruction interchange and every existing embedding for
aesthetic gain (the instruction list is the cross-language interchange
format, `ADR-0001`). This module owns it publicly instead: one place that
names the atom, checks for it, and normalizes it against `nil` at a
JSON-shaped boundary.

# `from_nil`

```elixir
@spec from_nil(Predicator.Types.value() | nil) :: Predicator.Types.value()
```

Converts `nil` to the `:undefined` sentinel; any other value passes
through unchanged. The inverse of `to_nil/1`.

For normalizing an incoming `nil` (JSON `null`, a host application's own
"missing") to predicator's sentinel at the edge. This is an edge helper
for a boundary that does not distinguish null from undefined -
`Predicator.Context.new/2` no longer calls it: a `nil` in a context is now
the null value.

## Examples

    iex> Predicator.Undefined.from_nil(nil)
    :undefined

    iex> Predicator.Undefined.from_nil(42)
    42

# `to_nil`

```elixir
@spec to_nil(Predicator.Types.value()) :: Predicator.Types.value() | nil
```

Converts the `:undefined` sentinel to `nil`; any other value passes
through unchanged.

For embedding at a boundary that speaks `nil` rather than `:undefined`
(JSON output, a host application's own representation of "missing"). This
is an edge helper for a boundary that does not distinguish null from
undefined - `Predicator.Context` itself keeps them apart.

## Examples

    iex> Predicator.Undefined.to_nil(:undefined)
    nil

    iex> Predicator.Undefined.to_nil(42)
    42

# `undefined?`

```elixir
@spec undefined?(Predicator.Types.value() | nil) :: boolean()
```

Checks whether `value` is the `:undefined` sentinel.

## Examples

    iex> Predicator.Undefined.undefined?(:undefined)
    true

    iex> Predicator.Undefined.undefined?(nil)
    false

    iex> Predicator.Undefined.undefined?(42)
    false

# `value`

```elixir
@spec value() :: :undefined
```

The `:undefined` sentinel value.

## Examples

    iex> Predicator.Undefined.value()
    :undefined

---

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