• Why it is this way
  • By default IEx will use the IO.Inspect protocol to pretty-print all results
    • If the list is a valid printable charlist, then IEx will print it as a charlist
• Official Elixir FAQ entry: https://github.com/elixir-lang/elixir/wiki/FAQ#4-why-is-my-list-of-integers-printed-as-a-string
• What to do

  • For the current IEx session, you can use IEx.configure/1 e.g. IEx.configure(inspect: [charlists: false]), or configure it globally with a .iex.exs file

    iex(1)> [7, 8, 9]
    '\a\b\t'
    iex(2)> IEx.configure(inspect: [charlists: false])
    :ok
    iex(3)> [7, 8, 9]
    [7, 8, 9]
    

  • Add a 0 to the end to ensure that all the code points are not printable:

    iex(1) [7, 8, 9, 0]
    [7, 8, 9, 0]
    

  • Understand that IEx is just pretty-printing your result - the values are exactly equivalent

  • Understand charlists vs strings

    • List.to_string/1 and String.to_charlist/1
• Examples
  • https://forum.elixirforum.net/t/how-to-use-a-list-with-non-negative-integers-without-making-it-a-charlist/26082
  • https://forum.elixirforum.net/t/7-8-9-in-iex-returns-a-b-t-why/29421
  • https://forum.elixirforum.net/t/unexpected-keyword-merge-behavior-elixir-1-9-4/27596
  • https://stackoverflow.com/questions/30037914/elixir-lists-interpreted-as-char-lists

• The behavior of Elixir here is different than Erlang to be more pragmatic and avoid requiring the programmer to have variables like a1, a2, a3 if they want to change the value of a binding
• Further reading:
  • https://medium.com/everydayhero-engineering/elixir-variable-rebinding-342c5d0fd961
  • blog.plataformatec.com.br/2016/01/comparing-elixir-and-erlang-variables/
• Related to trying to change the value of a binding in a loop, see next point
• Examples
  • Rebinding: https://forum.elixirforum.net/t/immutability-beginner-question/34655
  • https://forum.elixirforum.net/t/understand-immutability/36106

Under the hood, most implementations of lists boil down to a classic singly linked list. So, appending with mutable data would mean modifying the next-pointer of the previously last node to point at the new last node.

But with immutable data, you can’t do that! So you have to create a new node, pointing to the added node, and throw away the old one. Any existing references to this, must be updated… such as the next-pointer in that previously second-to-last node. However, the same condition applies, recursively, all the way back to the beginning of the list.

So, appending to a list with immutable data means you have to reconstruct the entire list every time. Since this must be done for every node you append, it takes the time to process the whole list from linear (proportional to the length) to quadratic (proportional to the square of the length).

By contrast, if you prepend a node, whether the data is mutable or not, you simply create it pointing to the old first node. Nothing more needs to be done. So, the time to process one node is constant, so the time to process the whole list is once again linear.

Here’s a more realistic example of this gotcha

vegetables = ["radish", "celery", "carrot"]

# We want this to become a list of vegetables starting with the letter "c"
c_vegetables = []

# We'll loop over `vegetables` 
# and try to concat each one that starts with "c" to the above list
Enum.each(vegetables, fn vegetable ->
  if String.starts_with?(vegetable, "c") do
    c_vegetables = Enum.concat(c_vegetables, [vegetable])

    # Inside this `if` block, `c_vegetables` will be rebound to one-item list
    # But it doesn't change the value of `c_vegetables` outside this block
    IO.inspect(c_vegetables) # Prints either `["celery"]` or `["carrot"]`
  end
end)

IO.inspect(c_vegetables) # This still has the value `[]`

Instead you should reassign the value of c_vegetables itself

vegetables = ["radish", "celery", "carrot"]

# Enum.filter docs: https://hexdocs.pm/elixir/Enum.html#filter/2
c_vegetables = Enum.filter(vegetables, fn vegetable ->
  String.starts_with?(vegetable, "c")
end)

IO.inspect(c_vegetables) # Prints out ["celery", "carrot"]

• To understand what is happening you should understand how scoping works in Elixir.
• This was actually allowed up to Elixir 1.6(?), and gave a warning up until Elixir 1.9(?)

Further reading:

• https://elixir-lang.org/getting-started/case-cond-and-if.html#if-and-unless
• https://elixir-lang.org/getting-started/try-catch-and-rescue.html#variables-scope
• https://elixir-lang.readthedocs.io/en/latest/technical/scoping.html

Examples:

• https://forum.elixirforum.net/t/tree-traversal-in-elixir-pre-order-in-order-post-order-what-am-i-doing-wrong/29568
• https://forum.elixirforum.net/t/keep-list-of-entries-during-enum-map/26004
• https://forum.elixirforum.net/t/using-if-else/36309
• https://forum.elixirforum.net/t/immutable-variable-isnt-immutable/38555

Further reading:

• https://stackoverflow.com/questions/41356447/whats-the-need-for-function-heads-in-multiple-clauses
• https://bordeltabernacle.netlify.app/elixir/notes-on-elixir-bodyless-functions/
• https://elixir-lang.org/getting-started/modules-and-functions.html#default-arguments

Examples:

• https://forum.elixirforum.net/t/def-without-do/12986

If Elixir/Erlang didn’t work this way then whenever you wanted to pattern match a map you would have to provide all of the keys, which would not be very ergonomic.

Instead in some cases you may want to use a guard instead:

def my_function(options) when options == %{} do
  # Handle case when no options are passed
end

• Examples
  • https://forum.elixirforum.net/t/pattern-match-on-empty-maps/33259
  • Example of using a guard: https://github.com/phoenixframework/phoenix/blob/e6d19272edfd980745d0a31a9217312580959eb9/lib/phoenix/controller.ex#L1504

The documentation for String.to_atom/1 states:

Warning: this function creates atoms dynamically and atoms are not garbage-collected. Therefore, string should not be an untrusted value, such as input received from a socket or during a web request. Consider using to_existing_atom/1 instead.

Examples:

• https://forum.elixirforum.net/t/key-not-found-map/4506
• https://forum.elixirforum.net/t/help-me-make-this-more-idiomatic/39633

Similarly you need to ensure that you don’t use :erlang.binary_to_term/2 on untrusted input as well:

https://blog.ispirata.com/how-to-destroy-your-application-using-erlang-binary-to-term-1-575ff7d05333

This is the same reason to generally avoid Jason.decode/2 with [keys: :atoms] and Poison.Parser.parse/2 with %{keys: :atoms!}

Instead you should use functions like Keyword.get/3 or Keyword.fetch!/2:

def my_function(opts) when is_list(opts) do
  name = Keyword.fetch!(opts, :name)
  age = Keyword.fetch!(opts, :age)
  # Or use `Keyword.get/3` if name or age are optional
end

Or pass options as a map:

def my_function(%{name: name, age: age}) do
  # do something with `name` and `age`
end

By pattern matching on a keyword list, you are stating that only a single ordering is allowed (i.e. that :name must be the very first element in the list in our example)

The primary target of this wiki post is to provide an easily digestible list of common gotchas or issues that beginners in Elixir often encounter. It is also a central place that people can link to an individual gotcha to help explain a specific issue in depth instead of having to type up a response in every chat thread or forum post.

Each gotcha should be commonly run into, so if it is something that does not come up often it’s best to not include it so that this wiki is easily understandable and not overwhelming to a beginner.

When editing, please try to avoid changing the titles of a gotcha because it will break any links that someone has made to the gotcha. And of course, all of the ElixirForum policies apply as well: https://forum.elixirforum.net/faq

a = %{val: 42}
a.val
# is the same as `a.val()`

a.foo

# is equivalent to

case a do
  %{foo: val} -> val
  mod -> mod.foo()
end

# Suppose that fetch_user/0 is a function that returns: 
#     {:ok, %{name: "john", age: 18}}
# But suppose the programmer is expecting simply %{name: "john", age: 18}
a = fetch_user()
a.age

** (ArgumentError) you attempted to apply :age on {:ok, %{age: 18}}. If you are using apply/3, make sure the module is an atom. If you are using the dot syntax, such as map.field or module.function(), make sure the left side of the dot is an atom or a map
    :erlang.apply({:ok, %{name: "john", age: 18}}, :age, [])

# On OTP 20 this was even more confusing because of tuple calls
iex(1)> a = {:ok, %{age: 20}}
{:ok, %{age: 20}}
iex(2)> a.age
** (UndefinedFunctionError) function :ok.age/1 is undefined (module :ok is not available)
    :ok.age({:ok, %{age: 20}})

iex(1)> myadd = fn num -> num + 1 end
#Function<44.79398840/1 in :erl_eval.expr/5>
iex(2)> myadd.(1)
2