# `TerminusDB.WOQL.RDFList`
[🔗](https://github.com/thanos/terminusdb-client-elixir/blob/v0.3.3/lib/terminus_db/woql/rdf_list.ex#L1)

RDF list library for TerminusDB.

Provides 17 functions for manipulating RDF `rdf:List` structures using
WOQL primitives. Each function composes `TerminusDB.WOQL.Query` structs
using existing `WOQL.*` builders.

Variable name collisions are avoided via an internal `localize/1` helper
that generates process-unique variable names using `:erlang.unique_integer/1`.

## Quick start

    import TerminusDB.WOQL

    # Get the first element of an rdf:List
    query = and_([
      triple("v:List", "rdf:type", iri("rdf:List")),
      TerminusDB.WOQL.RDFList.rdflist_peek("v:List", "v:First")
    ])

    # Get all elements as an array
    query = TerminusDB.WOQL.RDFList.rdflist_list("v:List", "v:Array")

# `vars`

```elixir
@type vars() :: %{required(atom()) => woql_var()}
```

# `woql_query`

```elixir
@type woql_query() :: TerminusDB.WOQL.t()
```

# `woql_var`

```elixir
@type woql_var() :: String.t()
```

# `rdflist_append`

```elixir
@spec rdflist_append(woql_var(), woql_var(), woql_var() | nil) :: woql_query()
```

Appends a value to the end of the list (allocates a new cell at rdf:nil).

## Examples

    iex> q = TerminusDB.WOQL.RDFList.rdflist_append("v:List", "v:Value")
    iex> q.op
    :and

# `rdflist_clear`

```elixir
@spec rdflist_clear(woql_var(), woql_var()) :: woql_query()
```

Deletes all cons cells and returns rdf:nil as the new list value.

## Examples

    iex> q = TerminusDB.WOQL.RDFList.rdflist_clear("v:List", "v:NewList")
    iex> q.op
    :and

# `rdflist_drop`

```elixir
@spec rdflist_drop(woql_var(), non_neg_integer() | woql_var()) :: woql_query()
```

Drops/removes a single element at the given position.

## Examples

    iex> q = TerminusDB.WOQL.RDFList.rdflist_drop("v:List", 1)
    iex> q.op
    :and

# `rdflist_empty`

```elixir
@spec rdflist_empty(woql_var()) :: woql_query()
```

Creates an empty rdf:List (binds to rdf:nil).

## Examples

    iex> q = TerminusDB.WOQL.RDFList.rdflist_empty("v:List")
    iex> q.op
    :eq

# `rdflist_insert`

```elixir
@spec rdflist_insert(
  woql_var(),
  non_neg_integer() | woql_var(),
  woql_var(),
  woql_var() | nil
) :: woql_query()
```

Inserts a value at a 0-indexed position (allocates a new cell).

## Examples

    iex> q = TerminusDB.WOQL.RDFList.rdflist_insert("v:List", 1, "v:Value")
    iex> q.op
    :and

# `rdflist_is_empty`

```elixir
@spec rdflist_is_empty(woql_var()) :: woql_query()
```

Checks if the list is empty (equals rdf:nil).

## Examples

    iex> q = TerminusDB.WOQL.RDFList.rdflist_is_empty("v:List")
    iex> q.op
    :eq

# `rdflist_last`

```elixir
@spec rdflist_last(woql_var(), woql_var()) :: woql_query()
```

Gets the last element of an rdf:List (the value of the cell whose rdf:rest is rdf:nil).

## Examples

    iex> q = TerminusDB.WOQL.RDFList.rdflist_last("v:List", "v:Last")
    iex> q.op
    :and

# `rdflist_length`

```elixir
@spec rdflist_length(woql_var(), woql_var()) :: woql_query()
```

Gets the length of an rdf:List.

## Examples

    iex> q = TerminusDB.WOQL.RDFList.rdflist_length("v:List", "v:Len")
    iex> q.op
    :and

# `rdflist_list`

```elixir
@spec rdflist_list(woql_var(), woql_var()) :: woql_query()
```

Collects all rdf:List elements into a single array variable.

## Examples

    iex> q = TerminusDB.WOQL.RDFList.rdflist_list("v:List", "v:Array")
    iex> q.op
    :and

# `rdflist_member`

```elixir
@spec rdflist_member(woql_var(), woql_var()) :: woql_query()
```

Traverses the list, yielding each element as a separate binding.

## Examples

    iex> q = TerminusDB.WOQL.RDFList.rdflist_member("v:List", "v:Elem")
    iex> q.op
    :and

# `rdflist_nth0`

```elixir
@spec rdflist_nth0(woql_var(), non_neg_integer() | woql_var(), woql_var()) ::
  woql_query()
```

Gets the element at a 0-indexed position.

## Examples

    iex> q = TerminusDB.WOQL.RDFList.rdflist_nth0("v:List", 2, "v:Elem")
    iex> q.op
    :and

# `rdflist_nth1`

```elixir
@spec rdflist_nth1(woql_var(), pos_integer() | woql_var(), woql_var()) :: woql_query()
```

Gets the element at a 1-indexed position.

## Examples

    iex> q = TerminusDB.WOQL.RDFList.rdflist_nth1("v:List", 3, "v:Elem")
    iex> q.op
    :and

# `rdflist_peek`

```elixir
@spec rdflist_peek(woql_var(), woql_var()) :: woql_query()
```

Gets the first element (rdf:first) of an rdf:List.

## Examples

    iex> q = TerminusDB.WOQL.RDFList.rdflist_peek("v:List", "v:First")
    iex> q.op
    :triple

# `rdflist_pop`

```elixir
@spec rdflist_pop(woql_var(), woql_var()) :: woql_query()
```

Pops the first element in-place (deletes the head cell).

## Examples

    iex> q = TerminusDB.WOQL.RDFList.rdflist_pop("v:List", "v:Value")
    iex> q.op
    :and

# `rdflist_push`

```elixir
@spec rdflist_push(woql_var(), woql_var(), woql_var()) :: woql_query()
```

Pushes a value to the front of the list, returning the new head cell.

The caller must update their reference to the new head cell. The original
list is not modified — the new cell's `rdf:rest` points to the original
list head.

## Examples

    iex> q = TerminusDB.WOQL.RDFList.rdflist_push("v:List", "v:Value", "v:NewHead")
    iex> q.op
    :and

# `rdflist_slice`

```elixir
@spec rdflist_slice(
  woql_var(),
  non_neg_integer() | woql_var(),
  non_neg_integer() | woql_var(),
  woql_var()
) :: woql_query()
```

Extracts a slice [start, end) as an array.

## Examples

    iex> q = TerminusDB.WOQL.RDFList.rdflist_slice("v:List", 0, 3, "v:Result")
    iex> q.op
    :and

# `rdflist_swap`

```elixir
@spec rdflist_swap(
  woql_var(),
  non_neg_integer() | woql_var(),
  non_neg_integer() | woql_var()
) :: woql_query()
```

Swaps elements at two positions.

## Examples

    iex> q = TerminusDB.WOQL.RDFList.rdflist_swap("v:List", 0, 2)
    iex> q.op
    :and

---

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