Distributed Life

Built-in Functions (BIFs)

Erlang’s Built-in Functions (shorthand BIFs) are commonly used functions that are intergrated into the Erlang’s VM for performance reasons. Most of them belong to the erlang module, but there are some in other modules, such as lists.

The BIFs can be separated to standard and non-standard. The standard ones are auto-imported; they can be called without the use of the module name prefix (remember the effect of the -import(...) directive). On the other hand, the non-standard ones have to be called following the normal module:function(...) convension. In the erlang module’s man pages (here) the distinction between standard and non-standard is visible by the lack or existence of the erlang (module’s name) prefix.

elrang

abs/1

Arithmetic absolut value of an integer or float.

erlang:append_element/2

Appends an element to a tuple.

apply/2|3

Calls the function passed as a parameter.

atom_to_list/1

Returns a string which corresponds to the text representation of Atom.

date/0

Returns the date in the {Year, Month, Day} format.

element/2

Called as element(N, Tuple). Returns the Nth of the Tuple.

error/1|2

Stops the execution with an error Reason.

exit/1|2

Stops the execution with an exit Reason.

float/1

Converts the number to float.

float_to_list/1

Returns a string which corresponds to the text representation of Float.

hd/1

Returns the head of a list (the first element).

integer_to_list/1|2

Returns a string which corresponds to the text representation of Integer.

is_atom/1

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

is_boolean/1

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

is_float/1

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

is_integer/1

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

is_list/1

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

is_number/1

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

is_tuple/1

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

length/1

Returns the length of a list.

list_to_atom/1

Returns the atom whose text representation is String.

list_to_existing_atom/1

Returns the atom whose text representation is String, but only if there already exists such atom.

Failure: badarg if there does not already exist an atom whose text representation is String.

2> erlang:loaded().
[otp_internal,lib,shell_default,erl_internal,edlin_expand,
 sets,ordsets,erl_lint,unicode,io,erl_scan,erl_parse,epp,
 filelib,ram_file,beam_lib,file_io_server,orddict,erl_eval,
 file,c,error_logger_tty_h,kernel_config,shell,io_lib_format,
 proplists,io_lib,edlin,group|...]
3> list_to_existing_atom("lib").
lib
4> list_to_existing_atom("lib11").
** exception error: bad argument
     in function  list_to_existing_atom/1
        called as list_to_existing_atom("lib11")

list_to_float/1

Returns the float whose text representation is String.

list_to_integer/1|2

Returns an integer whose text representation is String.

list_to_tuple/1

Returns a tuple which corresponds to List. List can contain any Erlang terms.

erlang:loaded/0

Returns a list of all loaded Erlang modules.

erlang:localtime/0

Returns the current local time and date in the format {{Year, Month, Date}, {Hour, Minute, Second}}.

max/2

Returns the maximum between two terms, or the first one if equal.

min/2

Returns the minimum between two terms, or the first one if equal.

now/0

Returns the tuple {MegaSecs, Secs, MicroSecs} which is the elapsed time since 00:00 GMT, January 1, 1970 (zero hour).

round/1

Returns the integer resulting by rounding the input.

self/0

Return the process identifier (Pid) of the current process. This function will be used extensively in the next post and what is a Pid will be explained in more detail.

erlang:send/2

Called as erlang:send(Dest, Msg). Sends message Msg to Dest. This is equivalent with Dest ! Msg. We will see the details of message passing in an upcoming post.

setelement/3

Returns a new tuple where the value of the specified element is set to the one provided.

size/1

Returns the size of the provided tuple or binary.

spawn/1|2|3|4

Creates a new process and returns its Pid. It is one of the most important and used functions in Erlang. There will be a dedicated post about processes.

throw/1

A non-local return from a function. If evaluated within a catch, catch will return the value Any (called as throw(Any)).

7> throw(my_exception).
** exception throw: my_exception
8> catch throw(my_exception).
my_exception

time/0

Returns the local time in {Hours, Minutes, Seconds} format.

tl/1/

Returns the tail of a list (the list without its head element).

trunc/1

Returns an integer by truncating the provided number.

tuple_size/1

Returns the size of the provided tuple.

tuple_to_list/1

Returns a list which corresponds to Tuple. Tuple may contain any Erlang terms.

Preexisting Modules

Erlang comes with tons of predefined general purpose or specialized modules. In the majority of the cases, if Erlang provides a function with the functionality you need, you would prefer to use it instead of reimplementing it for three main reasons: (1) why reinventing the wheel, (2) performance, (3) difficult to program.

I will present some of the modules that I consider the most important/useful. A full list of the existing Erlang’s (Erlang/OTP to be precise) modules can be found here.

debugger

This is the module used to start the Erlang debugger for debugging and testing Erlang programs. Details here. There will be a post about debugging in the future, so do not worry for now.

start/0|1|2

Starts the debugger.

file

Functions used to read and manipulate files. Details here.

open/2

Opens a file.

close/1

Closes an opened file.

read/2, read_file/1, read_line/1, pread/2|3

Reading from a file.

write/2, write_file/2|3, pwrite/2|3

Writing to a file.

position/2

Moves the current pointer in a file.

rename/2

Renames a file.

copy/2|3

Copies the contents of a file to another.

list_dir/1, make_dir/1, delete_dir/1

List, create, and delete directories.

io

Functions related to input/output. Details here.

format/1|2|3

Write formatted output to the standard output. (similar to printf in C)

11> io:format("Hello World~n").        
Hello World
ok

read/1|2, read_line/1|2, get_chars/2|3

Reads a term, a line, or a number of chars from the standard input.

lists

Functions related to lists. Details here. The next post will be focusing on lists and the lists module, so I do not present them here.

math

Mathematical functions (sin/1, cos/1, tan/1, exp/1, log/1, pow/2, sqrt/1, etc). Details here.

pman

A graphical process manager tool used to inspect the Erlang processes executing either locally or on remote nodes. It is also possible to trace events in the individual processes. Details here. We will use this module in the post about debugging.

start/0|1

Starts the process manager.

proc/1|3

Starts a process manager for a specific process.

string

Functions related to strings. Details here.

len/1

Returns the number of characters of a string.

equal/2

Test two strings for equality.

concat/2

Concatenates two strings and returns the results.

str/2, rstr/2

Returns the position where the first/last occurrence of a substring begins in a string. 0 is returned if substring does not exist in the string.

substr/2|3

Returns the substring of a string.

to_lower/1, to_upper/1

Case convertion.

timer

This module provides useful functions related to time. Details here.

apply_after/4

Apply a function after a given time.

send_after/2|3

Send a message to a process after a given time.

tc/2|3

Returns {Time, Value}, where Time is the microseconds that the execution took and Value is the result of the applied function.

14> timer:tc(erlang, length, [[1, 2, 3, 4, 5, 6, 7]]).
{6,7} %r esult 7 in 6 microseconds

now_diff/2

Returns the difference between two different “now values” (got by calling now()) in microseconds.

15> Now_old = now().
{1302,680891,260499}
16> Now_new = now().
{1302,680895,780496}
17> timer:now_diff(Now_new, Now_old).
4519997

Next

The next post will be dedicated to lists and the lists module.