View Source Function (Elixir v1.17.0-rc.0)

A set of functions for working with functions.

Anonymous functions are typically created by using fn:

iex> add = fn a, b -> a + b end
iex> add.(1, 2)
3

Anonymous functions can also have multiple clauses. All clauses should expect the same number of arguments:

iex> negate = fn
...>   true -> false
...>   false -> true
...> end
iex> negate.(false)
true

The capture operator

It is also possible to capture public module functions and pass them around as if they were anonymous functions by using the capture operator &/1:

iex> add = &Kernel.+/2
iex> add.(1, 2)
3

iex> length = &String.length/1
iex> length.("hello")
5

To capture a definition within the current module, you can skip the module prefix, such as &my_fun/2. In those cases, the captured function can be public (def) or private (defp).

The capture operator can also be used to create anonymous functions that expect at least one argument:

iex> add = &(&1 + &2)
iex> add.(1, 2)
3

In such cases, using the capture operator is no different than using fn.

Internal and external functions

We say that functions that point to definitions residing in modules, such as &String.length/1, are external functions. All other functions are local and they are always bound to the file or module that defined them.

Besides the functions in this module to work with functions, Kernel also has an apply/2 function that invokes a function with a dynamic number of arguments, as well as is_function/1 and is_function/2, to check respectively if a given value is a function or a function of a given arity.

Summary

Types

information()

Functions

capture(module, function_name, arity)

Captures the given function.

identity(value)

Returns its input value. This function can be passed as an anonymous function to transformation functions.

info(fun)

Returns a keyword list with information about a function.

info(fun, item)

Returns a specific information about the function.

Types

information()

@type information() ::
  :arity
  | :env
  | :index
  | :module
  | :name
  | :new_index
  | :new_uniq
  | :pid
  | :type
  | :uniq

Functions

capture(module, function_name, arity)

(since 1.7.0)

@spec capture(module(), atom(), arity()) :: (... -> any())

Captures the given function.

Inlined by the compiler.

Examples

iex> Function.capture(String, :length, 1)
&String.length/1

identity(value)

(since 1.10.0)

@spec identity(value) :: value when value: var

Returns its input value. This function can be passed as an anonymous function to transformation functions.

Examples

iex> Function.identity("Hello world!")
"Hello world!"

iex> ~c"abcdaabccc" |> Enum.sort() |> Enum.chunk_by(&Function.identity/1)
[~c"aaa", ~c"bb", ~c"cccc", ~c"d"]

iex> Enum.group_by(~c"abracadabra", &Function.identity/1)
%{97 => ~c"aaaaa", 98 => ~c"bb", 99 => ~c"c", 100 => ~c"d", 114 => ~c"rr"}

iex> Enum.map([1, 2, 3, 4], &Function.identity/1)
[1, 2, 3, 4]

info(fun)

(since 1.7.0)

@spec info((... -> any())) :: [{information(), term()}]

Returns a keyword list with information about a function.

The returned keys (with the corresponding possible values) for all types of functions (local and external) are the following:

:type - :local (for anonymous functions) or :external (for named functions).
:module - an atom which is the module where the function is defined when anonymous or the module which the function refers to when it's a named function.
:arity - (integer) the number of arguments the function is to be called with.
:name - (atom) the name of the function.
:env - a list of the environment or free variables. For named functions, the returned list is always empty.

When fun is an anonymous function (that is, the type is :local), the following additional keys are returned:

:pid - PID of the process that originally created the function.
:index - (integer) an index into the module function table.
:new_index - (integer) an index into the module function table.
:new_uniq - (binary) a unique value for this function. It's calculated from the compiled code for the entire module.
:uniq - (integer) a unique value for this function. This integer is calculated from the compiled code for the entire module.

Note: this function must be used only for debugging purposes.

Inlined by the compiler.

Examples

iex> fun = fn x -> x end
iex> info = Function.info(fun)
iex> Keyword.get(info, :arity)
1
iex> Keyword.get(info, :type)
:local

iex> fun = &String.length/1
iex> info = Function.info(fun)
iex> Keyword.get(info, :type)
:external
iex> Keyword.get(info, :name)
:length

info(fun, item)

(since 1.7.0)

@spec info((... -> any()), item) :: {item, term()} when item: information()

Returns a specific information about the function.

The returned information is a two-element tuple in the shape of {info, value}.

For any function, the information asked for can be any of the atoms :module, :name, :arity, :env, or :type.

For anonymous functions, there is also information about any of the atoms :index, :new_index, :new_uniq, :uniq, and :pid. For a named function, the value of any of these items is always the atom :undefined.

For more information on each of the possible returned values, see info/1.

Inlined by the compiler.

Examples

iex> f = fn x -> x end
iex> Function.info(f, :arity)
{:arity, 1}
iex> Function.info(f, :type)
{:type, :local}

iex> fun = &String.length/1
iex> Function.info(fun, :name)
{:name, :length}
iex> Function.info(fun, :pid)
{:pid, :undefined}