Tuple

Functions for working with tuples.

Tuples are ordered collection of elements; tuples can contain elements of any type, and a tuple can contain elements of different types. Curly braces can be used to create tuples:

iex> {}
{}
iex> {1, :two, "three"}
{1, :two, "three"}

Tuples store elements contiguously in memory; this means that accessing a tuple element by index (which can be done through the Kernel.elem/2 function) is a constant-time operation:

iex> tuple = {1, :two, "three"}
iex> elem(tuple, 0)
1
iex> elem(tuple, 2)
"three"

Same goes for getting the tuple size (via Kernel.tuple_size/1):

iex> tuple_size({})
0
iex> tuple_size({1, 2, 3})
3

Tuples being stored contiguously in memory also means that updating a tuple (for example replacing an element with Kernel.put_elem/3) will make a copy of the whole tuple.

Tuples are not meant to be used as a “collection” type (which is also suggested by the absence of an implementation of the Enumerable protocol for tuples): they’re mostly meant to be used as a fixed-size container for multiple elements. For example, tuples are often used to have functions return “enriched” values: a common pattern is for functions to return {:ok, value} for successful cases and {:error, reason} for unsuccessful cases. For example, this is exactly what File.read/1 does: it returns {:ok, contents} if reading the given file is successful, or {:error, reason} otherwise (e.g., {:error, :enoent} if the file doesn’t exist).

This module provides functions to work with tuples; some more functions to work with tuples can be found in Kernel (Kernel.tuple_size/1, Kernel.elem/2, Kernel.put_elem/3, and others).

Summary

Functions

append(tuple, value)

Inserts an element at the end of a tuple

delete_at(tuple, index)

Removes an element from a tuple

duplicate(data, size)

Creates a new tuple

insert_at(tuple, index, value)

Inserts an element into a tuple

to_list(tuple)

Converts a tuple to a list

Functions

append(tuple, value)

append(tuple(), term()) :: tuple()

Inserts an element at the end of a tuple.

Returns a new tuple with the element appended at the end, and contains the elements in tuple followed by value as the last element.

Inlined by the compiler.

Examples

iex> tuple = {:foo, :bar}
iex> Tuple.append(tuple, :baz)
{:foo, :bar, :baz}

delete_at(tuple, index)

delete_at(tuple(), non_neg_integer()) :: tuple()

Removes an element from a tuple.

Deletes the element at the given index from tuple. Raises an ArgumentError if index is negative or greater than or equal to the length of tuple. Index is zero-based.

Inlined by the compiler.

Examples

iex> tuple = {:foo, :bar, :baz}
iex> Tuple.delete_at(tuple, 0)
{:bar, :baz}

duplicate(data, size)

duplicate(term(), non_neg_integer()) :: tuple()

Creates a new tuple.

Creates a tuple of size containing the given data at every position.

Inlined by the compiler.

Examples

iex> Tuple.duplicate(:hello, 3)
{:hello, :hello, :hello}

insert_at(tuple, index, value)

insert_at(tuple(), non_neg_integer(), term()) :: tuple()

Inserts an element into a tuple.

Inserts value into tuple at the given index. Raises an ArgumentError if index is negative or greater than the length of tuple. Index is zero-based.

Inlined by the compiler.

Examples

iex> tuple = {:bar, :baz}
iex> Tuple.insert_at(tuple, 0, :foo)
{:foo, :bar, :baz}
iex> Tuple.insert_at(tuple, 2, :bong)
{:bar, :baz, :bong}

to_list(tuple)

to_list(tuple()) :: list()

Converts a tuple to a list.

Returns a new list with all the tuple elements.

Inlined by the compiler.

Examples

iex> tuple = {:foo, :bar, :baz}
iex> Tuple.to_list(tuple)
[:foo, :bar, :baz]