Kernel

Kernel is Elixir's default environment.

It mainly consists of:

  • basic language primitives, such as arithmetic operators, spawning of processes, data type handling, etc.
  • macros for control-flow and defining new functionality (modules, functions, and so on)
  • guard checks for augmenting pattern matching

You can use Kernel functions/macros without the Kernel prefix anywhere in Elixir code as all its functions and macros are automatically imported. For example, in IEx:

iex> is_number(13)
true

If you don't want to import a function or macro from Kernel, use the :except option and then list the function/macro by arity:

import Kernel, except: [if: 2, unless: 2]

See Kernel.SpecialForms.import/2 for more information on importing.

Elixir also has special forms that are always imported and cannot be skipped. These are described in Kernel.SpecialForms.

The standard library

Kernel provides the basic capabilities the Elixir standard library is built on top of. It is recommended to explore the standard library for advanced functionality. Here are the main groups of modules in the standard library (this list is not a complete reference, see the documentation sidebar for all entries).

Built-in types

The following modules handle Elixir built-in data types:

  • Atom - literal constants with a name (true, false, and nil are atoms)
  • Float - numbers with floating point precision
  • Function - a reference to code chunk, created with the fn/1 special form
  • Integer - whole numbers (not fractions)
  • List - collections of a variable number of elements (linked lists)
  • Map - collections of key-value pairs
  • Process - light-weight threads of execution
  • Port - mechanisms to interact with the external world
  • Tuple - collections of a fixed number of elements

There are two data types without an accompanying module:

  • Bitstring - a sequence of bits, created with Kernel.SpecialForms.<<>>/1. When the number of bits is divisible by 8, they are called binaries and can be manipulated with Erlang's :binary module
  • Reference - a unique value in the runtime system, created with make_ref/0

Data types

Elixir also provides other data types that are built on top of the types listed above. Some of them are:

  • Date - year-month-day structs in a given calendar
  • DateTime - date and time with time zone in a given calendar
  • Exception - data raised from errors and unexpected scenarios
  • MapSet - unordered collections of unique elements
  • NaiveDateTime - date and time without time zone in a given calendar
  • Keyword - lists of two-element tuples, often representing optional values
  • Range - inclusive ranges between two integers
  • Regex - regular expressions
  • String - UTF-8 encoded binaries representing characters
  • Time - hour:minute:second structs in a given calendar
  • URI - representation of URIs that identify resources
  • Version - representation of versions and requirements

System modules

Modules that interface with the underlying system, such as:

  • IO - handles input and output
  • File - interacts with the underlying file system
  • Path - manipulates file system paths
  • System - reads and writes system information

Protocols

Protocols add polymorphic dispatch to Elixir. They are contracts implementable by data types. See defprotocol/2 for more information on protocols. Elixir provides the following protocols in the standard library:

  • Collectable - collects data into a data type
  • Enumerable - handles collections in Elixir. The Enum module provides eager functions for working with collections, the Stream module provides lazy functions
  • Inspect - converts data types into their programming language representation
  • List.Chars - converts data types to their outside world representation as charlists (non-programming based)
  • String.Chars - converts data types to their outside world representation as strings (non-programming based)

Process-based and application-centric functionality

The following modules build on top of processes to provide concurrency, fault-tolerance, and more.

  • Agent - a process that encapsulates mutable state
  • Application - functions for starting, stopping and configuring applications
  • GenServer - a generic client-server API
  • Registry - a key-value process-based storage
  • Supervisor - a process that is responsible for starting, supervising and shutting down other processes
  • Task - a process that performs computations
  • Task.Supervisor - a supervisor for managing tasks exclusively

Supporting documents

Elixir documentation also includes supporting documents under the "Pages" section. Those are:

Guards

This module includes the built-in guards used by Elixir developers. They are a predefined set of functions and macros that augment pattern matching, typically invoked after the when operator. For example:

def drive(%User{age: age}) when age >= 16 do
  ...
end

The clause above will only be invoked if the user's age is more than or equal to 16. A more complete introduction to guards is available in the Guards page.

Inlining

Some of the functions described in this module are inlined by the Elixir compiler into their Erlang counterparts in the :erlang module. Those functions are called BIFs (built-in internal functions) in Erlang-land and they exhibit interesting properties, as some of them are allowed in guards and others are used for compiler optimizations.

Most of the inlined functions can be seen in effect when capturing the function:

iex> &Kernel.is_atom/1
&:erlang.is_atom/1

Those functions will be explicitly marked in their docs as "inlined by the compiler".

Summary

Guards

left != right

Returns true if the two items are not equal.

left !== right

Returns true if the two items are not exactly equal.

left * right

Arithmetic multiplication.

+value

Arithmetic unary plus.

left + right

Arithmetic addition.

-value

Arithmetic unary minus.

left - right

Arithmetic subtraction.

left / right

Arithmetic division.

left < right

Returns true if left is less than right.

left <= right

Returns true if left is less than or equal to right.

left == right

Returns true if the two items are equal.

left === right

Returns true if the two items are exactly equal.

left > right

Returns true if left is more than right.

left >= right

Returns true if left is more than or equal to right.

abs(number)

Returns an integer or float which is the arithmetical absolute value of number.

left and right

Boolean and.

binary_part(binary, start, length)

Extracts the part of the binary starting at start with length length. Binaries are zero-indexed.

bit_size(bitstring)

Returns an integer which is the size in bits of bitstring.

byte_size(bitstring)

Returns the number of bytes needed to contain bitstring.

ceil(number)

Returns the smallest integer not greater than number.

div(dividend, divisor)

Performs an integer division.

elem(tuple, index)

Gets the element at the zero-based index in tuple.

floor(number)

Returns the largest integer not greater than number.

hd(list)

Returns the head of a list. Raises ArgumentError if the list is empty.

left in right

Checks if the element on the left-hand side is a member of the collection on the right-hand side.

is_atom(term)

Returns true if term is an atom; otherwise returns false.

is_binary(term)

Returns true if term is a binary; otherwise returns false.

is_bitstring(term)

Returns true if term is a bitstring (including a binary); otherwise returns false.

is_boolean(term)

Returns true if term is either the atom true or the atom false (i.e., a boolean); otherwise returns false.

is_float(term)

Returns true if term is a floating-point number; otherwise returns false.

is_function(term)

Returns true if term is a function; otherwise returns false.

is_function(term, arity)

Returns true if term is a function that can be applied with arity number of arguments; otherwise returns false.

is_integer(term)

Returns true if term is an integer; otherwise returns false.

is_list(term)

Returns true if term is a list with zero or more elements; otherwise returns false.

is_map(term)

Returns true if term is a map; otherwise returns false.

is_nil(term)

Returns true if term is nil, false otherwise.

is_number(term)

Returns true if term is either an integer or a floating-point number; otherwise returns false.

is_pid(term)

Returns true if term is a PID (process identifier); otherwise returns false.

is_port(term)

Returns true if term is a port identifier; otherwise returns false.

is_reference(term)

Returns true if term is a reference; otherwise returns false.

is_tuple(term)

Returns true if term is a tuple; otherwise returns false.

length(list)

Returns the length of list.

map_size(map)

Returns the size of a map.

node()

Returns an atom representing the name of the local node. If the node is not alive, :nonode@nohost is returned instead.

node(arg)

Returns the node where the given argument is located. The argument can be a PID, a reference, or a port. If the local node is not alive, :nonode@nohost is returned.

not(value)

Boolean not.

left or right

Boolean or.

rem(dividend, divisor)

Computes the remainder of an integer division.

round(number)

Rounds a number to the nearest integer.

self()

Returns the PID (process identifier) of the calling process.

tl(list)

Returns the tail of a list. Raises ArgumentError if the list is empty.

trunc(number)

Returns the integer part of number.

tuple_size(tuple)

Returns the size of a tuple.

Functions

!value

Boolean not.

left && right

Provides a short-circuit operator that evaluates and returns the second expression only if the first one evaluates to to a truthy value (neither false nor nil). Returns the first expression otherwise.

left ++ right

Concatenates a proper list and a term, returning a list.

left -- right

Removes the first occurrence of an item on the left list for each item on the right.

first..last

Returns a range with the specified first and last integers.

left <> right

Concatenates two binaries.

left =~ right

Matches the term on the left against the regular expression or string on the right.

@expr

Reads and writes attributes of the current module.

alias!(alias)

When used inside quoting, marks that the given alias should not be hygienized. This means the alias will be expanded when the macro is expanded.

apply(fun, args)

Invokes the given anonymous function fun with the list of arguments args.

apply(module, function_name, args)

Invokes the given function from module with the list of arguments args.

binding(context \\ nil)

Returns the binding for the given context as a keyword list.

def(call, expr \\ nil)

Defines a function with the given name and body.

defdelegate(funs, opts)

Defines a function that delegates to another module.

defexception(fields)

Defines an exception.

defguard(guard)

Generates a macro suitable for use in guard expressions.

defguardp(guard)

Generates a private macro suitable for use in guard expressions.

defimpl(name, opts, do_block \\ [])

Defines an implementation for the given protocol.

defmacro(call, expr \\ nil)

Defines a macro with the given name and body.

defmacrop(call, expr \\ nil)

Defines a private macro with the given name and body.

defmodule(alias, do_block)

Defines a module given by name with the given contents.

defoverridable(keywords_or_behaviour)

Makes the given functions in the current module overridable.

defp(call, expr \\ nil)

Defines a private function with the given name and body.

defprotocol(name, do_block)

Defines a protocol.

defstruct(fields)

Defines a struct.

destructure(left, right)

Destructures two lists, assigning each term in the right one to the matching term in the left one.

exit(reason)

Stops the execution of the calling process with the given reason.

function_exported?(module, function, arity)

Returns true if module is loaded and contains a public function with the given arity, otherwise false.

get_and_update_in(path, fun)

Gets a value and updates a nested data structure via the given path.

get_and_update_in(data, keys, fun)

Gets a value and updates a nested structure.

get_in(data, keys)

Gets a value from a nested structure.

if(condition, clauses)

Provides an if/2 macro.

inspect(term, opts \\ [])

Inspects the given argument according to the Inspect protocol. The second argument is a keyword list with options to control inspection.

macro_exported?(module, macro, arity)

Returns true if module is loaded and contains a public macro with the given arity, otherwise false.

make_ref()

Returns an almost unique reference.

match?(pattern, expr)

A convenience macro that checks if the right side (an expression) matches the left side (a pattern).

max(first, second)

Returns the biggest of the two given terms according to Erlang's term ordering.

min(first, second)

Returns the smallest of the two given terms according to Erlang's term ordering.

pop_in(path)

Pops a key from the nested structure via the given path.

pop_in(data, keys)

Pops a key from the given nested structure.

put_elem(tuple, index, value)

Puts value at the given zero-based index in tuple.

put_in(path, value)

Puts a value in a nested structure via the given path.

put_in(data, keys, value)

Puts a value in a nested structure.

raise(message)

Raises an exception.

raise(exception, attributes)

Raises an exception.

reraise(message, stacktrace)

Raises an exception preserving a previous stacktrace.

reraise(exception, attributes, stacktrace)

Raises an exception preserving a previous stacktrace.

send(dest, message)

Sends a message to the given dest and returns the message.

sigil_C(term, modifiers)

Handles the sigil ~C for charlists.

sigil_D(date_string, modifiers)

Handles the sigil ~D for dates.

sigil_N(naive_datetime_string, modifiers)

Handles the sigil ~N for naive date times.

sigil_R(term, modifiers)

Handles the sigil ~R for regular expressions.

sigil_S(term, modifiers)

Handles the sigil ~S for strings.

sigil_T(time_string, modifiers)

Handles the sigil ~T for times.

sigil_W(term, modifiers)

Handles the sigil ~W for list of words.

sigil_c(term, modifiers)

Handles the sigil ~c for charlists.

sigil_r(term, modifiers)

Handles the sigil ~r for regular expressions.

sigil_s(term, modifiers)

Handles the sigil ~s for strings.

sigil_w(term, modifiers)

Handles the sigil ~w for list of words.

spawn(fun)

Spawns the given function and returns its PID.

spawn(module, fun, args)

Spawns the given function fun from the given module passing it the given args and returns its PID.

spawn_link(fun)

Spawns the given function, links it to the current process, and returns its PID.

spawn_link(module, fun, args)

Spawns the given function fun from the given module passing it the given args, links it to the current process, and returns its PID.

spawn_monitor(fun)

Spawns the given function, monitors it and returns its PID and monitoring reference.

spawn_monitor(module, fun, args)

Spawns the given module and function passing the given args, monitors it and returns its PID and monitoring reference.

struct(struct, fields \\ [])

Creates and updates structs.

struct!(struct, fields \\ [])

Similar to struct/2 but checks for key validity.

throw(term)

A non-local return from a function.

to_charlist(term)

Converts the given term to a charlist according to the List.Chars protocol.

to_string(term)

Converts the argument to a string according to the String.Chars protocol.

unless(condition, clauses)

Provides an unless macro.

update_in(path, fun)

Updates a nested structure via the given path.

update_in(data, keys, fun)

Updates a key in a nested structure.

use(module, opts \\ [])

Uses the given module in the current context.

var!(var, context \\ nil)

When used inside quoting, marks that the given variable should not be hygienized.

left |> right

Pipe operator.

left || right

Provides a short-circuit operator that evaluates and returns the second expression only if the first one does not evaluate to a truthy value (that is, it is either nil or false). Returns the first expression otherwise.

Guards

left != right

term() != term() :: boolean()

Returns true if the two items are not equal.

This operator considers 1 and 1.0 to be equal. For match comparison, use !==/2 instead.

All terms in Elixir can be compared with each other.

Allowed in guard tests. Inlined by the compiler.

Examples

iex> 1 != 2
true

iex> 1 != 1.0
false

left !== right

term() !== term() :: boolean()

Returns true if the two items are not exactly equal.

All terms in Elixir can be compared with each other.

Allowed in guard tests. Inlined by the compiler.

Examples

iex> 1 !== 2
true

iex> 1 !== 1.0
true

left * right

integer() * integer() :: integer()
float() * float() :: float()
integer() * float() :: float()
float() * integer() :: float()

Arithmetic multiplication.

Allowed in guard tests. Inlined by the compiler.

Examples

iex> 1 * 2
2

+value

+value :: value when value: number()

Arithmetic unary plus.

Allowed in guard tests. Inlined by the compiler.

Examples

iex> +1
1

left + right

integer() + integer() :: integer()
float() + float() :: float()
integer() + float() :: float()
float() + integer() :: float()

Arithmetic addition.

Allowed in guard tests. Inlined by the compiler.

Examples

iex> 1 + 2
3

-value

-0 :: 0
-pos_integer() :: neg_integer()
-neg_integer() :: pos_integer()
-float() :: float()

Arithmetic unary minus.

Allowed in guard tests. Inlined by the compiler.

Examples

iex> -2
-2

left - right

integer() - integer() :: integer()
float() - float() :: float()
integer() - float() :: float()
float() - integer() :: float()

Arithmetic subtraction.

Allowed in guard tests. Inlined by the compiler.

Examples

iex> 1 - 2
-1

left / right

number() / number() :: float()

Arithmetic division.

The result is always a float. Use div/2 and rem/2 if you want an integer division or the remainder.

Raises ArithmeticError if right is 0 or 0.0.

Allowed in guard tests. Inlined by the compiler.

Examples

1 / 2
#=> 0.5

-3.0 / 2.0
#=> -1.5

5 / 1
#=> 5.0

7 / 0
#=> ** (ArithmeticError) bad argument in arithmetic expression

left < right

term() < term() :: boolean()

Returns true if left is less than right.

All terms in Elixir can be compared with each other.

Allowed in guard tests. Inlined by the compiler.

Examples

iex> 1 < 2
true

left <= right

term() <= term() :: boolean()

Returns true if left is less than or equal to right.

All terms in Elixir can be compared with each other.

Allowed in guard tests. Inlined by the compiler.

Examples

iex> 1 <= 2
true

left == right

term() == term() :: boolean()

Returns true if the two items are equal.

This operator considers 1 and 1.0 to be equal. For stricter semantics, use ===/2 instead.

All terms in Elixir can be compared with each other.

Allowed in guard tests. Inlined by the compiler.

Examples

iex> 1 == 2
false

iex> 1 == 1.0
true

left === right

term() === term() :: boolean()

Returns true if the two items are exactly equal.

The items are only considered to be exactly equal if they have the same value and are of the same type. For example, 1 == 1.0 returns true, but since they are of different types, 1 === 1.0 returns false.

All terms in Elixir can be compared with each other.

Allowed in guard tests. Inlined by the compiler.

Examples

iex> 1 === 2
false

iex> 1 === 1.0
false

left > right

term() > term() :: boolean()

Returns true if left is more than right.

All terms in Elixir can be compared with each other.

Allowed in guard tests. Inlined by the compiler.

Examples

iex> 1 > 2
false

left >= right

term() >= term() :: boolean()

Returns true if left is more than or equal to right.

All terms in Elixir can be compared with each other.

Allowed in guard tests. Inlined by the compiler.

Examples

iex> 1 >= 2
false

abs(number)

abs(number()) :: number()

Returns an integer or float which is the arithmetical absolute value of number.

Allowed in guard tests. Inlined by the compiler.

Examples

iex> abs(-3.33)
3.33

iex> abs(-3)
3

left and right

(macro)

Boolean and.

If left is false, returns false; otherwise returns right.

Requires only the left operand to be a boolean since it short-circuits. If the left operand is not a boolean, an ArgumentError exception is raised.

Allowed in guard tests.

Examples

iex> true and false
false
iex> true and "yay!"
"yay!"

binary_part(binary, start, length)

binary_part(binary(), non_neg_integer(), integer()) :: binary()

Extracts the part of the binary starting at start with length length. Binaries are zero-indexed.

If start or length reference in any way outside the binary, an ArgumentError exception is raised.

Allowed in guard tests. Inlined by the compiler.

Examples

iex> binary_part("foo", 1, 2)
"oo"

A negative length can be used to extract bytes that come before the byte at start:

iex> binary_part("Hello", 5, -3)
"llo"

bit_size(bitstring)

bit_size(bitstring()) :: non_neg_integer()

Returns an integer which is the size in bits of bitstring.

Allowed in guard tests. Inlined by the compiler.

Examples

iex> bit_size(<<433::16, 3::3>>)
19

iex> bit_size(<<1, 2, 3>>)
24

byte_size(bitstring)

byte_size(bitstring()) :: non_neg_integer()

Returns the number of bytes needed to contain bitstring.

That is, if the number of bits in bitstring is not divisible by 8, the resulting number of bytes will be rounded up (by excess). This operation happens in constant time.

Allowed in guard tests. Inlined by the compiler.

Examples

iex> byte_size(<<433::16, 3::3>>)
3

iex> byte_size(<<1, 2, 3>>)
3

ceil(number)

(since 1.8.0)
ceil(number()) :: integer()

Returns the smallest integer not greater than number.

If you want to perform ceil operation on other decimal places, use Float.ceil/2 instead.

Allowed in guard tests. Inlined by the compiler.

div(dividend, divisor)

div(integer(), neg_integer() | pos_integer()) :: integer()

Performs an integer division.

Raises an ArithmeticError exception if one of the arguments is not an integer, or when the divisor is 0.

div/2 performs truncated integer division. This means that the result is always rounded towards zero.

If you want to perform floored integer division (rounding towards negative infinity), use Integer.floor_div/2 instead.

Allowed in guard tests. Inlined by the compiler.

Examples

div(5, 2)
#=> 2

div(6, -4)
#=> -1

div(-99, 2)
#=> -49

div(100, 0)
#=> ** (ArithmeticError) bad argument in arithmetic expression

elem(tuple, index)

elem(tuple(), non_neg_integer()) :: term()

Gets the element at the zero-based index in tuple.

It raises ArgumentError when index is negative or it is out of range of the tuple elements.

Allowed in guard tests. Inlined by the compiler.

Examples

tuple = {:foo, :bar, 3}
elem(tuple, 1)
#=> :bar

elem({}, 0)
#=> ** (ArgumentError) argument error

elem({:foo, :bar}, 2)
#=> ** (ArgumentError) argument error

floor(number)

(since 1.8.0)
floor(number()) :: integer()

Returns the largest integer not greater than number.

If you want to perform floor operation on other decimal places, use Float.floor/2 instead.

Allowed in guard tests. Inlined by the compiler.

hd(list)

hd(nonempty_maybe_improper_list(elem, any())) :: elem when elem: term()

Returns the head of a list. Raises ArgumentError if the list is empty.

It works with improper lists.

Allowed in guard tests. Inlined by the compiler.

Examples

hd([1, 2, 3, 4])
#=> 1

hd([])
#=> ** (ArgumentError) argument error

hd([1 | 2])
#=> 1

left in right

(macro)

Checks if the element on the left-hand side is a member of the collection on the right-hand side.

Examples

iex> x = 1
iex> x in [1, 2, 3]
true

This operator (which is a macro) simply translates to a call to Enum.member?/2. The example above would translate to:

Enum.member?([1, 2, 3], x)

Elixir also supports left not in right, which evaluates to not(left in right):

iex> x = 1
iex> x not in [1, 2, 3]
false

Guards

The in/2 operator (as well as not in) can be used in guard clauses as long as the right-hand side is a range or a list. In such cases, Elixir will expand the operator to a valid guard expression. For example:

when x in [1, 2, 3]

translates to:

when x === 1 or x === 2 or x === 3

When using ranges:

when x in 1..3

translates to:

when is_integer(x) and x >= 1 and x <= 3

Note that only integers can be considered inside a range by in.

AST considerations

left not in right is parsed by the compiler into the AST:

{:not, _, [{:in, _, [left, right]}]}

This is the same AST as not(left in right).

Additionally, Macro.to_string/2 will translate all occurrences of this AST to left not in right.

is_atom(term)

is_atom(term()) :: boolean()

Returns true if term is an atom; otherwise returns false.

Allowed in guard tests. Inlined by the compiler.

is_binary(term)

is_binary(term()) :: boolean()

Returns true if term is a binary; otherwise returns false.

A binary always contains a complete number of bytes.

Allowed in guard tests. Inlined by the compiler.

Examples

iex> is_binary("foo")
true
iex> is_binary(<<1::3>>)
false

is_bitstring(term)

is_bitstring(term()) :: boolean()

Returns true if term is a bitstring (including a binary); otherwise returns false.

Allowed in guard tests. Inlined by the compiler.

Examples

iex> is_bitstring("foo")
true
iex> is_bitstring(<<1::3>>)
true

is_boolean(term)

is_boolean(term()) :: boolean()

Returns true if term is either the atom true or the atom false (i.e., a boolean); otherwise returns false.

Allowed in guard tests. Inlined by the compiler.

is_float(term)

is_float(term()) :: boolean()

Returns true if term is a floating-point number; otherwise returns false.

Allowed in guard tests. Inlined by the compiler.

is_function(term)

is_function(term()) :: boolean()

Returns true if term is a function; otherwise returns false.

Allowed in guard tests. Inlined by the compiler.

is_function(term, arity)

is_function(term(), non_neg_integer()) :: boolean()

Returns true if term is a function that can be applied with arity number of arguments; otherwise returns false.

Allowed in guard tests. Inlined by the compiler.

Examples

iex> is_function(fn x -> x * 2 end, 1)
true
iex> is_function(fn x -> x * 2 end, 2)
false

is_integer(term)

is_integer(term()) :: boolean()

Returns true if term is an integer; otherwise returns false.

Allowed in guard tests. Inlined by the compiler.

is_list(term)

is_list(term()) :: boolean()

Returns true if term is a list with zero or more elements; otherwise returns false.

Allowed in guard tests. Inlined by the compiler.

is_map(term)

is_map(term()) :: boolean()

Returns true if term is a map; otherwise returns false.

Allowed in guard tests. Inlined by the compiler.

is_nil(term)

(macro)

Returns true if term is nil, false otherwise.

Allowed in guard clauses.

Examples

iex> is_nil(1)
false

iex> is_nil(nil)
true

is_number(term)

is_number(term()) :: boolean()

Returns true if term is either an integer or a floating-point number; otherwise returns false.

Allowed in guard tests. Inlined by the compiler.

is_pid(term)

is_pid(term()) :: boolean()

Returns true if term is a PID (process identifier); otherwise returns false.

Allowed in guard tests. Inlined by the compiler.

is_port(term)

is_port(term()) :: boolean()

Returns true if term is a port identifier; otherwise returns false.

Allowed in guard tests. Inlined by the compiler.

is_reference(term)

is_reference(term()) :: boolean()

Returns true if term is a reference; otherwise returns false.

Allowed in guard tests. Inlined by the compiler.

is_tuple(term)

is_tuple(term()) :: boolean()

Returns true if term is a tuple; otherwise returns false.

Allowed in guard tests. Inlined by the compiler.

length(list)

length(list()) :: non_neg_integer()

Returns the length of list.

Allowed in guard tests. Inlined by the compiler.

Examples

iex> length([1, 2, 3, 4, 5, 6, 7, 8, 9])
9

map_size(map)

map_size(map()) :: non_neg_integer()

Returns the size of a map.

The size of a map is the number of key-value pairs that the map contains.

This operation happens in constant time.

Allowed in guard tests. Inlined by the compiler.

Examples

iex> map_size(%{a: "foo", b: "bar"})
2

node()

node() :: node()

Returns an atom representing the name of the local node. If the node is not alive, :nonode@nohost is returned instead.

Allowed in guard tests. Inlined by the compiler.

node(arg)

node(pid() | reference() | port()) :: node()

Returns the node where the given argument is located. The argument can be a PID, a reference, or a port. If the local node is not alive, :nonode@nohost is returned.

Allowed in guard tests. Inlined by the compiler.

not(value)

not true :: false
not false :: true

Boolean not.

arg must be a boolean; if it's not, an ArgumentError exception is raised.

Allowed in guard tests. Inlined by the compiler.

Examples

iex> not false
true

left or right

(macro)

Boolean or.

If left is true, returns true; otherwise returns right.

Requires only the left operand to be a boolean since it short-circuits. If the left operand is not a boolean, an ArgumentError exception is raised.

Allowed in guard tests.

Examples

iex> true or false
true
iex> false or 42
42

rem(dividend, divisor)

rem(integer(), neg_integer() | pos_integer()) :: integer()

Computes the remainder of an integer division.

rem/2 uses truncated division, which means that the result will always have the sign of the dividend.

Raises an ArithmeticError exception if one of the arguments is not an integer, or when the divisor is 0.

Allowed in guard tests. Inlined by the compiler.

Examples

iex> rem(5, 2)
1
iex> rem(6, -4)
2

round(number)

round(float()) :: integer()
round(value) :: value when value: integer()

Rounds a number to the nearest integer.

Allowed in guard tests. Inlined by the compiler.

Examples

iex> round(5.6)
6

iex> round(5.2)
5

iex> round(-9.9)
-10

iex> round(-9)
-9

self()

self() :: pid()

Returns the PID (process identifier) of the calling process.

Allowed in guard clauses. Inlined by the compiler.

tl(list)

tl(nonempty_maybe_improper_list(elem, tail)) ::
  maybe_improper_list(elem, tail) | tail
when elem: term(), tail: term()

Returns the tail of a list. Raises ArgumentError if the list is empty.

It works with improper lists.

Allowed in guard tests. Inlined by the compiler.

Examples

tl([1, 2, 3, :go])
#=> [2, 3, :go]

tl([])
#=> ** (ArgumentError) argument error

tl([:one])
#=> []

tl([:a, :b | :c])
#=> [:b | :c]

tl([:a | %{b: 1}])
#=> %{b: 1}

trunc(number)

trunc(value) :: value when value: integer()
trunc(float()) :: integer()

Returns the integer part of number.

Allowed in guard tests. Inlined by the compiler.

Examples

iex> trunc(5.4)
5

iex> trunc(-5.99)
-5

iex> trunc(-5)
-5

tuple_size(tuple)

tuple_size(tuple()) :: non_neg_integer()

Returns the size of a tuple.

This operation happens in constant time.

Allowed in guard tests. Inlined by the compiler.

Examples

iex> tuple_size({:a, :b, :c})
3

Functions

!value

(macro)

Boolean not.

Receives any argument (not just booleans) and returns true if the argument is false or nil; returns false otherwise.

Not allowed in guard clauses.

Examples

iex> !Enum.empty?([])
false

iex> !List.first([])
true

left && right

(macro)

Provides a short-circuit operator that evaluates and returns the second expression only if the first one evaluates to to a truthy value (neither false nor nil). Returns the first expression otherwise.

Not allowed in guard clauses.

Examples

iex> Enum.empty?([]) && Enum.empty?([])
true

iex> List.first([]) && true
nil

iex> Enum.empty?([]) && List.first([1])
1

iex> false && throw(:bad)
false

Note that, unlike and/2, this operator accepts any expression as the first argument, not only booleans.

left ++ right

list() ++ term() :: maybe_improper_list()

Concatenates a proper list and a term, returning a list.

The complexity of a ++ b is proportional to length(a), so avoid repeatedly appending to lists of arbitrary length, e.g. list ++ [item]. Instead, consider prepending via [item | rest] and then reversing.

If the right operand is not a proper list, it returns an improper list. If the left operand is not a proper list, it raises ArgumentError.

Inlined by the compiler.

Examples

iex> [1] ++ [2, 3]
[1, 2, 3]

iex> 'foo' ++ 'bar'
'foobar'

# returns an improper list
iex> [1] ++ 2
[1 | 2]

# returns a proper list
iex> [1] ++ [2]
[1, 2]

# improper list on the right will return an improper list
iex> [1] ++ [2 | 3]
[1, 2 | 3]

left -- right

list() -- list() :: list()

Removes the first occurrence of an item on the left list for each item on the right.

The complexity of a -- b is proportional to length(a) * length(b), meaning that it will be very slow if both a and b are long lists. In such cases, consider converting each list to a MapSet and using MapSet.difference/2.

Inlined by the compiler.

Examples

iex> [1, 2, 3] -- [1, 2]
[3]

iex> [1, 2, 3, 2, 1] -- [1, 2, 2]
[3, 1]

first..last

(macro)

Returns a range with the specified first and last integers.

If last is larger than first, the range will be increasing from first to last. If first is larger than last, the range will be decreasing from first to last. If first is equal to last, the range will contain one element, which is the number itself.

Examples

iex> 0 in 1..3
false

iex> 1 in 1..3
true

iex> 2 in 1..3
true

iex> 3 in 1..3
true

left <> right

(macro)

Concatenates two binaries.

Examples

iex> "foo" <> "bar"
"foobar"

The <>/2 operator can also be used in pattern matching (and guard clauses) as long as the left argument is a literal binary:

iex> "foo" <> x = "foobar"
iex> x
"bar"

x <> "bar" = "foobar" would have resulted in a CompileError exception.

left =~ right

String.t() =~ (String.t() | Regex.t()) :: boolean()

Matches the term on the left against the regular expression or string on the right.

Returns true if left matches right (if it's a regular expression) or contains right (if it's a string).

Examples

iex> "abcd" =~ ~r/c(d)/
true

iex> "abcd" =~ ~r/e/
false

iex> "abcd" =~ "bc"
true

iex> "abcd" =~ "ad"
false

iex> "abcd" =~ ""
true

@expr

(macro)

Reads and writes attributes of the current module.

The canonical example for attributes is annotating that a module implements an OTP behaviour, such as GenServer:

defmodule MyServer do
  @behaviour GenServer
  # ... callbacks ...
end

By default Elixir supports all the module attributes supported by Erlang, but custom attributes can be used as well:

defmodule MyServer do
  @my_data 13
  IO.inspect(@my_data) #=> 13
end

Unlike Erlang, such attributes are not stored in the module by default since it is common in Elixir to use custom attributes to store temporary data that will be available at compile-time. Custom attributes may be configured to behave closer to Erlang by using Module.register_attribute/3.

Finally, notice that attributes can also be read inside functions:

defmodule MyServer do
  @my_data 11
  def first_data, do: @my_data
  @my_data 13
  def second_data, do: @my_data
end

MyServer.first_data()
#=> 11

MyServer.second_data()
#=> 13

It is important to note that reading an attribute takes a snapshot of its current value. In other words, the value is read at compilation time and not at runtime. Check the Module module for other functions to manipulate module attributes.

alias!(alias)

(macro)

When used inside quoting, marks that the given alias should not be hygienized. This means the alias will be expanded when the macro is expanded.

Check Kernel.SpecialForms.quote/2 for more information.

apply(fun, args)

apply((... -> any()), [any()]) :: any()

Invokes the given anonymous function fun with the list of arguments args.

Inlined by the compiler.

Examples

iex> apply(fn x -> x * 2 end, [2])
4

apply(module, function_name, args)

apply(module(), function_name :: atom(), [any()]) :: any()

Invokes the given function from module with the list of arguments args.

apply/3 is used to invoke functions where the module, function name or arguments are defined dynamically at runtime. For this reason, you can't invoke macros using apply/3, only functions.

Inlined by the compiler.

Examples

iex> apply(Enum, :reverse, [[1, 2, 3]])
[3, 2, 1]

binding(context \\ nil)

(macro)

Returns the binding for the given context as a keyword list.

In the returned result, keys are variable names and values are the corresponding variable values.

If the given context is nil (by default it is), the binding for the current context is returned.

Examples

iex> x = 1
iex> binding()
[x: 1]
iex> x = 2
iex> binding()
[x: 2]

iex> binding(:foo)
[]
iex> var!(x, :foo) = 1
1
iex> binding(:foo)
[x: 1]

def(call, expr \\ nil)

(macro)

Defines a function with the given name and body.

Examples

defmodule Foo do
  def bar, do: :baz
end

Foo.bar()
#=> :baz

A function that expects arguments can be defined as follows:

defmodule Foo do
  def sum(a, b) do
    a + b
  end
end

In the example above, a sum/2 function is defined; this function receives two arguments and returns their sum.

Default arguments

\\ is used to specify a default value for a parameter of a function. For example:

defmodule MyMath do
  def multiply_by(number, factor \\ 2) do
    number * factor
  end
end

MyMath.multiply_by(4, 3)
#=> 12

MyMath.multiply_by(4)
#=> 8

The compiler translates this into multiple functions with different arities, here Foo.multiply_by/1 and Foo.multiply_by/2, that represent cases when arguments for parameters with default values are passed or not passed.

When defining a function with default arguments as well as multiple explicitly declared clauses, you must write a function head that declares the defaults. For example:

defmodule MyString do
  def join(string1, string2 \\ nil, separator \\ " ")

  def join(string1, nil, _separator) do
    string1
  end

  def join(string1, string2, separator) do
    string1 <> separator <> string2
  end
end

Note that \\ can't be used with anonymous functions because they can only have a sole arity.

Function and variable names

Function and variable names have the following syntax: A lowercase ASCII letter or an underscore, followed by any number of lowercase or uppercase ASCII letters, numbers, or underscores. Optionally they can end in either an exclamation mark or a question mark.

For variables, any identifier starting with an underscore should indicate an unused variable. For example:

def foo(bar) do
  []
end
#=> warning: variable bar is unused

def foo(_bar) do
  []
end
#=> no warning

def foo(_bar) do
  _bar
end
#=> warning: the underscored variable "_bar" is used after being set

rescue/catch/after/else

Function bodies support rescue, catch, after, and else as Kernel.SpecialForms.try/1 does. For example, the following two functions are equivalent:

def format(value) do
  try do
    format!(value)
  catch
    :exit, reason -> {:error, reason}
  end
end

def format(value) do
  format!(value)
catch
  :exit, reason -> {:error, reason}
end

defdelegate(funs, opts)

(macro)

Defines a function that delegates to another module.

Functions defined with defdelegate/2 are public and can be invoked from outside the module they're defined in (like if they were defined using def/2). When the desire is to delegate as private functions, import/2 should be used.

Delegation only works with functions; delegating macros is not supported.

Check def/2 for rules on naming and default arguments.

Options

  • :to - the module to dispatch to.

  • :as - the function to call on the target given in :to. This parameter is optional and defaults to the name being delegated (funs).

Examples

defmodule MyList do
  defdelegate reverse(list), to: Enum
  defdelegate other_reverse(list), to: Enum, as: :reverse
end

MyList.reverse([1, 2, 3])
#=> [3, 2, 1]

MyList.other_reverse([1, 2, 3])
#=> [3, 2, 1]

defexception(fields)

(macro)

Defines an exception.

Exceptions are structs backed by a module that implements the Exception behaviour. The Exception behaviour requires two functions to be implemented:

  • exception/1 - receives the arguments given to raise/2 and returns the exception struct. The default implementation accepts either a set of keyword arguments that is merged into the struct or a string to be used as the exception's message.

  • message/1 - receives the exception struct and must return its message. Most commonly exceptions have a message field which by default is accessed by this function. However, if an exception does not have a message field, this function must be explicitly implemented.

Since exceptions are structs, the API supported by defstruct/1 is also available in defexception/1.

Raising exceptions

The most common way to raise an exception is via raise/2:

defmodule MyAppError do
  defexception [:message]
end

value = [:hello]

raise MyAppError,
  message: "did not get what was expected, got: #{inspect(value)}"

In many cases it is more convenient to pass the expected value to raise/2 and generate the message in the Exception.exception/1 callback:

defmodule MyAppError do
  defexception [:message]

  @impl true
  def exception(value) do
    msg = "did not get what was expected, got: #{inspect(value)}"
    %MyAppError{message: msg}
  end
end

raise MyAppError, value

The example above shows the preferred strategy for customizing exception messages.

defguard(guard)

(macro)(since 1.6.0)
defguard(Macro.t()) :: Macro.t()

Generates a macro suitable for use in guard expressions.

It raises at compile time if the definition uses expressions that aren't allowed in guards, and otherwise creates a macro that can be used both inside or outside guards.

Note the convention in Elixir is to name functions/macros allowed in guards with the is_ prefix, such as is_list/1. If, however, the function/macro returns a boolean and is not allowed in guards, it should have no prefix and end with a question mark, such as Keyword.keyword?/1.

Example

defmodule Integer.Guards do
  defguard is_even(value) when is_integer(value) and rem(value, 2) == 0
end

defmodule Collatz do
  @moduledoc "Tools for working with the Collatz sequence."
  import Integer.Guards

  @doc "Determines the number of steps `n` takes to reach `1`."
  # If this function never converges, please let me know what `n` you used.
  def converge(n) when n > 0, do: step(n, 0)

  defp step(1, step_count) do
    step_count
  end

  defp step(n, step_count) when is_even(n) do
    step(div(n, 2), step_count + 1)
  end

  defp step(n, step_count) do
    step(3 * n + 1, step_count + 1)
  end
end

defguardp(guard)

(macro)(since 1.6.0)
defguardp(Macro.t()) :: Macro.t()

Generates a private macro suitable for use in guard expressions.

It raises at compile time if the definition uses expressions that aren't allowed in guards, and otherwise creates a private macro that can be used both inside or outside guards in the current module.

Similar to defmacrop/2, defguardp/1 must be defined before its use in the current module.

defimpl(name, opts, do_block \\ [])

(macro)

Defines an implementation for the given protocol.

See defprotocol/2 for more information and examples on protocols.

Inside an implementation, the name of the protocol can be accessed via @protocol and the current target as @for.

defmacro(call, expr \\ nil)

(macro)

Defines a macro with the given name and body.

Check def/2 for rules on naming and default arguments.

Examples

defmodule MyLogic do
  defmacro unless(expr, opts) do
    quote do
      if !unquote(expr), unquote(opts)
    end
  end
end

require MyLogic

MyLogic.unless false do
  IO.puts("It works")
end

defmacrop(call, expr \\ nil)

(macro)

Defines a private macro with the given name and body.

Private macros are only accessible from the same module in which they are defined.

Check defmacro/2 for more information, and check def/2 for rules on naming and default arguments.

defmodule(alias, do_block)

(macro)

Defines a module given by name with the given contents.

This macro defines a module with the given alias as its name and with the given contents. It returns a tuple with four elements:

  • :module
  • the module name
  • the binary contents of the module
  • the result of evaluating the contents block

Examples

iex> defmodule Foo do
...>   def bar, do: :baz
...> end
iex> Foo.bar()
:baz

Nesting

Nesting a module inside another module affects the name of the nested module:

defmodule Foo do
  defmodule Bar do
  end
end

In the example above, two modules - Foo and Foo.Bar - are created. When nesting, Elixir automatically creates an alias to the inner module, allowing the second module Foo.Bar to be accessed as Bar in the same lexical scope where it's defined (the Foo module).

If the Foo.Bar module is moved somewhere else, the references to Bar in the Foo module need to be updated to the fully-qualified name (Foo.Bar) or an alias has to be explicitly set in the Foo module with the help of Kernel.SpecialForms.alias/2.

defmodule Foo.Bar do
  # code
end

defmodule Foo do
  alias Foo.Bar
  # code here can refer to "Foo.Bar" as just "Bar"
end

Module names

A module name can be any atom, but Elixir provides a special syntax which is usually used for module names. What is called a module name is an uppercase ASCII letter followed by any number of lowercase or uppercase ASCII letters, numbers, or underscores. This identifier is equivalent to an atom prefixed by Elixir.. So in the defmodule Foo example Foo is equivalent to :"Elixir.Foo"

Dynamic names

Elixir module names can be dynamically generated. This is very useful when working with macros. For instance, one could write:

defmodule String.to_atom("Foo#{1}") do
  # contents ...
end

Elixir will accept any module name as long as the expression passed as the first argument to defmodule/2 evaluates to an atom. Note that, when a dynamic name is used, Elixir won't nest the name under the current module nor automatically set up an alias.

Reserved module names

If you attempt to define a module that already exists, you will get a warning saying that a module has been redefined.

There are some modules that Elixir does not currently implement but it may be implement in the future. Those modules are reserved and defining them will result in a compilation error:

defmodule Any do
  # code
end
#=> ** (CompileError) iex:1: module Any is reserved and cannot be defined

Elixir reserves the following module names: Elixir, Any, BitString, PID, and Reference.

defoverridable(keywords_or_behaviour)

(macro)

Makes the given functions in the current module overridable.

An overridable function is lazily defined, allowing a developer to override it.

Example

defmodule DefaultMod do
  defmacro __using__(_opts) do
    quote do
      def test(x, y) do
        x + y
      end

      defoverridable test: 2
    end
  end
end

defmodule InheritMod do
  use DefaultMod

  def test(x, y) do
    x * y + super(x, y)
  end
end

As seen as in the example above, super can be used to call the default implementation.

If @behaviour has been defined, defoverridable can also be called with a module as an argument. All implemented callbacks from the behaviour above the call to defoverridable will be marked as overridable.

Example

defmodule Behaviour do
  @callback foo :: any
end

defmodule DefaultMod do
  defmacro __using__(_opts) do
    quote do
      @behaviour Behaviour

      def foo do
        "Override me"
      end

      defoverridable Behaviour
    end
  end
end

defmodule InheritMod do
  use DefaultMod

  def foo do
    "Overridden"
  end
end

defp(call, expr \\ nil)

(macro)

Defines a private function with the given name and body.

Private functions are only accessible from within the module in which they are defined. Trying to access a private function from outside the module it's defined in results in an UndefinedFunctionError exception.

Check def/2 for more information.

Examples

defmodule Foo do
  def bar do
    sum(1, 2)
  end

  defp sum(a, b), do: a + b
end

Foo.bar()
#=> 3

Foo.sum(1, 2)
#=> ** (UndefinedFunctionError) undefined function Foo.sum/2

defprotocol(name, do_block)

(macro)

Defines a protocol.

A protocol specifies an API that should be defined by its implementations.

Examples

In Elixir, we have two verbs for checking how many items there are in a data structure: length and size. length means the information must be computed. For example, length(list) needs to traverse the whole list to calculate its length. On the other hand, tuple_size(tuple) and byte_size(binary) do not depend on the tuple and binary size as the size information is precomputed in the data structure.

Although Elixir includes specific functions such as tuple_size, binary_size and map_size, sometimes we want to be able to retrieve the size of a data structure regardless of its type. In Elixir we can write polymorphic code, i.e. code that works with different shapes/types, by using protocols. A size protocol could be implemented as follows:

defprotocol Size do
  @doc "Calculates the size (and not the length!) of a data structure"
  def size(data)
end

Now that the protocol can be implemented for every data structure the protocol may have a compliant implementation for:

defimpl Size, for: BitString do
  def size(binary), do: byte_size(binary)
end

defimpl Size, for: Map do
  def size(map), do: map_size(map)
end

defimpl Size, for: Tuple do
  def size(tuple), do: tuple_size(tuple)
end

Notice we didn't implement it for lists as we don't have the size information on lists, rather its value needs to be computed with length.

It is possible to implement protocols for all Elixir types:

Protocols and Structs

The real benefit of protocols comes when mixed with structs. For instance, Elixir ships with many data types implemented as structs, like MapSet. We can implement the Size protocol for those types as well:

defimpl Size, for: MapSet do
  def size(map_set), do: MapSet.size(map_set)
end

When implementing a protocol for a struct, the :for option can be omitted if the defimpl call is inside the module that defines the struct:

defmodule User do
  defstruct [:email, :name]

  defimpl Size do
    # two fields
    def size(%User{}), do: 2
  end
end

If a protocol implementation is not found for a given type, invoking the protocol will raise unless it is configured to fall back to Any. Conveniences for building implementations on top of existing ones are also available, look at defstruct/1 for more information about deriving protocols.

Fallback to Any

In some cases, it may be convenient to provide a default implementation for all types. This can be achieved by setting the @fallback_to_any attribute to true in the protocol definition:

defprotocol Size do
  @fallback_to_any true
  def size(data)
end

The Size protocol can now be implemented for Any:

defimpl Size, for: Any do
  def size(_), do: 0
end

Although the implementation above is arguably not a reasonable one. For example, it makes no sense to say a PID or an integer have a size of 0. That's one of the reasons why @fallback_to_any is an opt-in behaviour. For the majority of protocols, raising an error when a protocol is not implemented is the proper behaviour.

Multiple implementations

Protocols can also be implemented for multiple types at once:

defprotocol Reversible do
  def reverse(term)
end

defimpl Reversible, for: [Map, List] do
  def reverse(term), do: Enum.reverse(term)
end

Types

Defining a protocol automatically defines a type named t, which can be used as follows:

@spec print_size(Size.t()) :: :ok
def print_size(data) do
  result =
    case Size.size(data) do
      0 -> "data has no items"
      1 -> "data has one item"
      n -> "data has #{n} items"
    end

  IO.puts(result)
end

The @spec above expresses that all types allowed to implement the given protocol are valid argument types for the given function.

Reflection

Any protocol module contains three extra functions:

  • __protocol__/1 - returns the protocol information. The function takes one of the following atoms:

    • :consolidated? - returns whether the protocol is consolidated

    • :functions - returns keyword list of protocol functions and their arities

    • :impls - if consolidated, returns {:consolidated, modules} with the list of modules implementing the protocol, otherwise :not_consolidated

    • :module - the protocol module atom name

  • impl_for/1 - receives a structure and returns the module that implements the protocol for the structure, nil otherwise

  • impl_for!/1 - same as above but raises an error if an implementation is not found

For example, for the Enumerable protocol we have:

iex> Enumerable.__protocol__(:functions)
[count: 1, member?: 2, reduce: 3, slice: 1]

iex> Enumerable.impl_for([])
Enumerable.List

iex> Enumerable.impl_for(42)
nil

Consolidation

In order to cope with code loading in development, protocols in Elixir provide a slow implementation of protocol dispatching specific to development.

In order to speed up dispatching in production environments, where all implementations are known up-front, Elixir provides a feature called protocol consolidation. Consolidation directly links protocols to their implementations in a way that invoking a function from a consolidated protocol is equivalent to invoking two remote functions.

Protocol consolidation is applied by default to all Mix projects during compilation. This may be an issue during test. For instance, if you want to implement a protocol during test, the implementation will have no effect, as the protocol has already been consolidated. One possible solution is to include compilation directories that are specific to your test environment in your mix.exs:

def project do
  ...
  elixirc_paths: elixirc_paths(Mix.env())
  ...
end

defp elixirc_paths(:test), do: ["lib", "test/support"]
defp elixirc_paths(_), do: ["lib"]

And then you can define the implementations specific to the test environment inside test/support/some_file.ex.

Another approach is to disable protocol consolidation during tests in your mix.exs:

def project do
  ...
  consolidate_protocols: Mix.env() != :test
  ...
end

Although doing so is not recommended as it may affect your test suite performance.

Finally note all protocols are compiled with debug_info set to true, regardless of the option set by elixirc compiler. The debug info is used for consolidation and it may be removed after consolidation.

defstruct(fields)

(macro)

Defines a struct.

A struct is a tagged map that allows developers to provide default values for keys, tags to be used in polymorphic dispatches and compile time assertions.

To define a struct, a developer must define both __struct__/0 and __struct__/1 functions. defstruct/1 is a convenience macro which defines such functions with some conveniences.

For more information about structs, please check Kernel.SpecialForms.%/2.

Examples

defmodule User do
  defstruct name: nil, age: nil
end

Struct fields are evaluated at compile-time, which allows them to be dynamic. In the example below, 10 + 11 is evaluated at compile-time and the age field is stored with value 21:

defmodule User do
  defstruct name: nil, age: 10 + 11
end

The fields argument is usually a keyword list with field names as atom keys and default values as corresponding values. defstruct/1 also supports a list of atoms as its argument: in that case, the atoms in the list will be used as the struct's field names and they will all default to nil.

defmodule Post do
  defstruct [:title, :content, :author]
end

Deriving

Although structs are maps, by default structs do not implement any of the protocols implemented for maps. For example, attempting to use a protocol with the User struct leads to an error:

john = %User{name: "John"}
MyProtocol.call(john)
** (Protocol.UndefinedError) protocol MyProtocol not implemented for %User{...}

defstruct/1, however, allows protocol implementations to be derived. This can be done by defining a @derive attribute as a list before invoking defstruct/1:

defmodule User do
  @derive [MyProtocol]
  defstruct name: nil, age: 10 + 11
end

MyProtocol.call(john) #=> works

For each protocol in the @derive list, Elixir will assert the protocol has been implemented for Any. If the Any implementation defines a __deriving__/3 callback, the callback will be invoked and it should define the implementation module. Otherwise an implementation that simply points to the Any implementation is automatically derived. For more information on the __deriving__/3 callback, see Protocol.derive/3.

Enforcing keys

When building a struct, Elixir will automatically guarantee all keys belongs to the struct:

%User{name: "john", unknown: :key}
** (KeyError) key :unknown not found in: %User{age: 21, name: nil}

Elixir also allows developers to enforce certain keys must always be given when building the struct:

defmodule User do
  @enforce_keys [:name]
  defstruct name: nil, age: 10 + 11
end

Now trying to build a struct without the name key will fail:

%User{age: 21}
** (ArgumentError) the following keys must also be given when building struct User: [:name]

Keep in mind @enforce_keys is a simple compile-time guarantee to aid developers when building structs. It is not enforced on updates and it does not provide any sort of value-validation.

Types

It is recommended to define types for structs. By convention such type is called t. To define a struct inside a type, the struct literal syntax is used:

defmodule User do
  defstruct name: "John", age: 25
  @type t :: %__MODULE__{name: String.t(), age: non_neg_integer}
end

It is recommended to only use the struct syntax when defining the struct's type. When referring to another struct it's better to use User.t instead of %User{}.

The types of the struct fields that are not included in %User{} default to term() (see term/0).

Structs whose internal structure is private to the local module (pattern matching them or directly accessing their fields should not be allowed) should use the @opaque attribute. Structs whose internal structure is public should use @type.

destructure(left, right)

(macro)

Destructures two lists, assigning each term in the right one to the matching term in the left one.

Unlike pattern matching via =, if the sizes of the left and right lists don't match, destructuring simply stops instead of raising an error.

Examples

iex> destructure([x, y, z], [1, 2, 3, 4, 5])
iex> {x, y, z}
{1, 2, 3}

In the example above, even though the right list has more entries than the left one, destructuring works fine. If the right list is smaller, the remaining items are simply set to nil:

iex> destructure([x, y, z], [1])
iex> {x, y, z}
{1, nil, nil}

The left-hand side supports any expression you would use on the left-hand side of a match:

x = 1
destructure([^x, y, z], [1, 2, 3])

The example above will only work if x matches the first value in the right list. Otherwise, it will raise a MatchError (like the = operator would do).

exit(reason)

exit(term()) :: no_return()

Stops the execution of the calling process with the given reason.

Since evaluating this function causes the process to terminate, it has no return value.

Inlined by the compiler.

Examples

When a process reaches its end, by default it exits with reason :normal. You can also call exit/1 explicitly if you want to terminate a process but not signal any failure:

exit(:normal)

In case something goes wrong, you can also use exit/1 with a different reason:

exit(:seems_bad)

If the exit reason is not :normal, all the processes linked to the process that exited will crash (unless they are trapping exits).

OTP exits

Exits are used by the OTP to determine if a process exited abnormally or not. The following exits are considered "normal":

  • exit(:normal)
  • exit(:shutdown)
  • exit({:shutdown, term})

Exiting with any other reason is considered abnormal and treated as a crash. This means the default supervisor behaviour kicks in, error reports are emitted, etc.

This behaviour is relied on in many different places. For example, ExUnit uses exit(:shutdown) when exiting the test process to signal linked processes, supervision trees and so on to politely shut down too.

CLI exits

Building on top of the exit signals mentioned above, if the process started by the command line exits with any of the three reasons above, its exit is considered normal and the Operating System process will exit with status 0.

It is, however, possible to customize the Operating System exit signal by invoking:

exit({:shutdown, integer})

This will cause the OS process to exit with the status given by integer while signaling all linked Erlang processes to politely shut down.

Any other exit reason will cause the OS process to exit with status 1 and linked Erlang processes to crash.

function_exported?(module, function, arity)

function_exported?(module(), atom(), arity()) :: boolean()

Returns true if module is loaded and contains a public function with the given arity, otherwise false.

Note that this function does not load the module in case it is not loaded. Check Code.ensure_loaded/1 for more information.

Inlined by the compiler.

Examples

iex> function_exported?(Enum, :member?, 2)
true

get_and_update_in(path, fun)

(macro)

Gets a value and updates a nested data structure via the given path.

This is similar to get_and_update_in/3, except the path is extracted via a macro rather than passing a list. For example:

get_and_update_in(opts[:foo][:bar], &{&1, &1 + 1})

Is equivalent to:

get_and_update_in(opts, [:foo, :bar], &{&1, &1 + 1})

Note that in order for this macro to work, the complete path must always be visible by this macro. See the Paths section below.

Examples

iex> users = %{"john" => %{age: 27}, "meg" => %{age: 23}}
iex> get_and_update_in(users["john"].age, &{&1, &1 + 1})
{27, %{"john" => %{age: 28}, "meg" => %{age: 23}}}

Paths

A path may start with a variable, local or remote call, and must be followed by one or more:

  • foo[bar] - accesses the key bar in foo; in case foo is nil, nil is returned

  • foo.bar - accesses a map/struct field; in case the field is not present, an error is raised

Here are some valid paths:

users["john"][:age]
users["john"].age
User.all()["john"].age
all_users()["john"].age

Here are some invalid ones:

# Does a remote call after the initial value
users["john"].do_something(arg1, arg2)

# Does not access any key or field
users

get_and_update_in(data, keys, fun)

get_and_update_in(
  structure :: Access.t(),
  keys,
  (term() -> {get_value, update_value} | :pop)
) :: {get_value, structure :: Access.t()}
when keys: [any(), ...], update_value: term(), get_value: var

Gets a value and updates a nested structure.

data is a nested structure (that is, a map, keyword list, or struct that implements the Access behaviour).

The fun argument receives the value of key (or nil if key is not present) and must return one of the following values:

  • a two-element tuple {get_value, new_value}. In this case, get_value is the retrieved value which can possibly be operated on before being returned. new_value is the new value to be stored under key.

  • :pop, which implies that the current value under key should be removed from the structure and returned.

This function uses the Access module to traverse the structures according to the given keys, unless the key is a function.

If a key is a function, the function will be invoked passing three arguments:

  • the operation (:get_and_update)
  • the data to be accessed
  • a function to be invoked next

This means get_and_update_in/3 can be extended to provide custom lookups. The downside is that functions cannot be stored as keys in the accessed data structures.

Examples

This function is useful when there is a need to retrieve the current value (or something calculated in function of the current value) and update it at the same time. For example, it could be used to read the current age of a user while increasing it by one in one pass:

iex> users = %{"john" => %{age: 27}, "meg" => %{age: 23}}
iex> get_and_update_in(users, ["john", :age], &{&1, &1 + 1})
{27, %{"john" => %{age: 28}, "meg" => %{age: 23}}}

When one of the keys is a function, the function is invoked. In the example below, we use a function to get and increment all ages inside a list:

iex> users = [%{name: "john", age: 27}, %{name: "meg", age: 23}]
iex> all = fn :get_and_update, data, next ->
...>   data |> Enum.map(next) |> Enum.unzip()
...> end
iex> get_and_update_in(users, [all, :age], &{&1, &1 + 1})
{[27, 23], [%{name: "john", age: 28}, %{name: "meg", age: 24}]}

If the previous value before invoking the function is nil, the function will receive nil as a value and must handle it accordingly (be it by failing or providing a sane default).

The Access module ships with many convenience accessor functions, like the all anonymous function defined above. See Access.all/0, Access.key/2, and others as examples.

get_in(data, keys)

get_in(Access.t(), [term(), ...]) :: term()

Gets a value from a nested structure.

Uses the Access module to traverse the structures according to the given keys, unless the key is a function.

If a key is a function, the function will be invoked passing three arguments:

  • the operation (:get)
  • the data to be accessed
  • a function to be invoked next

This means get_in/2 can be extended to provide custom lookups. The downside is that functions cannot be stored as keys in the accessed data structures.

Examples

iex> users = %{"john" => %{age: 27}, "meg" => %{age: 23}}
iex> get_in(users, ["john", :age])
27

In case any of the entries in the middle returns nil, nil will be returned as per the Access module:

iex> users = %{"john" => %{age: 27}, "meg" => %{age: 23}}
iex> get_in(users, ["unknown", :age])
nil

When one of the keys is a function that takes three arguments, the function is invoked. In the example below, we use a function to get all the maps inside a list:

iex> users = [%{name: "john", age: 27}, %{name: "meg", age: 23}]
iex> all = fn :get, data, next -> Enum.map(data, next) end
iex> get_in(users, [all, :age])
[27, 23]

If the previous value before invoking the function is nil, the function will receive nil as a value and must handle it accordingly.

if(condition, clauses)

(macro)

Provides an if/2 macro.

This macro expects the first argument to be a condition and the second argument to be a keyword list.

One-liner examples

if(foo, do: bar)

In the example above, bar will be returned if foo evaluates to a truthy value (neither false nor nil). Otherwise, nil will be returned.

An else option can be given to specify the opposite:

if(foo, do: bar, else: baz)

Blocks examples

It's also possible to pass a block to the if/2 macro. The first example above would be translated to:

if foo do
  bar
end

Note that do/end become delimiters. The second example would translate to:

if foo do
  bar
else
  baz
end

In order to compare more than two clauses, the cond/1 macro has to be used.

inspect(term, opts \\ [])

inspect(Inspect.t(), keyword()) :: String.t()

Inspects the given argument according to the Inspect protocol. The second argument is a keyword list with options to control inspection.

Options

inspect/2 accepts a list of options that are internally translated to an Inspect.Opts struct. Check the docs for Inspect.Opts to see the supported options.

Examples

iex> inspect(:foo)
":foo"

iex> inspect([1, 2, 3, 4, 5], limit: 3)
"[1, 2, 3, ...]"

iex> inspect([1, 2, 3], pretty: true, width: 0)
"[1,\n 2,\n 3]"

iex> inspect("olá" <> <<0>>)
"<<111, 108, 195, 161, 0>>"

iex> inspect("olá" <> <<0>>, binaries: :as_strings)
"\"olá\\0\""

iex> inspect("olá", binaries: :as_binaries)
"<<111, 108, 195, 161>>"

iex> inspect('bar')
"'bar'"

iex> inspect([0 | 'bar'])
"[0, 98, 97, 114]"

iex> inspect(100, base: :octal)
"0o144"

iex> inspect(100, base: :hex)
"0x64"

Note that the Inspect protocol does not necessarily return a valid representation of an Elixir term. In such cases, the inspected result must start with #. For example, inspecting a function will return:

inspect(fn a, b -> a + b end)
#=> #Function<...>

The Inspect protocol can be derived to hide certain fields from structs, so they don't show up in logs, inspects and similar. See the "Deriving" section of the documentation of the Inspect protocol for more information.

macro_exported?(module, macro, arity)

macro_exported?(module(), atom(), arity()) :: boolean()

Returns true if module is loaded and contains a public macro with the given arity, otherwise false.

Note that this function does not load the module in case it is not loaded. Check Code.ensure_loaded/1 for more information.

If module is an Erlang module (as opposed to an Elixir module), this function always returns false.

Examples

iex> macro_exported?(Kernel, :use, 2)
true

iex> macro_exported?(:erlang, :abs, 1)
false

make_ref()

make_ref() :: reference()

Returns an almost unique reference.

The returned reference will re-occur after approximately 2^82 calls; therefore it is unique enough for practical purposes.

Inlined by the compiler.

Examples

make_ref()
#=> #Reference<0.0.0.135>

match?(pattern, expr)

(macro)

A convenience macro that checks if the right side (an expression) matches the left side (a pattern).

Examples

iex> match?(1, 1)
true

iex> match?(1, 2)
false

iex> match?({1, _}, {1, 2})
true

iex> map = %{a: 1, b: 2}
iex> match?(%{a: _}, map)
true

iex> a = 1
iex> match?(^a, 1)
true

match?/2 is very useful when filtering or finding a value in an enumerable:

iex> list = [a: 1, b: 2, a: 3]
iex> Enum.filter(list, &match?({:a, _}, &1))
[a: 1, a: 3]

Guard clauses can also be given to the match:

iex> list = [a: 1, b: 2, a: 3]
iex> Enum.filter(list, &match?({:a, x} when x < 2, &1))
[a: 1]

However, variables assigned in the match will not be available outside of the function call (unlike regular pattern matching with the = operator):

iex> match?(_x, 1)
true
iex> binding()
[]

max(first, second)

max(first, second) :: first | second when first: term(), second: term()

Returns the biggest of the two given terms according to Erlang's term ordering.

If the terms compare equal, the first one is returned.

Inlined by the compiler.

Examples

iex> max(1, 2)
2
iex> max(:a, :b)
:b

Using Erlang's term ordering means that comparisons are structural and not semantic. For example, when comparing dates:

iex> max(~D[2017-03-31], ~D[2017-04-01])
~D[2017-03-31]

In the example above, max/1 returned March 31st instead of April 1st because the structural comparison compares the day before the year. In such cases it is common for modules to provide functions such as Date.compare/2 that perform semantic comparison.

min(first, second)

min(first, second) :: first | second when first: term(), second: term()

Returns the smallest of the two given terms according to Erlang's term ordering.

If the terms compare equal, the first one is returned.

Inlined by the compiler.

Examples

iex> min(1, 2)
1
iex> min("foo", "bar")
"bar"

Using Erlang's term ordering means that comparisons are structural and not semantic. For example, when comparing dates:

iex> min(~D[2017-03-31], ~D[2017-04-01])
~D[2017-04-01]

In the example above, min/1 returned April 1st instead of March 31st because the structural comparison compares the day before the year. In such cases it is common for modules to provide functions such as Date.compare/2 that perform semantic comparison.

pop_in(path)

(macro)

Pops a key from the nested structure via the given path.

This is similar to pop_in/2, except the path is extracted via a macro rather than passing a list. For example:

pop_in(opts[:foo][:bar])

Is equivalent to:

pop_in(opts, [:foo, :bar])

Note that in order for this macro to work, the complete path must always be visible by this macro. For more information about the supported path expressions, please check get_and_update_in/2 docs.

Examples

iex> users = %{"john" => %{age: 27}, "meg" => %{age: 23}}
iex> pop_in(users["john"][:age])
{27, %{"john" => %{}, "meg" => %{age: 23}}}

iex> users = %{john: %{age: 27}, meg: %{age: 23}}
iex> pop_in(users.john[:age])
{27, %{john: %{}, meg: %{age: 23}}}

In case any entry returns nil, its key will be removed and the deletion will be considered a success.

pop_in(data, keys)

pop_in(data, [Access.get_and_update_fun(term(), data) | term(), ...]) ::
  {term(), data}
when data: Access.container()

Pops a key from the given nested structure.

Uses the Access protocol to traverse the structures according to the given keys, unless the key is a function. If the key is a function, it will be invoked as specified in get_and_update_in/3.

Examples

iex> users = %{"john" => %{age: 27}, "meg" => %{age: 23}}
iex> pop_in(users, ["john", :age])
{27, %{"john" => %{}, "meg" => %{age: 23}}}

In case any entry returns nil, its key will be removed and the deletion will be considered a success.

iex> users = %{"john" => %{age: 27}, "meg" => %{age: 23}}
iex> pop_in(users, ["jane", :age])
{nil, %{"john" => %{age: 27}, "meg" => %{age: 23}}}

put_elem(tuple, index, value)

put_elem(tuple(), non_neg_integer(), term()) :: tuple()

Puts value at the given zero-based index in tuple.

Inlined by the compiler.

Examples

iex> tuple = {:foo, :bar, 3}
iex> put_elem(tuple, 0, :baz)
{:baz, :bar, 3}

put_in(path, value)

(macro)

Puts a value in a nested structure via the given path.

This is similar to put_in/3, except the path is extracted via a macro rather than passing a list. For example:

put_in(opts[:foo][:bar], :baz)

Is equivalent to:

put_in(opts, [:foo, :bar], :baz)

Note that in order for this macro to work, the complete path must always be visible by this macro. For more information about the supported path expressions, please check get_and_update_in/2 docs.

Examples

iex> users = %{"john" => %{age: 27}, "meg" => %{age: 23}}
iex> put_in(users["john"][:age], 28)
%{"john" => %{age: 28}, "meg" => %{age: 23}}

iex> users = %{"john" => %{age: 27}, "meg" => %{age: 23}}
iex> put_in(users["john"].age, 28)
%{"john" => %{age: 28}, "meg" => %{age: 23}}

put_in(data, keys, value)

put_in(Access.t(), [term(), ...], term()) :: Access.t()

Puts a value in a nested structure.

Uses the Access module to traverse the structures according to the given keys, unless the key is a function. If the key is a function, it will be invoked as specified in get_and_update_in/3.

Examples

iex> users = %{"john" => %{age: 27}, "meg" => %{age: 23}}
iex> put_in(users, ["john", :age], 28)
%{"john" => %{age: 28}, "meg" => %{age: 23}}

In case any of the entries in the middle returns nil, an error will be raised when trying to access it next.

raise(message)

(macro)

Raises an exception.

If the argument msg is a binary, it raises a RuntimeError exception using the given argument as message.

If msg is an atom, it just calls raise/2 with the atom as the first argument and [] as the second argument.

If msg is an exception struct, it is raised as is.

If msg is anything else, raise will fail with an ArgumentError exception.

Examples

iex> raise "oops"
** (RuntimeError) oops

try do
  1 + :foo
rescue
  x in [ArithmeticError] ->
    IO.puts("that was expected")
    raise x
end

raise(exception, attributes)

(macro)

Raises an exception.

Calls the exception/1 function on the given argument (which has to be a module name like ArgumentError or RuntimeError) passing attrs as the attributes in order to retrieve the exception struct.

Any module that contains a call to the defexception/1 macro automatically implements the Exception.exception/1 callback expected by raise/2. For more information, see defexception/1.

Examples

iex> raise(ArgumentError, "Sample")
** (ArgumentError) Sample

reraise(message, stacktrace)

(macro)

Raises an exception preserving a previous stacktrace.

Works like raise/1 but does not generate a new stacktrace.

Notice that __STACKTRACE__ can be used inside catch/rescue to retrieve the current stacktrace.

Examples

try do
  raise "oops"
rescue
  exception ->
    reraise exception, __STACKTRACE__
end

reraise(exception, attributes, stacktrace)

(macro)

Raises an exception preserving a previous stacktrace.

reraise/3 works like reraise/2, except it passes arguments to the exception/1 function as explained in raise/2.

Examples

try do
  raise "oops"
rescue
  exception ->
    reraise WrapperError, [exception: exception], __STACKTRACE__
end

send(dest, message)

send(dest :: Process.dest(), message) :: message when message: any()

Sends a message to the given dest and returns the message.

dest may be a remote or local PID, a local port, a locally registered name, or a tuple in the form of {registered_name, node} for a registered name at another node.

Inlined by the compiler.

Examples

iex> send(self(), :hello)
:hello

sigil_C(term, modifiers)

(macro)

Handles the sigil ~C for charlists.

It simply returns a charlist without escaping characters and without interpolations.

Examples

iex> ~C(foo)
'foo'

iex> ~C(f#{o}o)
'f\#{o}o'

sigil_D(date_string, modifiers)

(macro)

Handles the sigil ~D for dates.

The lower case ~d variant does not exist as interpolation and escape characters are not useful for date sigils.

More information on dates can be found in the Date module.

Examples

iex> ~D[2015-01-13]
~D[2015-01-13]

sigil_N(naive_datetime_string, modifiers)

(macro)

Handles the sigil ~N for naive date times.

The lower case ~n variant does not exist as interpolation and escape characters are not useful for datetime sigils.

More information on naive date times can be found in the NaiveDateTime module.

Examples

iex> ~N[2015-01-13 13:00:07]
~N[2015-01-13 13:00:07]
iex> ~N[2015-01-13T13:00:07.001]
~N[2015-01-13 13:00:07.001]

sigil_R(term, modifiers)

(macro)

Handles the sigil ~R for regular expressions.

It returns a regular expression pattern without escaping nor interpreting interpolations.

More information on regexes can be found in the Regex module.

Examples

iex> Regex.match?(~R(f#{1,3}o), "f#o")
true

sigil_S(term, modifiers)

(macro)

Handles the sigil ~S for strings.

It simply returns a string without escaping characters and without interpolations.

Examples

iex> ~S(foo)
"foo"

iex> ~S(f#{o}o)
"f\#{o}o"

sigil_T(time_string, modifiers)

(macro)

Handles the sigil ~T for times.

The lower case ~t variant does not exist as interpolation and escape characters are not useful for time sigils.

More information on times can be found in the Time module.

Examples

iex> ~T[13:00:07]
~T[13:00:07]
iex> ~T[13:00:07.001]
~T[13:00:07.001]

sigil_W(term, modifiers)

(macro)

Handles the sigil ~W for list of words.

It returns a list of "words" split by whitespace without escaping nor interpreting interpolations.

Modifiers

  • s: words in the list are strings (default)
  • a: words in the list are atoms
  • c: words in the list are charlists

Examples

iex> ~W(foo #{bar} baz)
["foo", "\#{bar}", "baz"]

sigil_c(term, modifiers)

(macro)

Handles the sigil ~c for charlists.

It returns a charlist as if it was a single quoted string, unescaping characters and replacing interpolations.

Examples

iex> ~c(foo)
'foo'

iex> ~c(f#{:o}o)
'foo'

iex> ~c(f\#{:o}o)
'f\#{:o}o'

sigil_r(term, modifiers)

(macro)

Handles the sigil ~r for regular expressions.

It returns a regular expression pattern, unescaping characters and replacing interpolations.

More information on regular expressions can be found in the Regex module.

Examples

iex> Regex.match?(~r(foo), "foo")
true

iex> Regex.match?(~r/abc/, "abc")
true

sigil_s(term, modifiers)

(macro)

Handles the sigil ~s for strings.

It returns a string as if it was a double quoted string, unescaping characters and replacing interpolations.

Examples

iex> ~s(foo)
"foo"

iex> ~s(f#{:o}o)
"foo"

iex> ~s(f\#{:o}o)
"f\#{:o}o"

sigil_w(term, modifiers)

(macro)

Handles the sigil ~w for list of words.

It returns a list of "words" split by whitespace. Character unescaping and interpolation happens for each word.

Modifiers

  • s: words in the list are strings (default)
  • a: words in the list are atoms
  • c: words in the list are charlists

Examples

iex> ~w(foo #{:bar} baz)
["foo", "bar", "baz"]

iex> ~w(foo #{" bar baz "})
["foo", "bar", "baz"]

iex> ~w(--source test/enum_test.exs)
["--source", "test/enum_test.exs"]

iex> ~w(foo bar baz)a
[:foo, :bar, :baz]

spawn(fun)

spawn((() -> any())) :: pid()

Spawns the given function and returns its PID.

Typically developers do not use the spawn functions, instead they use abstractions such as Task, GenServer and Agent, built on top of spawn, that spawns processes with more conveniences in terms of introspection and debugging.

Check the Process module for more process-related functions.

The anonymous function receives 0 arguments, and may return any value.

Inlined by the compiler.

Examples

current = self()
child = spawn(fn -> send(current, {self(), 1 + 2}) end)

receive do
  {^child, 3} -> IO.puts("Received 3 back")
end

spawn(module, fun, args)

spawn(module(), atom(), list()) :: pid()

Spawns the given function fun from the given module passing it the given args and returns its PID.

Typically developers do not use the spawn functions, instead they use abstractions such as Task, GenServer and Agent, built on top of spawn, that spawns processes with more conveniences in terms of introspection and debugging.

Check the Process module for more process-related functions.

Inlined by the compiler.

Examples

spawn(SomeModule, :function, [1, 2, 3])

spawn_link(fun)

spawn_link((() -> any())) :: pid()

Spawns the given function, links it to the current process, and returns its PID.

Typically developers do not use the spawn functions, instead they use abstractions such as Task, GenServer and Agent, built on top of spawn, that spawns processes with more conveniences in terms of introspection and debugging.

Check the Process module for more process-related functions. For more information on linking, check Process.link/1.

The anonymous function receives 0 arguments, and may return any value.

Inlined by the compiler.

Examples

current = self()
child = spawn_link(fn -> send(current, {self(), 1 + 2}) end)

receive do
  {^child, 3} -> IO.puts("Received 3 back")
end

spawn_link(module, fun, args)

spawn_link(module(), atom(), list()) :: pid()

Spawns the given function fun from the given module passing it the given args, links it to the current process, and returns its PID.

Typically developers do not use the spawn functions, instead they use abstractions such as Task, GenServer and Agent, built on top of spawn, that spawns processes with more conveniences in terms of introspection and debugging.

Check the Process module for more process-related functions. For more information on linking, check Process.link/1.

Inlined by the compiler.

Examples

spawn_link(SomeModule, :function, [1, 2, 3])

spawn_monitor(fun)

spawn_monitor((() -> any())) :: {pid(), reference()}

Spawns the given function, monitors it and returns its PID and monitoring reference.

Typically developers do not use the spawn functions, instead they use abstractions such as Task, GenServer and Agent, built on top of spawn, that spawns processes with more conveniences in terms of introspection and debugging.

Check the Process module for more process-related functions.

The anonymous function receives 0 arguments, and may return any value.

Inlined by the compiler.

Examples

current = self()
spawn_monitor(fn -> send(current, {self(), 1 + 2}) end)

spawn_monitor(module, fun, args)

spawn_monitor(module(), atom(), list()) :: {pid(), reference()}

Spawns the given module and function passing the given args, monitors it and returns its PID and monitoring reference.

Typically developers do not use the spawn functions, instead they use abstractions such as Task, GenServer and Agent, built on top of spawn, that spawns processes with more conveniences in terms of introspection and debugging.

Check the Process module for more process-related functions.

Inlined by the compiler.

Examples

spawn_monitor(SomeModule, :function, [1, 2, 3])

struct(struct, fields \\ [])

struct(module() | struct(), Enum.t()) :: struct()

Creates and updates structs.

The struct argument may be an atom (which defines defstruct) or a struct itself. The second argument is any Enumerable that emits two-element tuples (key-value pairs) during enumeration.

Keys in the Enumerable that don't exist in the struct are automatically discarded. Note that keys must be atoms, as only atoms are allowed when defining a struct.

This function is useful for dynamically creating and updating structs, as well as for converting maps to structs; in the latter case, just inserting the appropriate :__struct__ field into the map may not be enough and struct/2 should be used instead.

Examples

defmodule User do
  defstruct name: "john"
end

struct(User)
#=> %User{name: "john"}

opts = [name: "meg"]
user = struct(User, opts)
#=> %User{name: "meg"}

struct(user, unknown: "value")
#=> %User{name: "meg"}

struct(User, %{name: "meg"})
#=> %User{name: "meg"}

# String keys are ignored
struct(User, %{"name" => "meg"})
#=> %User{name: "john"}

struct!(struct, fields \\ [])

struct!(module() | struct(), Enum.t()) :: struct()

Similar to struct/2 but checks for key validity.

The function struct!/2 emulates the compile time behaviour of structs. This means that:

  • when building a struct, as in struct!(SomeStruct, key: :value), it is equivalent to %SomeStruct{key: :value} and therefore this function will check if every given key-value belongs to the struct. If the struct is enforcing any key via @enforce_keys, those will be enforced as well;

  • when updating a struct, as in struct!(%SomeStruct{}, key: :value), it is equivalent to %SomeStruct{struct | key: :value} and therefore this function will check if every given key-value belongs to the struct. However, updating structs does not enforce keys, as keys are enforced only when building;

throw(term)

throw(term()) :: no_return()

A non-local return from a function.

Check Kernel.SpecialForms.try/1 for more information.

Inlined by the compiler.

to_charlist(term)

(macro)

Converts the given term to a charlist according to the List.Chars protocol.

Examples

iex> to_charlist(:foo)
'foo'

to_string(term)

(macro)

Converts the argument to a string according to the String.Chars protocol.

This is the function invoked when there is string interpolation.

Examples

iex> to_string(:foo)
"foo"

unless(condition, clauses)

(macro)

Provides an unless macro.

This macro evaluates and returns the do block passed in as the second argument unless clause evaluates to a truthy value (neither false nor nil). Otherwise, it returns the value of the else block if present or nil if not.

See also if/2.

Examples

iex> unless(Enum.empty?([]), do: "Hello")
nil

iex> unless(Enum.empty?([1, 2, 3]), do: "Hello")
"Hello"

iex> unless Enum.sum([2, 2]) == 5 do
...>   "Math still works"
...> else
...>   "Math is broken"
...> end
"Math still works"

update_in(path, fun)

(macro)

Updates a nested structure via the given path.

This is similar to update_in/3, except the path is extracted via a macro rather than passing a list. For example:

update_in(opts[:foo][:bar], &(&1 + 1))

Is equivalent to:

update_in(opts, [:foo, :bar], &(&1 + 1))

Note that in order for this macro to work, the complete path must always be visible by this macro. For more information about the supported path expressions, please check get_and_update_in/2 docs.

Examples

iex> users = %{"john" => %{age: 27}, "meg" => %{age: 23}}
iex> update_in(users["john"][:age], &(&1 + 1))
%{"john" => %{age: 28}, "meg" => %{age: 23}}

iex> users = %{"john" => %{age: 27}, "meg" => %{age: 23}}
iex> update_in(users["john"].age, &(&1 + 1))
%{"john" => %{age: 28}, "meg" => %{age: 23}}

update_in(data, keys, fun)

update_in(Access.t(), [term(), ...], (term() -> term())) :: Access.t()

Updates a key in a nested structure.

Uses the Access module to traverse the structures according to the given keys, unless the key is a function. If the key is a function, it will be invoked as specified in get_and_update_in/3.

Examples

iex> users = %{"john" => %{age: 27}, "meg" => %{age: 23}}
iex> update_in(users, ["john", :age], &(&1 + 1))
%{"john" => %{age: 28}, "meg" => %{age: 23}}

In case any of the entries in the middle returns nil, an error will be raised when trying to access it next.

use(module, opts \\ [])

(macro)

Uses the given module in the current context.

When calling:

use MyModule, some: :options

the __using__/1 macro from the MyModule module is invoked with the second argument passed to use as its argument. Since __using__/1 is a macro, all the usual macro rules apply, and its return value should be quoted code that is then inserted where use/2 is called.

Examples

For example, in order to write test cases using the ExUnit framework provided with Elixir, a developer should use the ExUnit.Case module:

defmodule AssertionTest do
  use ExUnit.Case, async: true

  test "always pass" do
    assert true
  end
end

In this example, ExUnit.Case.__using__/1 is called with the keyword list [async: true] as its argument; use/2 translates to:

defmodule AssertionTest do
  require ExUnit.Case
  ExUnit.Case.__using__(async: true)

  test "always pass" do
    assert true
  end
end

ExUnit.Case will then define the __using__/1 macro:

defmodule ExUnit.Case do
  defmacro __using__(opts) do
    # do something with opts
    quote do
      # return some code to inject in the caller
    end
  end
end

Best practices

__using__/1 is typically used when there is a need to set some state (via module attributes) or callbacks (like @before_compile, see the documentation for Module for more information) into the caller.

__using__/1 may also be used to alias, require, or import functionality from different modules:

defmodule MyModule do
  defmacro __using__(_opts) do
    quote do
      import MyModule.Foo
      import MyModule.Bar
      import MyModule.Baz

      alias MyModule.Repo
    end
  end
end

However, do not provide __using__/1 if all it does is to import, alias or require the module itself. For example, avoid this:

defmodule MyModule do
  defmacro __using__(_opts) do
    quote do
      import MyModule
    end
  end
end

In such cases, developers should instead import or alias the module directly, so that they can customize those as they wish, without the indirection behind use/2.

Finally, developers should also avoid defining functions inside the __using__/1 callback, unless those functions are the default implementation of a previously defined @callback or are functions meant to be overridden (see defoverridable/1). Even in these cases, defining functions should be seen as a "last resort".

In case you want to provide some existing functionality to the user module, please define it in a module which will be imported accordingly; for example, ExUnit.Case doesn't define the test/3 macro in the module that calls use ExUnit.Case, but it defines ExUnit.Case.test/3 and just imports that into the caller when used.

var!(var, context \\ nil)

(macro)

When used inside quoting, marks that the given variable should not be hygienized.

The argument can be either a variable unquoted or in standard tuple form {name, meta, context}.

Check Kernel.SpecialForms.quote/2 for more information.

left |> right

(macro)

Pipe operator.

This operator introduces the expression on the left-hand side as the first argument to the function call on the right-hand side.

Examples

iex> [1, [2], 3] |> List.flatten()
[1, 2, 3]

The example above is the same as calling List.flatten([1, [2], 3]).

The |> operator is mostly useful when there is a desire to execute a series of operations resembling a pipeline:

iex> [1, [2], 3] |> List.flatten() |> Enum.map(fn x -> x * 2 end)
[2, 4, 6]

In the example above, the list [1, [2], 3] is passed as the first argument to the List.flatten/1 function, then the flattened list is passed as the first argument to the Enum.map/2 function which doubles each element of the list.

In other words, the expression above simply translates to:

Enum.map(List.flatten([1, [2], 3]), fn x -> x * 2 end)

Pitfalls

There are two common pitfalls when using the pipe operator.

The first one is related to operator precedence. For example, the following expression:

String.graphemes "Hello" |> Enum.reverse

Translates to:

String.graphemes("Hello" |> Enum.reverse())

which results in an error as the Enumerable protocol is not defined for binaries. Adding explicit parentheses resolves the ambiguity:

String.graphemes("Hello") |> Enum.reverse()

Or, even better:

"Hello" |> String.graphemes() |> Enum.reverse()

The second pitfall is that the |> operator works on calls. For example, when you write:

"Hello" |> some_function()

Elixir sees the right-hand side is a function call and pipes to it. This means that, if you want to pipe to an anonymous or captured function, it must also be explicitly called.

Given the anonymous function:

fun = fn x -> IO.puts(x) end
fun.("Hello")

This won't work as it will rather try to invoke the local function fun:

"Hello" |> fun()

This works:

"Hello" |> fun.()

As you can see, the |> operator retains the same semantics as when the pipe is not used since both require the fun.(...) notation.

left || right

(macro)

Provides a short-circuit operator that evaluates and returns the second expression only if the first one does not evaluate to a truthy value (that is, it is either nil or false). Returns the first expression otherwise.

Not allowed in guard clauses.

Examples

iex> Enum.empty?([1]) || Enum.empty?([1])
false

iex> List.first([]) || true
true

iex> Enum.empty?([1]) || 1
1

iex> Enum.empty?([]) || throw(:bad)
true

Note that, unlike or/2, this operator accepts any expression as the first argument, not only booleans.

© 2012 Plataformatec
Licensed under the Apache License, Version 2.0.
https://hexdocs.pm/elixir/1.8.2/Kernel.html