Defining structs

section: getting-started layout: getting-started title: Structs redirect_from: /getting-started/struct.html

In chapter 7 we learned about maps:

 map = %{a: 1, b: 2}
 map[:a]
 %{map | a: 3}

Structs are extensions built on top of maps that provide compile-time checks and default values.

Defining structs

To define a struct, the defstruct construct is used:

 defmodule User do
   defstruct name: "John", age: 27
 end

The keyword list used with defstruct defines what fields the struct will have along with their default values.

Structs take the name of the module they’re defined in. In the example above, we defined a struct named User.

We can now create User structs by using a syntax similar to the one used to create maps (if you have defined the struct in a separate file, you can compile the file inside IEx before proceeding by running c "file.exs"; be aware you may get an error saying the struct was not yet defined if you try the below example in a file directly due to when definitions are resolved):

 %User{}
 %User{name: "Jane"}

Structs provide compile-time guarantees that only the fields (and all of them) defined through defstruct will be allowed to exist in a struct:

 %User{oops: :field}

Accessing and updating structs

When we discussed maps, we showed how we can access and update the fields of a map. The same techniques (and the same syntax) apply to structs as well:

 john = %User{}
 john.name
 jane = %{john | name: "Jane"}
 %{jane | oops: :field}

When using the update syntax (|), the VM is aware that no new keys will be added to the struct, allowing the maps underneath to share their structure in memory. In the example above, both john and jane share the same key structure in memory.

Structs can also be used in pattern matching, both for matching on the value of specific keys as well as for ensuring that the matching value is a struct of the same type as the matched value.

 %User{name: name} = john
 name
 %User{} = %{}

Structs are bare maps underneath

In the example above, pattern matching works because underneath structs are bare maps with a fixed set of fields. As maps, structs store a “special” field named __struct__ that holds the name of the struct:

 is_map(john)
 john.__struct__

Notice that we referred to structs as bare maps because none of the protocols implemented for maps are available for structs. For example, you can neither enumerate nor access a struct:

 john = %User{}
 john[:name]
 Enum.each john, fn({field, value}) -> IO.puts(value) end

However, since structs are just maps, they work with the functions from the Map module:

 jane = Map.put(%User{}, :name, "Jane")
 Map.merge(jane, %User{name: "John"})
 Map.keys(jane)

Structs alongside protocols provide one of the most important features for Elixir developers: data polymorphism. That’s what we will explore in the next chapter.

Default values and required keys

If you don’t specify a default key value when defining a struct, nil will be assumed:

 defmodule Product do
   defstruct [:name]
 end
 %Product{}

You can define a structure combining both fields with explicit default values, and implicit nil values. In this case you must first specify the fields which implicitly default to nil:

 defmodule User do
   defstruct [:email, name: "John", age: 27]
 end
 %User{}

Doing it in reverse order will raise a syntax error:

 defmodule User do
   defstruct [name: "John", age: 27, :email]
 end

You can also enforce that certain keys have to be specified when creating the struct:

 defmodule Car do
   @enforce_keys [:make]
   defstruct [:model, :make]
 end
 %Car{}