-spec abs(Float) -> float() when Float :: float();
   (Int) -> non_neg_integer() when Int :: integer().

Returns an integer or float that is the arithmetical absolute value of Float or Int.

For example:

> abs(-3.33).
3.33
> abs(-3).
3

-spec append_element(Tuple1, Term) -> Tuple2 when Tuple1 :: tuple(), Tuple2 :: tuple(), Term :: term().

Returns a new tuple that has one element more than Tuple1, and contains the elements in Tuple1 followed by Term as the last element.

Semantically equivalent to list_to_tuple(tuple_to_list(Tuple1) ++ [Term]), but much faster.

For example:

> erlang:append_element({one, two}, three).
{one,two,three}

-spec atom_to_binary(Atom) -> binary() when Atom :: atom().

Equivalent to atom_to_binary(Atom, utf8).

-spec atom_to_binary(Atom, Encoding) -> binary()
                  when Atom :: atom(), Encoding :: latin1 | unicode | utf8.

Returns a binary corresponding to the text representation of Atom.

If Encoding is latin1, one byte exists for each character in the text representation. If Encoding is utf8 or unicode, the characters are encoded using UTF-8 where characters may require multiple bytes.

Change

As from Erlang/OTP 20, atoms can contain any Unicode character and atom_to_binary(Atom, latin1) may fail if the text representation for Atom contains a Unicode character > 255.

Example:

> atom_to_binary('Erlang', latin1).
<<"Erlang">>

-spec atom_to_list(Atom) -> string() when Atom :: atom().

Returns a list of unicode code points corresponding to the text representation of Atom.

For example:

> atom_to_list('Erlang').
"Erlang"

> atom_to_list('你好').
[20320,22909]

See unicode for how to convert the resulting list to different formats.

-spec binary_part(Subject, PosLen) -> binary()
               when
                   Subject :: binary(),
                   PosLen :: {Start :: non_neg_integer(), Length :: integer()}.

Extracts the part of the binary described by PosLen.

Negative length can be used to extract bytes at the end of a binary.

For example:

1> Bin = <<1,2,3,4,5,6,7,8,9,10>>.
2> binary_part(Bin,{byte_size(Bin), -5}).
<<6,7,8,9,10>>

Failure: badarg if PosLen in any way references outside the binary.

Start is zero-based, that is:

1> Bin = <<1,2,3>>
2> binary_part(Bin,{0,2}).
<<1,2>>

For details about the PosLen semantics, see binary.

-spec binary_part(Subject, Start, Length) -> binary()
               when Subject :: binary(), Start :: non_neg_integer(), Length :: integer().

Equivalent to binary_part(Subject, {Start, Length}).

-spec binary_to_atom(Binary) -> atom() when Binary :: binary().

Equivalent to binary_to_atom(Binary, utf8).

-spec binary_to_atom(Binary, Encoding) -> atom()
                  when Binary :: binary(), Encoding :: latin1 | unicode | utf8.

Returns the atom whose text representation is Binary. If Encoding is utf8 or unicode, the binary must contain valid UTF-8 sequences.

Change

As from Erlang/OTP 20, binary_to_atom(Binary, utf8) is capable of decoding any Unicode character. Earlier versions would fail if the binary contained Unicode characters > 255.

Note

The number of characters that are permitted in an atom name is limited. The default limits can be found in the Efficiency Guide (section System Limits).

Note

There is configurable limit on how many atoms that can exist and atoms are not garbage collected. Therefore, it is recommended to consider whether binary_to_existing_atom/2 is a better option than binary_to_atom/2. The default limits can be found in Efficiency Guide (section System Limits).

Examples:

> binary_to_atom(<<"Erlang">>, latin1).
'Erlang'

> binary_to_atom(<<1024/utf8>>, utf8).
'Ѐ'

-spec binary_to_existing_atom(Binary) -> atom() when Binary :: binary().

Equivalent to binary_to_existing_atom(Binary, utf8).

-spec binary_to_existing_atom(Binary, Encoding) -> atom()
                           when Binary :: binary(), Encoding :: latin1 | unicode | utf8.

As binary_to_atom/2, but the atom must exist.

The Erlang system has a configurable limit for the total number of atoms that can exist, and atoms are not garbage collected. Therefore, it is not safe to create many atoms from binaries that come from an untrusted source (for example, a file fetched from the Internet), for example, using binary_to_atom/2. This function is thus the appropriate option when the input binary comes from an untrusted source.

An atom exists in an Erlang system when included in a loaded Erlang module or when created programmatically (for example, by binary_to_atom/2). See the next note for an example of when an atom exists in the source code for an Erlang module but not in the compiled version of the same module.

Failure: badarg if the atom does not exist.

Note

Note that the compiler may optimize away atoms. For example, the compiler will rewrite atom_to_list(some_atom) to "some_atom". If that expression is the only mention of the atom some_atom in the containing module, the atom will not be created when the module is loaded, and a subsequent call to binary_to_existing_atom(<<"some_atom">>, utf8) will fail.

Note

The number of characters that are permitted in an atom name is limited. The default limits can be found in the Efficiency Guide (section System Limits).

-spec binary_to_float(Binary) -> float() when Binary :: binary().

Returns the float whose text representation is Binary.

For example:

> binary_to_float(<<"2.2017764e+0">>).
2.2017764

The float string format is the same as the format for Erlang float literals except for that underscores are not permitted.

Failure: badarg if Binary contains a bad representation of a float.

-spec binary_to_integer(Binary) -> integer() when Binary :: binary().

Returns an integer whose text representation is Binary.

For example:

> binary_to_integer(<<"123">>).
123

binary_to_integer/1 accepts the same string formats as list_to_integer/1.

Failure: badarg if Binary contains a bad representation of an integer.

-spec binary_to_integer(Binary, Base) -> integer() when Binary :: binary(), Base :: 2..36.

Returns an integer whose text representation in base Base is Binary.

For example:

> binary_to_integer(<<"3FF">>, 16).
1023

binary_to_integer/2 accepts the same string formats as list_to_integer/2.

Failure: badarg if Binary contains a bad representation of an integer.

-spec binary_to_list(Binary) -> [byte()] when Binary :: binary().

Returns a list of integers corresponding to the bytes of Binary.

-spec binary_to_list(Binary, Start, Stop) -> [byte()]
                  when Binary :: binary(), Start :: pos_integer(), Stop :: pos_integer().

As binary_to_list/1, but returns a list of integers corresponding to the bytes from position Start to position Stop in Binary. The positions in the binary are numbered starting from 1.

Note

The one-based indexing for binaries used by this function is deprecated. New code is to use binary:bin_to_list/3 in STDLIB instead. All functions in module binary consistently use zero-based indexing.

-spec binary_to_term(Binary) -> term() when Binary :: ext_binary().

Returns an Erlang term that is the result of decoding binary object Binary, which must be encoded according to the Erlang external term format.

> Bin = term_to_binary(hello).
<<131,100,0,5,104,101,108,108,111>>
> hello = binary_to_term(Bin).
hello

Warning

When decoding binaries from untrusted sources, the untrusted source may submit data in a way to create resources, such as atoms and remote references, that cannot be garbage collected and lead to Denial of Service attack. In such cases, consider using binary_to_term/2 with the safe option.

See also term_to_binary/1 and binary_to_term/2.

-spec binary_to_term(Binary, Opts) -> term() | {term(), Used}
                  when
                      Binary :: ext_binary(),
                      Opt :: safe | used,
                      Opts :: [Opt],
                      Used :: pos_integer().

Equivalent to binary_to_term(Binary), but can be configured to fit special purposes.

The allowed options are:

• safe - Use this option when receiving binaries from an untrusted source.

  When enabled, it prevents decoding data that can be used to attack the Erlang runtime. In the event of receiving unsafe data, decoding fails with a badarg error.

  This prevents creation of new atoms directly, creation of new atoms indirectly (as they are embedded in certain structures, such as process identifiers, refs, and funs), and creation of new external function references. None of those resources are garbage collected, so unchecked creation of them can exhaust available memory.

  > binary_to_term(<<131,100,0,5,"hello">>, [safe]).
  ** exception error: bad argument
  > hello.
  hello
  > binary_to_term(<<131,100,0,5,"hello">>, [safe]).
  hello

  Warning

  The safe option ensures the data is safely processed by the Erlang runtime but it does not guarantee the data is safe to your application. You must always validate data from untrusted sources. If the binary is stored or transits through untrusted sources, you should also consider cryptographically signing it.

• used - Changes the return value to {Term, Used} where Used is the number of bytes actually read from Binary.

  > Input = <<131,100,0,5,"hello","world">>.
  <<131,100,0,5,104,101,108,108,111,119,111,114,108,100>>
  > {Term, Used} = binary_to_term(Input, [used]).
  {hello, 9}
  > split_binary(Input, Used).
  {<<131,100,0,5,104,101,108,108,111>>, <<"world">>}

Failure: badarg if safe is specified and unsafe data is decoded.

See also term_to_binary/1, binary_to_term/1, and list_to_existing_atom/1.

-spec bit_size(Bitstring) -> non_neg_integer() when Bitstring :: bitstring().

Returns an integer that is the size in bits of Bitstring.

For example:

> bit_size(<<433:16,3:3>>).
19
> bit_size(<<1,2,3>>).
24

-spec bitstring_to_list(Bitstring) -> [byte() | bitstring()] when Bitstring :: bitstring().

Returns a list of integers corresponding to the bytes of Bitstring.

If the number of bits in the binary is not divisible by 8, the last element of the list is a bitstring containing the remaining 1-7 bits.

For example:

> bitstring_to_list(<<433:16>>).
[1,177]

> bitstring_to_list(<<433:16,3:3>>).
[1,177,<<3:3>>]

-spec byte_size(Bitstring) -> non_neg_integer() when Bitstring :: bitstring().

Returns an integer that is 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 is rounded up.

For example:

> byte_size(<<433:16,3:3>>).
3
> byte_size(<<1,2,3>>).
3

-spec ceil(Number) -> integer() when Number :: number().

Returns the smallest integer not less than Number.

For example:

> ceil(5.5).
6

-spec decode_packet(Type, Bin, Options) -> {ok, Packet, Rest} | {more, Length} | {error, Reason}
                 when
                     Type ::
                         raw | 0 | 1 | 2 | 4 | asn1 | cdr | sunrm | fcgi | tpkt | line | http |
                         http_bin | httph | httph_bin,
                     Bin :: binary(),
                     Options :: [Opt],
                     Opt :: {packet_size, non_neg_integer()} | {line_length, non_neg_integer()},
                     Packet :: binary() | HttpPacket,
                     Rest :: binary(),
                     Length :: non_neg_integer() | undefined,
                     Reason :: term(),
                     HttpPacket :: HttpRequest | HttpResponse | HttpHeader | http_eoh | HttpError,
                     HttpRequest :: {http_request, HttpMethod, HttpUri, HttpVersion},
                     HttpResponse :: {http_response, HttpVersion, integer(), HttpString},
                     HttpHeader ::
                         {http_header,
                          integer(),
                          HttpField,
                          UnmodifiedField :: HttpString,
                          Value :: HttpString},
                     HttpError :: {http_error, HttpString},
                     HttpMethod ::
                         'OPTIONS' | 'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE' | 'TRACE' |
                         HttpString,
                     HttpUri ::
                         '*' |
                         {absoluteURI,
                          http | https,
                          Host :: HttpString,
                          Port :: inet:port_number() | undefined,
                          Path :: HttpString} |
                         {scheme, Scheme :: HttpString, HttpString} |
                         {abs_path, HttpString} |
                         HttpString,
                     HttpVersion :: {Major :: non_neg_integer(), Minor :: non_neg_integer()},
                     HttpField ::
                         'Cache-Control' | 'Connection' | 'Date' | 'Pragma' |
                         'Transfer-Encoding' | 'Upgrade' | 'Via' | 'Accept' | 'Accept-Charset' |
                         'Accept-Encoding' | 'Accept-Language' | 'Authorization' | 'From' |
                         'Host' | 'If-Modified-Since' | 'If-Match' | 'If-None-Match' |
                         'If-Range' | 'If-Unmodified-Since' | 'Max-Forwards' |
                         'Proxy-Authorization' | 'Range' | 'Referer' | 'User-Agent' | 'Age' |
                         'Location' | 'Proxy-Authenticate' | 'Public' | 'Retry-After' | 'Server' |
                         'Vary' | 'Warning' | 'Www-Authenticate' | 'Allow' | 'Content-Base' |
                         'Content-Encoding' | 'Content-Language' | 'Content-Length' |
                         'Content-Location' | 'Content-Md5' | 'Content-Range' | 'Content-Type' |
                         'Etag' | 'Expires' | 'Last-Modified' | 'Accept-Ranges' | 'Set-Cookie' |
                         'Set-Cookie2' | 'X-Forwarded-For' | 'Cookie' | 'Keep-Alive' |
                         'Proxy-Connection' | HttpString,
                     HttpString :: string() | binary().

Decodes the binary Bin according to the packet protocol specified by Type. Similar to the packet handling done by sockets with option {packet,Type}.

If an entire packet is contained in Bin, it is returned together with the remainder of the binary as {ok,Packet,Rest}.

If Bin does not contain the entire packet, {more,Length} is returned. Length is either the expected total size of the packet, or undefined if the expected packet size is unknown. decode_packet can then be called again with more data added.

If the packet does not conform to the protocol format, {error,Reason} is returned.

Types:

• raw | 0 - No packet handling is done. The entire binary is returned unless it is empty.

• 1 | 2 | 4 - Packets consist of a header specifying the number of bytes in the packet, followed by that number of bytes. The length of the header can be one, two, or four bytes; the order of the bytes is big-endian. The header is stripped off when the packet is returned.

• line - A packet is a line-terminated by a delimiter byte, default is the latin-1 newline character. The delimiter byte is included in the returned packet unless the line was truncated according to option line_length.

• asn1 | cdr | sunrm | fcgi | tpkt - The header is not stripped off.

  The meanings of the packet types are as follows:

  • asn1 - ASN.1 BER

  • sunrm - Sun's RPC encoding

  • cdr - CORBA (GIOP 1.1)

  • fcgi - Fast CGI

  • tpkt - TPKT format [RFC1006]

• http | httph | http_bin | httph_bin - The Hypertext Transfer Protocol. The packets are returned with the format according to HttpPacket described earlier. A packet is either a request, a response, a header, or an end of header mark. Invalid lines are returned as HttpError.

  Recognized request methods and header fields are returned as atoms. Others are returned as strings. Strings of unrecognized header fields are formatted with only capital letters first and after hyphen characters, for example, "Sec-Websocket-Key". Header field names are also returned in UnmodifiedField as strings, without any conversion or formatting.

  The protocol type http is only to be used for the first line when an HttpRequest or an HttpResponse is expected. The following calls are to use httph to get HttpHeaders until http_eoh is returned, which marks the end of the headers and the beginning of any following message body.

  The variants http_bin and httph_bin return strings (HttpString) as binaries instead of lists.

  Since OTP 26.0, Host may be an IPv6 address enclosed in [], as defined in RFC2732 .

Options:

• {packet_size, integer() >= 0} - Sets the maximum allowed size of the packet body. If the packet header indicates that the length of the packet is longer than the maximum allowed length, the packet is considered invalid. Defaults to 0, which means no size limit.

• {line_length, integer() >= 0} - For packet type line, lines longer than the indicated length are truncated.

  Option line_length also applies to http* packet types as an alias for option packet_size if packet_size itself is not set. This use is only intended for backward compatibility.

• {line_delimiter, 0 =< byte() =< 255} - For packet type line, sets the delimiting byte. Default is the latin-1 character $\n.

Examples:

> erlang:decode_packet(1,<<3,"abcd">>,[]).
{ok,<<"abc">>,<<"d">>}
> erlang:decode_packet(1,<<5,"abcd">>,[]).
{more,6}

-spec delete_element(Index, Tuple1) -> Tuple2
                  when Index :: pos_integer(), Tuple1 :: tuple(), Tuple2 :: tuple().

Returns a new tuple with element at Index removed from tuple Tuple1.

For example:

> erlang:delete_element(2, {one, two, three}).
{one,three}

-spec display(Term) -> true when Term :: term().

Prints a text representation of Term on the standard output.

Warning

This BIF is intended for debugging only. The printed representation may contain internal details that do not match the high-level representation of the term in Erlang.

-spec element(N, Tuple) -> term() when N :: pos_integer(), Tuple :: tuple().

Returns the Nth element (numbering from 1) of Tuple.

For example:

> element(2, {a, b, c}).
b

-spec external_size(Term) -> non_neg_integer() when Term :: term().

Calculates, without doing the encoding, the maximum byte size for a term encoded in the Erlang external term format.

The following condition applies always:

> Size1 = byte_size(term_to_binary(Term)),
> Size2 = erlang:external_size(Term),
> true = Size1 =< Size2.
true

This is equivalent to a call to:

erlang:external_size(Term, [])

-spec external_size(Term, Options) -> non_neg_integer()
                 when
                     Term :: term(),
                     Options ::
                         [compressed |
                          {compressed, Level :: 0..9} |
                          deterministic |
                          {minor_version, Version :: 0..2} |
                          local].

Calculates, without doing the encoding, the maximum byte size for a term encoded in the Erlang external term format.

The following condition applies always:

> Size1 = byte_size(term_to_binary(Term, Options)),
> Size2 = erlang:external_size(Term, Options),
> true = Size1 =< Size2.
true

Option {minor_version, Version} specifies how floats are encoded. For a detailed description, see term_to_binary/2.

-spec float(Number) -> float() when Number :: number().

Returns a float by converting Number to a float.

For example:

> float(55).
55.0

Note

If used on the top level in a guard, it tests whether the argument is a floating point number; for clarity, use is_float/1 instead.

When float/1 is used in an expression in a guard, such as 'float(A) == 4.0', it converts a number as described earlier.

-spec float_to_binary(Float) -> binary() when Float :: float().

Equivalent to float_to_binary(Float, [{scientific, 20}]).

-spec float_to_binary(Float, Options) -> binary()
                   when
                       Float :: float(),
                       Options :: [Option],
                       Option ::
                           {decimals, Decimals :: 0..253} |
                           {scientific, Decimals :: 0..249} |
                           compact | short.

Returns a binary corresponding to the text representation of Float using fixed decimal point formatting.

Options behaves in the same way as float_to_list/2.

For example:

> float_to_binary(7.12, [{decimals, 4}]).
<<"7.1200">>
> float_to_binary(7.12, [{decimals, 4}, compact]).
<<"7.12">>
> float_to_binary(7.12, [{scientific, 3}]).
<<"7.120e+00">>
> float_to_binary(7.12, [short]).
<<"7.12">>
> float_to_binary(0.1+0.2, [short]).
<<"0.30000000000000004">>
> float_to_binary(0.1+0.2)
<<"3.00000000000000044409e-01">>

-spec float_to_list(Float) -> string() when Float :: float().

Equivalent to float_to_list(Float, [{scientific, 20}]).

-spec float_to_list(Float, Options) -> string()
                 when
                     Float :: float(),
                     Options :: [Option],
                     Option ::
                         {decimals, Decimals :: 0..253} |
                         {scientific, Decimals :: 0..249} |
                         compact | short.

Returns a string corresponding to the text representation of Float using fixed decimal point formatting.

Available options:

• If option decimals is specified, the returned value contains at most Decimals number of digits past the decimal point. If the number does not fit in the internal static buffer of 256 bytes, the function throws badarg.
• If option compact is specified, the trailing zeros at the end of the list are truncated. This option is only meaningful together with option decimals.
• If option scientific is specified, the float is formatted using scientific notation with Decimals digits of precision.
• If option short is specified, the float is formatted with the smallest number of digits that still guarantees that F =:= list_to_float(float_to_list(F, [short])). When the float is inside the range (-2⁵³, 2⁵³), the notation that yields the smallest number of characters is used (scientific notation or normal decimal notation). Floats outside the range (-2⁵³, 2⁵³) are always formatted using scientific notation to avoid confusing results when doing arithmetic operations.
• If Options is [], the function behaves as float_to_list/1.

Examples:

> float_to_list(7.12, [{decimals, 4}]).
"7.1200"
> float_to_list(7.12, [{decimals, 4}, compact]).
"7.12"
> float_to_list(7.12, [{scientific, 3}]).
"7.120e+00"
> float_to_list(7.12, [short]).
"7.12"
> float_to_list(0.1+0.2, [short]).
"0.30000000000000004"
> float_to_list(0.1+0.2)
"3.00000000000000044409e-01"

In the last example, float_to_list(0.1+0.2) evaluates to "3.00000000000000044409e-01". The reason for this is explained in Representation of Floating Point Numbers.

-spec floor(Number) -> integer() when Number :: number().

Returns the largest integer not greater than Number.

For example:

> floor(-10.5).
-11

-spec fun_info(Fun) -> [{Item, Info}]
            when
                Fun :: function(),
                Item ::
                    arity | env | index | name | module | new_index | new_uniq | pid | type | uniq,
                Info :: term().

Returns a list with information about the fun Fun. Each list element is a tuple. The order of the tuples is undefined, and more tuples can be added in a future release.

Warning

This BIF is mainly intended for debugging, but it can sometimes be useful in library functions that need to verify, for example, the arity of a fun.

Two types of funs have slightly different semantics:

• A fun created by fun M:F/A is called an external fun. Calling it will always call the function F with arity A in the latest code for module M. Notice that module M does not even need to be loaded when the fun fun M:F/A is created.
• All other funs are called local. When a local fun is called, the same version of the code that created the fun is called (even if a newer version of the module has been loaded).

The following elements are always present in the list for both local and external funs:

• {type, Type} - Type is local or external.

• {module, Module} - Module (an atom) is the module name.

  If Fun is a local fun, Module is the module in which the fun is defined.

  If Fun is an external fun, Module is the module that the fun refers to.

• {name, Name} - Name (an atom) is a function name.

  If Fun is a local fun, Name is the name of the local function that implements the fun. (This name was generated by the compiler, and is only of informational use. As it is a local function, it cannot be called directly.) If no code is currently loaded for the fun, [] is returned instead of an atom.

  If Fun is an external fun, Name is the name of the exported function that the fun refers to.

• {arity, Arity} - Arity is the number of arguments that the fun is to be called with.

• {env, Env} - Env (a list) is the environment or free variables for the fun. For external funs, the returned list is always empty.

The following elements are only present in the list if Fun is local:

• {pid, Pid} - Pid is the process identifier of the process that originally created the fun.

  It might point to the init process if the Fun was statically allocated when module was loaded (this optimisation is performed for local functions that do not capture the environment).

  Change

  In Erlang/OTP 27, we plan to change the return value so that it always points to the local init process, regardless of which process or node the fun was originally created on. See Upcoming Potential Incompatibilities .

• {index, Index} - Index (an integer) is an index into the module fun table.

• {new_index, Index} - Index (an integer) is an index into the module fun table.

• {new_uniq, Uniq} - Uniq (a binary) is a unique value for this fun. It is calculated from the compiled code for the entire module.

• {uniq, Uniq} - Uniq (an integer) is a unique value for this fun. As from Erlang/OTP R15, this integer is calculated from the compiled code for the entire module. Before Erlang/OTP R15, this integer was based on only the body of the fun.

-spec fun_info(Fun, Item) -> {Item, Info}
            when Fun :: function(), Item :: fun_info_item(), Info :: term().

Returns information about Fun as specified by Item, in the form {Item,Info}.

For any fun, Item can be any of the atoms module, name, arity, env, or type.

For a local fun, Item can also be any of the atoms index, new_index, new_uniq, uniq, and pid. For an external fun, the value of any of these items is always the atom undefined.