A record is defined with the following syntax:

The record name and field names must be atoms. The optional default values, which are terms, are used if no value is supplied for a field when a new instance of the record is created. If the default value is not supplied, then the atom undefined is assumed.

For example, in the following record definition, the address field is undefined.

-record(person, {name = "", phone = [], address}).    

This definition of a person will be used in many of the examples which follow.

If the record is used in several modules, its definition should be placed in a .hrl header file. Each module which uses the record definition should have a -include(FileName). statement. For example:

A new record is created with the following syntax:

If any of the fields is omitted, then the default value supplied in the record definition is used. For example:

> #person{phone = [0,8,2,3,4,3,1,2], name = "Robert"}.
{person, "Robert", [0,8,2,3,4,3,1,2], undefined}.          

There is a new feature introduced in Erlang 5.1 (OTP release R8), with which you can set a value to all fields in a record, overriding the defaults in the record specification. The special field _, means "all fields not explicitly specified".

> #person{name = "Jakob", _ = '_'}
{person, "Jakob", '_', '_'}    

It is primarily intended to be used in ets:match/2 and mnesia:match_object/3, to set record fields to the atom '_'. (This is a wildcard in ets:match/2.)

The following syntax is used to select an individual field from a record:

> P = #person{name = "Joe", phone = [0,8,2,3,4,3,1,2]}.
{person, "Joe", [0,8,2,3,4,3,1,2], undefined}
> P#person.name.
"Joe"    

The following syntax is used to create a new copy of the record with some of the fields changed. Only the fields to be changed need to be referred to, all other fields retain their old values.

For example:

> P1 = #person{name="Joe", phone=[1,2,3], address="A street"}.
{person, "Joe", [1,2,3], "A street"}
> P2 = P1#person{name="Robert"}.
{person, "Robert", [1,2,3], "A street"}    

The following guard test is used to test the type of a record:

The following example shows that the guard succeeds if P is record of type person.

foo(P) when record(P, person) -> a_person;
foo(_) -> not_a_person.    

Matching can be used in combination with records as shown in the following example:

> P = #person{name="Joe", phone=[0,0,7], address="A street"}.
{person, "Joe", [0,0,7], "A street"}
> #person{name = Name} = P, Name.
"Joe"    

The following function takes a list of person records and searches for the phone number of a person with a particular name:

The value of a field in a record might be an instance of a record. Retrieval of nested data can be done stepwise, or in a single step, as shown in the following example:

-record(name, {first = "Robert", last = "Ericsson"}).
-record(person, {name = #name{}, phone}).

demo() ->
  P = #person{name= #name{first="Robert",last="Virding"}, phone=123},
  First = (P#person.name)#name.first.    

It is often desirable to write generic functions which will work on any record, not just a record of a particular type. For this reason, records are represented internally as tuples and the ordering of the fields in the tuple is strictly defined.

For example, the record -record(person, {name, phone, address}). is represented internally by the tuple {person, X, Y, Z}.

The arity of the tuple is one more than the number of fields in the tuple. The first element of the tuple is the name of the record, and the elements of the tuple are the fields in the record. The variables X, Y and Z will store the data contained in the record fields.

The following two functions determine the indices in the tuple which refer to the named fields in the record:

In addition, #Rec.Name returns the index in the tuple representation of Name of the record Rec.

For example, the following test function test() might return the result shown:

test() ->
    {record_info(fields, person),
     record_info(size, person),
     #person.name}.    

> Mod:test().
{[name,address,phone],4,2}    

The order in which records map onto tuples is implementation dependent.

%% File: person.hrl

%%-----------------------------------------------------------
%% Data Type: person
%% where:
%%    name:  A string (default is undefined).
%%    age:   An integer (default is undefined).
%%    phone: A list of integers (default is []).
%%    dict:  A dictionary containing various information 
%%           about the person. 
%%           A {Key, Value} list (default is the empty list).
%%------------------------------------------------------------
-record(person, {name, age, phone = [], dict = []}).
    

-module(person).
-include("person.hrl").
-compile(export_all). % For test purposes only.

%% This creates an instance of a person.
%%   Note: The phone number is not supplied so the
%%         default value [] will be used.

make_hacker_without_phone(Name, Age) ->
   #person{name = Name, age = Age, 
           dict = [{computer_knowledge, excellent}, 
                   {drinks, coke}]}.

%% This demonstrates matching in arguments

print(#person{name = Name, age = Age,
              phone = Phone, dict = Dict}) ->
  io:format("Name: ~s, Age: ~w, Phone: ~w ~n" 
            "Dictionary: ~w.~n", [Name, Age, Phone, Dict]).

%% Demonstrates type testing, selector, updating.

birthday(P) when record(P, person) -> 
   P#person{age = P#person.age + 1}.

register_two_hackers() ->
   Hacker1 = make_hacker_without_phone("Joe", 29),
   OldHacker = birthday(Hacker1),
   % The central_register_server should have 
   % an interface function for this.
   central_register_server ! {register_person, Hacker1},
   central_register_server ! {register_person, 
             OldHacker#person{name = "Robert", 
                              phone = [0,8,3,2,4,5,3,1]}}.