Returns true if the two items are not equal.

This operator considers 1 and 1.0 to be equal. For match comparison, use !== 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

Returns true if the two items do not match.

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

Arithmetic multiplication.

Allowed in guard tests. Inlined by the compiler.

Examples

iex> 1 * 2
2

Arithmetic unary plus.

Allowed in guard tests. Inlined by the compiler.

Examples

iex> +1
1

Arithmetic plus.

Allowed in guard tests. Inlined by the compiler.

Examples

iex> 1 + 2
3

Concatenates two lists.

Allowed in guard tests. Inlined by the compiler.

Examples

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

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

Arithmetic unary minus.

Allowed in guard tests. Inlined by the compiler.

Examples

iex> -2
-2

Arithmetic minus.

Allowed in guard tests. Inlined by the compiler.

Examples

iex> 1 - 2
-1

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

Allowed in guard tests. Inlined by the compiler.

Examples

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

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

Arithmetic division.

The result is always a float. Use div and rem if you want a natural division or the remainder.

Allowed in guard tests. Inlined by the compiler.

Examples

iex> 1 / 2
0.5

iex> 2 / 1
2.0

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

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

Returns true if the two items are equal.

This operator considers 1 and 1.0 to be equal. For match semantics, use === 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

Returns true if the two items are match.

This operator gives the same semantics as the one existing in pattern matching, i.e., 1 and 1.0 are equal, but they do not match.

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

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

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

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

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

Invokes the given fun with the array of arguments args.

Inlined by the compiler.

Examples

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

Invokes the given fun from module with the array of arguments args.

Inlined by the compiler.

Examples

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

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

If start or length references 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 at the end of a binary:

iex> binary_part("foo", 3, -1)
"o"

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

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. 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

Performs an integer division.

Raises an error if one of the arguments is not an integer.

Allowed in guard tests. Inlined by the compiler.

Examples

iex> div(5, 2)
2

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

Allowed in guard tests. Inlined by the compiler.

Example

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

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 it 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 reason is not :normal, all linked process to the exited process will crash (unless they are trapping exits).

OTP exits

Exits are used by 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 shutdown 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 OTP processes to politely shutdown.

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

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

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

Gets a value and updates a nested structure.

It expects a tuple to be returned, containing the value retrieved and the update one.

Uses the Access protocol 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, and 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 increase the age of a user by one and return the previous age 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 ->
...>   Enum.map(data, next) |> :lists.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).

Gets a value from a nested structure.

Uses the Access protocol 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, and 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 entries in the middle returns nil, nil will be returned as per the Access protocol:

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

When one of the keys is a function, 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.

Returns the head of a list, raises badarg if the list is empty.

Inlined by the compiler.

Inspect the given argument according to the Inspect protocol. The second argument is a keywords 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("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<...>

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

Allowed in guard tests. Inlined by the compiler.

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.

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

Allowed in guard tests. Inlined by the compiler.

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.

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

Allowed in guard tests. Inlined by the compiler.

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

Allowed in guard tests. Inlined by the compiler.

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.

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

Allowed in guard tests. Inlined by the compiler.

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

Allowed in guard tests. Inlined by the compiler.

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

Allowed in guard tests. Inlined by the compiler.

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

Allowed in guard tests. Inlined by the compiler.

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

Allowed in guard tests. Inlined by the compiler.

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

Allowed in guard tests. Inlined by the compiler.

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

Allowed in guard tests. Inlined by the compiler.

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

Allowed in guard tests. Inlined by the compiler.

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

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

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

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>

Returns the size of a map.

This operation happens in constant time.

Allowed in guard tests. Inlined by the compiler.

Return 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

Return 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

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.

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.

Boolean not. Argument must be a boolean.

Allowed in guard tests. Inlined by the compiler.

Examples

iex> not false
true

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

Inlined by the compiler.

Example

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

Puts a value in a 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> put_in(users, ["john", :age], 28)
%{"john" => %{age: 28}, "meg" => %{age: 23}}

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

Calculates the remainder of an integer division.

Raises an error if one of the arguments is not an integer.

Allowed in guard tests. Inlined by the compiler.

Examples

iex> rem(5, 2)
1

Returns an integer by rounding the given number.

Allowed in guard tests. Inlined by the compiler.

Examples

iex> round(5.5)
6

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

Allowed in guard clauses. Inlined by the compiler.

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 {registered_name, node} for a registered name at another node.

Inlined by the compiler.

Examples

iex> send self(), :hello
:hello

Spawns the given function and returns its pid.

Check the modules Process and Node for other functions to handle processes, including spawning functions in nodes.

Inlined by the compiler.

Examples

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

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

Spawns the given module and function passing the given args and returns its pid.

Check the modules Process and Node for other functions to handle processes, including spawning functions in nodes.

Inlined by the compiler.

Examples

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

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

Check the modules Process and Node for other functions to handle processes, including spawning functions in nodes.

Inlined by the compiler.

Examples

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

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

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

Check the modules Process and Node for other functions to handle processes, including spawning functions in nodes.

Inlined by the compiler.

Examples

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

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

Check the modules Process and Node for other functions to handle processes, including spawning functions in nodes.

Inlined by the compiler.

Examples

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

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

Check the modules Process and Node for other functions to handle processes, including spawning functions in nodes.

Inlined by the compiler.

Examples

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

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-item tuples (key-value) during enumeration.

If one of the keys in the Enumerable does not exist in the struct, they are automatically discarded.

This function is useful for dynamically creating and updating structs.

Example

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"}

A non-local return from a function. Check Kernel.SpecialForms.try/1 for more information.

Inlined by the compiler.

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

Allowed in guard tests. Inlined by the compiler.

Returns an integer by truncating the given number.

Allowed in guard tests. Inlined by the compiler.

Examples

iex> trunc(5.5)
5

Returns the size of a tuple.

This operation happens in constant time.

Allowed in guard tests. Inlined by the compiler.

Updates a key in a 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> update_in(users, ["john", :age], &(&1 + 1))
%{"john" => %{age: 28}, "meg" => %{age: 23}}

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

Receives any argument and returns true if it is false or nil. Returns false otherwise. Not allowed in guard clauses.

Examples

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

iex> !List.first([])
true

Provides a short-circuit operator that evaluates and returns the second expression only if the first one evaluates to true (i.e. it is not nil nor false). Returns the first expression otherwise.

Examples

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

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

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

iex> false && throw(:bad)
false

Notice that, unlike Erlang’s and operator, this operator accepts any expression as an argument, not only booleans, however it is not allowed in guards.

Returns a range with the specified start and end. Includes both ends.

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

Concatenates two binaries.

Examples

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

The <> operator can also be used in guard clauses as long as the first part is a literal binary:

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

Read and write attributes of th current module.

The canonical example for attributes is annotating that a module implements the OTP behaviour called gen_server:

defmodule MyServer do
  @behaviour :gen_server
  # ... callbacks ...
end

By default Elixir supports all Erlang module attributes, but any developer can also add custom attributes:

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 such attributes to store temporary data. A developer can configure an attribute to behave closer to Erlang by calling 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.

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

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

Boolean and. Requires only the first argument to be a boolean since it short-circuits.

Allowed in guard tests.

Examples

iex> true and false
false

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

The variable name is the key and the variable value is the value.

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]

Defines a function with the given name and contents.

Examples

defmodule Foo do
  def bar, do: :baz
end

Foo.bar #=> :baz

A function that expects arguments can be defined as follow:

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

In the example above, we defined a function sum that receives two arguments and sums them.

Defines the given functions in the current module that will delegate to the given target. Functions defined with defdelegate are public and are allowed to be invoked from external. If you find yourself wishing to define a delegation as private, you should likely use import instead.

Delegation only works with functions, delegating to macros is not supported.

Options

• :to - the expression to delegate to. Any expression is allowed and its results will be calculated on runtime.

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

• :append_first - if true, when delegated, first argument passed to the delegate will be relocated to the end of the arguments when dispatched to the target.

  The motivation behind this is because Elixir normalizes the “handle” as a first argument and some Erlang modules expect it as last argument.

Examples

defmodule MyList do
  defdelegate reverse(list), to: :lists
  defdelegate [reverse(list), map(callback, list)], to: :lists
  defdelegate other_reverse(list), to: :lists, as: :reverse
end

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

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

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 - that receives the arguments given to raise/2 and returns the exception struct. The default implementation accepts a set of keyword arguments that is merged into the struct.

• 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 your exception does not have a message field, this function must be explicitly implemented.

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

Raising exceptions

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

defmodule MyAppError do
  defexception [:message]
end

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 and generate the message in the exception/1 callback:

defmodule MyAppError do
  defexception [:message]

  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 is the preferred mechanism for customizing exception messages.

Defines an implementation for the given protocol. See defprotocol/2 for examples.

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

Defines a macro with the given name and contents.

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

Defines a macro that is private. Private macros are only accessible from the same module in which they are defined.

Check defmacro/2 for more information

Defines a module given by name with the given contents.

It returns the module name, the module binary and the block contents result.

Examples

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

Nesting

Nesting a module inside another module affects its name:

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, allowing the second module Foo.Bar to be accessed as Bar in the same lexical scope.

This means that, if the module Bar is moved to another file, the references to Bar needs to be updated or an alias needs to be explicitly set with the help of Kernel.SpecialForms.alias/2.

Dynamic names

Elixir module names can be dynamically generated. This is very useful for 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 returns 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.

Makes the given functions in the current module overridable. An overridable function is lazily defined, allowing a developer to customize 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 super can be used to call the default implementation.

Defines a function that is private. Private functions are only accessible from within the module in which they are defined.

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

In the example above, sum is private and accessing it through Foo.sum will raise an error.

Defines a protocol.

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

Examples

In Elixir, only false and nil are considered falsy values. Everything else evaluates to true in if clauses. Depending on the application, it may be important to specify a blank? protocol that returns a boolean for other data types that should be considered blank?. For instance, an empty list or an empty binary could be considered blanks.

We could implement this protocol as follow:

defprotocol Blank do
  @doc "Returns true if data is considered blank/empty"
  def blank?(data)
end

Now that the protocol is defined, we can implement it. We need to implement the protocol for each Elixir type. For example:

# Integers are never blank
defimpl Blank, for: Integer do
  def blank?(number), do: false
end

# Just empty list is blank
defimpl Blank, for: List do
  def blank?([]), do: true
  def blank?(_),  do: false
end

# Just the atoms false and nil are blank
defimpl Blank, for: Atom do
  def blank?(false), do: true
  def blank?(nil),   do: true
  def blank?(_),     do: false
end

And we would have to define the implementation for all types. The supported types available are:

• Structs (see below)
• Tuple
• Atom
• List
• BitString
• Integer
• Float
• Function
• PID
• Map
• Port
• Reference
• Any (see below)

Protocols + Structs

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

defimpl Blank, for: [HashDict, HashSet] do
  def blank?(enum_like), do: Enum.empty?(enum_like)
end

If a protocol is not found for a given type, it will fallback to Any.

Fallback to any

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

defprotocol Blank do
  @fallback_to_any true
  def blank?(data)
end

Which can now be implemented as:

defimpl Blank, for: Any do
  def blank?(_), do: true
end

One may wonder why such fallback is not true by default.

It is two-fold: first, the majority of protocols cannot implement an action in a generic way for all types. In fact, providing a default implementation may be harmful, because users may rely on the default implementation instead of providing a specialized one.

Second, falling back to Any adds an extra lookup to all types, which is unnecessary overhead unless an implementation for Any is required.

Types

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

@spec present?(Blank.t) :: boolean
def present?(blank) do
  not Blank.blank?(blank)
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 name when :name is given, and a keyword list with the protocol functions when :functions is given

• 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

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. For this reason, all protocols are compiled with debug_info set to true, regardless of the option set by elixirc compiler. The debug info though may be removed after consolidation.

For more information on how to apply protocol consolidation to a given project, please check the functions in the Protocol module or the mix compile.protocols task.

Defines a struct for the current module.

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 needs to only define a function named __struct__/0 that returns a map with the structs field. This macro is a convenience for defining such function, with the addition of a type t and deriving 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 definition time, which allows them to be dynamic. In the example below, 10 + 11 will be evaluated at compilation time and the age field will be stored with value 21:

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

Deriving

Although structs are maps, by default structs do not implement any of the protocols implemented for maps. For example, if you attempt to use the access protocol with the User struct, it will lead to an error:

%User{}[:age]
** (Protocol.UndefinedError) protocol Access not implemented for %User{...}

However, defstruct/2 allows implementation for protocols to derived by defining a @derive attribute as a list before defstruct/2 is invoked:

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

%User{}[:age] #=> 21

For each protocol given to @derive, Elixir will assert there is an implementation of that protocol for maps and check if the map implementation defines a __deriving__/3 callback. If so, the callback is invoked, otherwise an implementation that simply points to the map one is automatically derived.

Types

It is recommended to define types for structs, by convention this type is called t. To define a struct in a type the struct literal syntax is used:

defmodule User do
  defstruct name: "john", age: 25
  @type t :: %User{name: String.t, age: integer}
end

It is recommended to only use the struct syntax when defining the struct’s type. When referring to another struct use User.t, not %User{}. Fields in the struct not included in the type defaults to term.

Private structs that are not used outside its module should use the private type attribute @typep. Public structs whose internal structure is private to the local module (you are not allowed to pattern match it or directly access fields) should use the @opaque attribute. Structs whose internal structure is public should use @type.

Allows you to destructure two lists, assigning each term in the right to the matching term in the left. 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}

Notice in the example above, even though the right size has more entries than the left, destructuring works fine. If the right size is smaller, the remaining items are simply assigned to nil:

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

The left side supports any expression you would use on the left 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 from the right side. Otherwise, it will raise a CaseClauseError.

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] - access a field; in case an intermediate field is not present or returns nil, an empty map is used

• foo.bar - access 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 field
users

Provides an if macro. This macro expects the first argument to be a condition and the rest are keyword arguments.

One-liner examples

if(foo, do: bar)

In the example above, bar will be returned if foo evaluates to true (i.e. it is 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

Elixir also allows you to pass a block to the if macro. The first example above would be translated to:

if foo do
  bar
end

Notice that do/end becomes delimiters. The second example would then translate to:

if foo do
  bar
else
  baz
end

If you want to compare more than two clauses, you can use the cond/1 macro.

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

Examples

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

This macro simply translates the expression above to:

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

Guards

The in operator can be used on guard clauses as long as the right side is a range or a list. Elixir will then 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 x >= 1 and x <= 3

Checks if the given argument is nil or not. Allowed in guard clauses.

Examples

iex> is_nil(1)
false

iex> is_nil(nil)
true

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

Match can also be used to filter or find a value in an enumerable:

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

Guard clauses can also be given to the match:

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

However, variables assigned in the match will not be available outside of the function call:

iex> match?(x, 1)
true

iex> binding([:x]) == []
true

Boolean or. Requires only the first argument to be a boolean since it short-circuits.

Allowed in guard tests.

Examples

iex> true or false
true

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}}

Raises an exception.

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

If an atom, it will become a call to raise(atom, []).

If anything else, it will just raise the given exception.

Examples

raise "Given values do not match"

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

Raises an exception.

Calls .exception on the given argument passing the attributes in order to retrieve the appropriate exception structure.

Any module defined via defexception/1 automatically implements exception(attrs) callback expected by raise/2.

Examples

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

Raises an exception preserving a previous stacktrace.

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

Notice that System.stacktrace returns the stacktrace of the last exception. That said, it is common to assign the stacktrace as the first expression inside a rescue clause as any other exception potentially raised (and rescued) in between the rescue clause and the raise call may change the System.stacktrace value.

Examples

try do
  raise "Oops"
rescue
  exception ->
    stacktrace = System.stacktrace
    if Exception.message(exception) == "Oops" do
      reraise exception, stacktrace
    end
end

Raises an exception preserving a previous stacktrace.

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

See reraise/2 for more details.

Examples

try do
  raise "Oops"
rescue
  exception ->
    stacktrace = System.stacktrace
    reraise WrapperError, [exception: exception], stacktrace
end

Handles the sigil ~C. It simply returns a char list without escaping characters and without interpolations.

Examples

iex> ~C(foo)
'foo'

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

Handles the sigil ~R. It returns a Regex pattern without escaping nor interpreting interpolations.

Examples

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

Handles the sigil ~S. It simply returns a string without escaping characters and without interpolations.

Examples

iex> ~S(foo)
"foo"

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

Handles the sigil ~W. It returns a list of “words” split by whitespace without escaping nor interpreting interpolations.

Modifiers

• s: strings (default)
• a: atoms
• c: char lists

Examples

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

Handles the sigil ~c. It returns a char list as if it were 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'

Handles the sigil ~r. It returns a Regex pattern.

Examples

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

Handles the sigil ~s. It returns a string as if it was 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"

Handles the sigil ~w. It returns a list of “words” split by whitespace.

Modifiers

• s: strings (default)
• a: atoms
• c: char lists

Examples

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]

Convert the argument to a list according to the List.Chars protocol.

Examples

iex> to_char_list(:foo)
'foo'

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"

Evaluates and returns the do-block passed in as a second argument unless clause evaluates to true. Returns nil otherwise. See also if.

Examples

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

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

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}}

use is a simple mechanism for using a given module into the current context.

Examples

For example, in order to write tests using the ExUnit framework, a developer should use the ExUnit.Case module:

defmodule AssertionTest do
  use ExUnit.Case, async: true

  test "always pass" do
    assert true
  end
end

By calling use, a hook called __using__ will be invoked in ExUnit.Case which will then do the proper setup.

Simply put, use is simply a translation to:

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

  test "always pass" do
    assert true
  end
end

When used inside quoting, marks that the 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.

|> is the pipe operator.

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

Examples

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

The example above is the same as calling List.flatten([1, [2], 3]), i.e. the argument on the left side of |> is introduced as the first argument of the function call on the right side.

This pattern is mostly useful when there is a desire to execute a bunch of operations, resembling a pipeline:

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

The example above will pass the list to List.flatten/1, then get the flattened list and pass to Enum.map/2, which will multiply each entry in the list per two.

In other words, the expression above simply translates to:

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

Beware of operator precedence when using the pipe operator. For example, the following expression:

String.graphemes "Hello" |> Enum.reverse

Translates to:

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

Which will result in an error as Enumerable protocol is not defined for binaries. Adding explicit parenthesis resolves the ambiguity:

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

Or, even better:

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

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

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

Notice that, unlike Erlang’s or operator, this operator accepts any expression as an argument, not only booleans, however it is not allowed in guards.