path: root/system/doc/extensions/records.xml

<?xml version="1.0" encoding="latin1" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">

<chapter>
  <header>
    <copyright>
      <year>1997</year>
      <year>2007</year>
      <holder>Ericsson AB, All Rights Reserved</holder>
    </copyright>
    <legalnotice>
  The contents of this file are subject to the Erlang Public License,
  Version 1.1, (the "License"); you may not use this file except in
  compliance with the License. You should have received a copy of the
  Erlang Public License along with this software. If not, it can be
  retrieved online at http://www.erlang.org/.

  Software distributed under the License is distributed on an "AS IS"
  basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
  the License for the specific language governing rights and limitations
  under the License.

  The Initial Developer of the Original Code is Ericsson AB.
    </legalnotice>

    <title>Records</title>
    <prepared>Joe Armstrong</prepared>
    <responsible>Bjarne D&auml;cker</responsible>
    <docno>1</docno>
    <approved>Bjarne D&auml;Ker</approved>
    <checked></checked>
    <date>96-09-10</date>
    <rev>PA1</rev>
    <file>records.sgml</file>
  </header>
  <p>A record is a data structure intended for storing a fixed number of related data items. It is
    similar to a <c>struct</c> in C, or a <c>record</c> in Pascal. </p>
  <p>The main advantage of using records instead of tuples is that fields in a record are accessed by name, whereas fields in a tuple are accessed by position. To illustrate these differences, suppose that we want to represent a person with the <em>tuple</em><c>{Name, Address, Phone}</c>.</p>
  <p>We must remember that the <c>Name</c> field is the first element of the tuple, the <c>Address</c> field is the second element, and so on, in order to write functions which manipulate this data. For example, to extract data from a variable <c>P</c> which contains such a tuple we might write the following code and then use pattern matching to extract the relevant fields.</p>
  <code type="none">

Name = element(1, P),
Address = element(2, P),
...  </code>
  <p>Code like this is difficult to read and understand and errors occur if we get the numbering of the elements in the tuple wrong. If we change the data representation by re-ordering the fields, or by adding or removing a field, then all references to the person tuple, wherever they occur, must be checked and possibly modified.</p>
  <p><em>Records</em> allow us to refer to the fields by name and not position. We use a record instead of a tuple to store the data . If we write a record definition of the type shown below, we can then refer to the fields of the record by name.</p>
  <code type="none">

-record(person, {name, phone, address}).  </code>
  <p>For example, if <c>P</c> is now a variable whose value is a <c>person</c> record, we can code as follows in order  to access the name and address fields of the records.</p>
  <code type="none">

Name = P#person.name,
Address = P#person.address,
...  </code>
  <p>In the following sections we describe the different operations which can be performed on records:</p>

  <section>
    <title>Defining a Record</title>
    <p>A record is defined with the following syntax:</p>
    <code type="none">

-record(RecordName, {Field1 [= DefaultValue1],
                     Field2 [= DefaultValue2],
                     ...,
                     FieldN [= DefaultValueN]}).    </code>
    <p>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 <c>undefined</c> is assumed.</p>
    <p>For example, in the following record definition, the address field is <c>undefined</c>.</p>
    <pre>
-record(person, {name = "", phone = [], address}).    </pre>
    <p>This definition of a person will be used in many of the examples which follow.</p>
  </section>

  <section>
    <title>Including a Record Definition</title>
    <p>If the record is used in several modules, its definition should be placed in a <c>.hrl</c> header file. Each module which uses the record definition should have a <c>-include(FileName).</c> statement. For example:</p>
    <code type="none">

-include("my_data_structures.hrl").    </code>
    <note>
      <p>The definition of the record must come before it is used.</p>
    </note>
  </section>

  <section>
    <title>Creating a Record</title>
    <p>A new record is created with the following syntax:</p>
    <code type="none">

#RecordName{Field1=Expr1,
             ...,
            FieldM=ExprM}.    </code>
    <p>If any of the fields is omitted, then the default value supplied in the record definition is used. For example:</p>
    <pre>
> #person{phone = [0,8,2,3,4,3,1,2], name = "Robert"}.
{person, "Robert", [0,8,2,3,4,3,1,2], undefined}.          </pre>
    <p>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 <c>_</c>, means "all fields not explicitly specified".</p>
    <pre>
> #person{name = "Jakob", _ = '_'}
{person, "Jakob", '_', '_'}    </pre>
    <p>It is primarily intended to be used in <c>ets:match/2</c> and
      <c>mnesia:match_object/3</c>, to set record fields to the atom
      <c>'_'</c>. (This is a wildcard in <c>ets:match/2</c>.)</p>
  </section>

  <section>
    <title>Selectors</title>
    <p>The following syntax is used to select an individual field from a record:</p>
    <code type="none">

Variable#RecordName.Field    </code>
    <note>
      <p>The values contained in record names and fields must be constants, not variables.</p>
    </note>
    <note>
      <p>For the purposes of illustration, we will demonstrate the use of records using an imaginary dialogue with the Erlang shell. Currently the Erlang evaluator does not support records so you may not be able to reproduce this dialogue.</p>
    </note>
    <pre>

> <input>P = #person{name = "Joe", phone = [0,8,2,3,4,3,1,2]}.</input>
{person, "Joe", [0,8,2,3,4,3,1,2], undefined}
> <input>P#person.name.</input>
"Joe"    </pre>
    <note>
      <p>Selectors for records are allowed in guards.</p>
    </note>
  </section>

  <section>
    <title>Updating a Record</title>
    <p>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.</p>
    <code type="none">

OldVariable#RecordName{Field1 = NewValue1,
                              ...,
                       FieldM = NewValueM}    </code>
    <p>For example:</p>
    <pre>
> 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"}    </pre>
  </section>

  <section>
    <title>Type Testing</title>
    <p>The following guard test is used to test the type of a record:</p>
    <code type="none">

record(Variable, RecordName)    </code>
    <p>The following example shows that the guard succeeds if <c>P</c> is record of type <c>person</c>.</p>
    <pre>
foo(P) when record(P, person) -> a_person;
foo(_) -> not_a_person.    </pre>
    <note>
      <p>This test checks that <c>P</c> is a tuple of arity <c>N + 1</c>, where <c>N</c> is the number
        of fields in the record, and the first element in the tuple is the atom <c>person</c>.</p>
    </note>
  </section>

  <section>
    <title>Pattern Matching</title>
    <p>Matching can be used in combination with records as shown in the following example:</p>
    <pre>
> P = #person{name="Joe", phone=[0,0,7], address="A street"}.
{person, "Joe", [0,0,7], "A street"}
> #person{name = Name} = P, Name.
"Joe"    </pre>
    <p>The following function takes a list of <c>person</c> records and searches for the phone number of a person with a particular name:</p>
    <code type="none">

find_phone([#person{name=Name, phone=Phone} | _], Name) ->
    {found,  Phone};
find_phone([_| T], Name) ->
    find_phone(T, Name);
find_phone([], Name) ->
    not_found.    </code>
    <note>
      <p>The fields referred to in the pattern can be given in any order.</p>
    </note>
  </section>

  <section>
    <title>Nested Records</title>
    <p>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:</p>
    <pre>
-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.    </pre>
    <note>
      <p>In this example, <c>demo()</c> evaluates to <c>"Robert"</c>.</p>
    </note>
  </section>

  <section>
    <title>Internal Representation of Records</title>
    <p>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.</p>
    <p>For example, the record <c>-record(person, {name, phone, address}).</c> is represented internally by the tuple <c>{person, X, Y, Z}</c>.</p>
    <p>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 <c>X</c>, <c>Y</c> and <c>Z</c> will store the data contained in the record fields.</p>
    <p>The following two functions determine the indices in the tuple which refer to the named fields in the record:</p>
    <list type="bulleted">
      <item><c>record_info(fields, Rec) -> [Names]</c>. This function returns the names of the fields in the record <c>Rec</c>. For example, <c>record_info(fields, person)</c> evaluates to <c>[name, address, phone]</c>.</item>
      <item><c>record_info(size, Rec) -> Size</c>. This function returns the size of the record <c>Rec</c> when represented as a tuple, which is one more than the number of fields. For example, <c>record_info(size, person)</c> returns <c>4</c>.</item>
    </list>
    <p>In addition, <c>#Rec.Name</c> returns the index in the tuple representation of <c>Name</c> of the record <c>Rec</c>.</p>
    <note>
      <p><c>Name</c> must be an atom.</p>
    </note>
    <p>For example, the following test function <c>test()</c> might return the result shown:</p>
    <pre>
test() ->
    {record_info(fields, person),
     record_info(size, person),
     #person.name}.    </pre>
    <pre>
> <input>Mod:test().</input>
{[name,address,phone],4,2}    </pre>
    <p>The order in which records map onto tuples is implementation dependent.</p>
    <note>
      <p><c>record_info</c> is a pseudo-function which cannot be exported from the module where it occurs.</p>
    </note>
  </section>

  <section>
    <title>Example</title>
    <pre>
%% 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 = []}).
    </pre>
    <pre>
-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]}}.    </pre>
  </section>
</chapter>