> ## 8 Records

> A record is a data structure for storing a fixed number of elements. It has named fields and is similar to a struct in C. Record expressions are translated to tuple expressions during compilation. Therefore, record expressions are not understood by the shell.

> Read more about records in Programming Examples.

> ### 8.1 Defining Records

> A record definition consists of the name of the record, followed by the field names of the record. Record and field names must be atoms. Each field can be given an optional default value. If no default value is supplied, `undefined` will be used.

>     -record(Name, {Field1 [= Value1],
>                    ...
>                    FieldN [= ValueN]}).

> A record definition can be placed anywhere among the attributes and function declarations of a module, but the definition must come before any usage of the record.

> If a record is used in several modules, it is recommended that the record definition is placed in an include file.

> ### 8.2 Creating Records

> The following expression creates a new `Name` record where the value of each field `FieldI` is the value of evaluating the corresponding expression `ExprI`:

>     #Name{Field1=Expr1,...,FieldK=ExprK}

> The fields may be in any order, not necessarily the same order as in the record definition, and fields can be omitted. Omitted fields will get their respective default value instead.

> If several fields should be assigned the same value, the following construction can be used:

>     #Name{Field1=Expr1,...,FieldK=ExprK, _=ExprL}

> Omitted fields will then get the value of evaluating `ExprL` instead of their default values. This feature was added in Erlang 5.1/OTP R8 and is primarily intended to be used to create patterns for ETS and Mnesia match functions. Example:

>     -record(person, {name, phone, address}).

>     ...

>     lookup(Name, Tab) ->
>         ets:match_object(Tab, #person{name=Name, _='_'}).

> ### 8.3 Accessing Record Fields

>     Expr#Name.Field

> Returns the value of the specified field. `Expr` should evaluate to a `Name` record.

> The following expression returns the position of the specified field in the tuple representation of the record:

>     #Name.Field

> Example:

>     -record(person, {name, phone, address}).

>     ...

>     lookup(Name, List) ->
>         lists:keysearch(Name, #person.name, List).

> ### 8.4 Updating Records

>     Expr#Name{Field1=Expr1,...,FieldK=ExprK}

> `Expr` should evaluate to a `Name` record. Returns a copy of this record, with the value of each specified field `FieldI` changed to the value of evaluating the corresponding expression `ExprI`. All other fields retain their old valules.

> ### 8.5 Records in Guards

> Accessing record fields using `Expr#Name.Field` is allowed in guards. There is also a type test BIF `is_record(Var, Name)`. Example:

>     is_person(P) when record(P, person) ->
>         true;
>     is_person(_P) ->
>         false.

> ### 8.6 Records in Patterns

> A pattern that will match a certain record is created the same way as a record is created:

>     #Name{Field1=Expr1,...,FieldK=ExprK}

> In this case, one or more of `Expr1`...`ExprK` may be unbound variables.

> ### 8.7 Internal Representation of Records

> Record expressions are translated to tuple expressions during compilation. A record defined as

>     -record(Name, {Field1,...,FieldN}).

> is internally represented by the tuple

>     {Name,Value1,...,ValueN}

> where each `ValueI` is the default value for `FieldI`.

> To each module using records, a pseudo function is added during compilation to obtain information about records:

>     record_info(fields, Record) -> [Field]
>     record_info(size, Record) -> Size

> `Size` is the size of the tuple representation, that is one more than the number of fields.

Copyright © 1991-2003 Ericsson Utvecklings AB