Update structs.md

Author: ice-cap0

lib/elixir/pages/getting-started/structs.md

@@ -2,6 +2,7 @@
   SPDX-License-Identifier: Apache-2.0
   SPDX-FileCopyrightText: 2021 The Elixir Team
 -->
+
 # Structs
 
 We learned about maps [in earlier chapters](keywords-and-maps.md):
@@ -19,7 +20,7 @@ Structs are extensions built on top of maps that provide compile-time checks and
 
 ## Defining structs
 
-To define a struct, the [`defstruct/1`](https://hexdocs.pm/elixir/Kernel.html#defstruct/1) construct is used:
+To define a struct, the `defstruct/1` construct is used:
 
 ```elixir
 iex> defmodule User do
@@ -29,9 +30,7 @@ iex> defmodule User do
 
 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`.
 
-## Creating structs
-
-We can create `User` structs by using a syntax similar to the one used to create maps:
+We can now create `User` structs by using a syntax similar to the one used to create maps:
 
 ```elixir
 iex> %User{}
@@ -47,129 +46,26 @@ iex> %User{oops: :field}
 ** (KeyError) key :oops not found expanding struct: User.__struct__/1
 ```
 
-You can also create structs using `Kernel.struct/2`:
-
-```elixir
-iex> struct(User)
-%User{age: 27, name: "John"}
-iex> struct(User, name: "Jane")
-%User{age: 27, name: "Jane"}
-iex> struct(User, %{name: "Jane", age: 30})
-%User{age: 30, name: "Jane"}
-```
-
-### Default values and required keys
-
-If you don't specify a default key value when defining a struct, `nil` will be assumed:
-
-```elixir
-iex> defmodule Product do
-...>   defstruct [:name]
-...> end
-iex> %Product{}
-%Product{name: nil}
-```
-
-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:
-
-```elixir
-iex> defmodule User do
-...>   defstruct [:email, name: "John", age: 27]
-...> end
-iex> %User{}
-%User{age: 27, email: nil, name: "John"}
-```
-
-Doing it in reverse order will raise a syntax error:
-
-```elixir
-iex> defmodule User do
-...>   defstruct [name: "John", age: 27, :email]
-...> end
-** (SyntaxError) iex:107: unexpected expression after keyword list. Keyword lists must always come last in lists and maps.
-```
-
-You can also enforce that certain keys have to be specified when creating the struct via the `@enforce_keys` module attribute:
-
-```elixir
-iex> defmodule Car do
-...>   @enforce_keys [:make]
-...>   defstruct [:model, :make]
-...> end
-iex> %Car{}
-** (ArgumentError) the following keys must also be given when building struct Car: [:make]
-    expanding struct: Car.__struct__/1
-```
-
-Enforcing keys provides a simple compile-time guarantee to aid developers when building structs. It is not enforced on updates and it does not provide any sort of value-validation.
-
-## Accessing struct fields
+## Accessing and updating structs
 
-Structs support dot notation for accessing fields:
+Structs share the same syntax for accessing and updating fields as maps of fixed keys:
 
 ```elixir
 iex> john = %User{}
 %User{age: 27, name: "John"}
 iex> john.name
 "John"
-iex> john.age
-27
-```
-
-Unlike maps, structs do not support bracket notation access:
-
-```elixir
-iex> john[:name]
-** (UndefinedFunctionError) function User.fetch/2 is undefined (User does not implement the Access behaviour)
-             User.fetch(%User{age: 27, name: "John"}, :name)
-```
-
-## Updating fields
-
-When you need to update specific fields with known values, use the update syntax:
-
-```elixir
-iex> john = %User{name: "John", age: 27}
-%User{age: 27, name: "John"}
 iex> jane = %{john | name: "Jane"}
 %User{age: 27, name: "Jane"}
-iex> older_jane = %{jane | age: 30, name: "Jane Smith"}
-%User{age: 30, name: "Jane Smith"}
-```
-
-The update syntax ensures that only existing struct fields can be updated:
-
-```elixir
 iex> %{jane | oops: :field}
 ** (KeyError) key :oops not found in: %User{age: 27, name: "Jane"}
 ```
 
 When using the update syntax (`|`), Elixir 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.
 
-## Merging data
-
-When you have data in maps or keyword lists that you want to merge into a struct, use `Kernel.struct/2`. It accepts maps, keyword lists, or any enumerable that emits key-value pairs, and automatically discards keys that are not defined in the struct:
-
-```elixir
-iex> john = %User{name: "John", age: 27}
-%User{age: 27, name: "John"}
-iex> fields = [name: "Jane", age: 30]
-[name: "Jane", age: 30]
-iex> struct(john, fields)
-%User{age: 30, name: "Jane"}
-iex> struct(john, %{name: "Jane", invalid_key: "ignored"})
-%User{age: 27, name: "Jane"}
-iex> struct(john, [name: "Jane", another_invalid: "also ignored"])
-%User{age: 27, name: "Jane"}
-```
-
-## Pattern matching structs
-
-Pattern matching structs is one of the most powerful features in Elixir. You can match on struct types, extract specific fields, and ensure data integrity all in one expression:
+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.
 
 ```elixir
-iex> john = %User{name: "John", age: 27}
-%User{age: 27, name: "John"}
 iex> %User{name: name} = john
 %User{age: 27, name: "John"}
 iex> name
@@ -178,57 +74,35 @@ iex> %User{} = %{}
 ** (MatchError) no match of right hand side value: %{}
 ```
 
-Pattern matching structs is particularly useful in function heads to handle different data types:
+For more details on creating, updating, and pattern matching structs, see the documentation for `%/2`.
 
-```elixir
-defmodule Notification do
-  def send(%ChatMessage{user: user, text: text}) do
-    "#{user}: #{text}"
-  end
-
-  def send(%FriendRequest{sender: sender}) do
-    "#{sender} wants to be your friend"
-  end
-
-  def send(%GameInvite{sender: sender, game: game}) do
-    "#{sender} invited you to play #{game}"
-  end
-end
-```
-
-For more details on creating, updating, and pattern matching structs, see the documentation for [`Kernel.SpecialForms.%/2`](https://hexdocs.pm/elixir/Kernel.SpecialForms.html#%25/2).
+## Dynamic struct updates
 
-## Broken structs
-
-Since structs are maps underneath, it's possible to change them using `Map` functions. However, this can "break" the struct by adding fields that were not defined in `defstruct`, turning it into a plain map:
+When you need to update structs with data from variables or external sources, use `struct!/2`:
 
 ```elixir
 iex> john = %User{name: "John", age: 27}
 %User{age: 27, name: "John"}
-iex> broken = Map.put(john, :email, "[email protected]")
-%{__struct__: User, age: 27, email: "[email protected]", name: "John"}
-iex> is_map(broken)
-true
+iex> struct!(john, name: "Jane", age: 30)
+%User{age: 30, name: "Jane"}
 ```
 
-The result may look like a struct but it's actually a plain map with extra fields. This can lead to unexpected behavior when pattern matching or using protocols.
-
-To safely merge data into structs, always use `Kernel.struct/2` instead of `Map` functions:
+Unlike the update syntax, `struct!/2` accepts data from maps and keyword lists, and will raise an error if you try to set invalid fields:
 
 ```elixir
-iex> john = %User{name: "John", age: 27}
-%User{age: 27, name: "John"}
-iex> struct(john, %{name: "Jane", email: "ignored"})
-%User{age: 27, name: "Jane"}
+iex> fields = [name: "Jane", invalid: "field"]
+[name: "Jane", invalid: "field"]
+iex> struct!(john, fields)
+** (KeyError) key :invalid not found in: %User{age: 27, name: "John"}
 ```
 
-## Structs vs maps
+Always use `struct!/2` instead of `Map` functions when working with structs, as functions like `Map.put/3` and `Map.merge/2` can break struct integrity. See the [`Kernel.struct!/2`](https://hexdocs.pm/elixir/Kernel.html#struct!/2) documentation for more details.
+
+## Structs are bare maps underneath
 
 Structs are simply maps with a "special" field named `__struct__` that holds the name of the struct:
 
 ```elixir
-iex> john = %User{name: "John", age: 27}
-%User{age: 27, name: "John"}
 iex> is_map(john)
 true
 iex> john.__struct__
@@ -248,3 +122,48 @@ iex> Enum.each(john, fn {field, value} -> IO.puts(value) end)
 ```
 
 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:
+
+```elixir
+iex> defmodule Product do
+...>   defstruct [:name]
+...> end
+iex> %Product{}
+%Product{name: nil}
+```
+
+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`:
+
+```elixir
+iex> defmodule User do
+...>   defstruct [:email, name: "John", age: 27]
+...> end
+iex> %User{}
+%User{age: 27, email: nil, name: "John"}
+```
+
+Doing it in reverse order will raise a syntax error:
+
+```elixir
+iex> defmodule User do
+...>   defstruct [name: "John", age: 27, :email]
+...> end
+** (SyntaxError) iex:107: unexpected expression after keyword list. Keyword lists must always come last in lists and maps.
+```
+
+You can also enforce that certain keys have to be specified when creating the struct via the `@enforce_keys` module attribute:
+
+```elixir
+iex> defmodule Car do
+...>   @enforce_keys [:make]
+...>   defstruct [:model, :make]
+...> end
+iex> %Car{}
+** (ArgumentError) the following keys must also be given when building struct Car: [:make]
+    expanding struct: Car.__struct__/1
+```
+
+Enforcing keys provides a simple compile-time guarantee to aid developers when building structs. It is not enforced on updates and it does not provide any sort of value-validation.