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.

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, _='_'}).

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).

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 values.

Since record expressions are expanded to tuple expressions, creating records and accessing record fields are allowed in guards. However all subexpressions, for example for field initiations, must of course be valid guard expressions as well. Examples:

There is also a type test BIF is_record(Term, RecordTag). Example:

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

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.

Beginning with R14 parentheses when accessing or updating nested records can be omitted. Assuming we have the following record definitions:

-record(nrec0, {name = "nested0"}).
-record(nrec1, {name = "nested1", nrec0=#nrec0{}}).
-record(nrec2, {name = "nested2", nrec1=#nrec1{}}).

N2 = #nrec2{},
    

Before R14 you would have needed to use parentheses as following:

"nested0" = ((N2#nrec2.nrec1)#nrec1.nrec0)#nrec0.name,
N0n = ((N2#nrec2.nrec1)#nrec1.nrec0)#nrec0{name = "nested0a"},
    

Since R14 you can also write:

"nested0" = N2#nrec2.nrec1#nrec1.nrec0#nrec0.name,
N0n = N2#nrec2.nrec1#nrec1.nrec0#nrec0{name = "nested0a"},

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.

In addition, #Record.Name returns the index in the tuple representation of Name of the record Record. Name must be an atom.