Struct vs. @type t

Questions / Help
,
1

I’m pretty new to Elixir. One thing I don’t think I understand is the typespecs, specifically when they deal with structs. A common pattern I’ve seen is that the struct definition is frequently accompanied by a @type t definition, something like this:

defmodule MyStruct do
  
  defstruct x: "",
            y: false,
            z: 0
            
  @type t :: %__MODULE__{
               x: String.t(),
               y: boolean,
               z: integer
             }
end

A struct is defined AND a @type t. If I want to use this struct in function @spec, I have seen both the struct or this type t referenced, e.g.

@spec my_func(%MyStruct{}) :: any

or

@spec my_func(MyStruct.t()) :: any

apply to a function, e.g.

def my_func(%MyStruct{} = input) do
    # something...
end

So my questions are:

  1. Is the @type t special? Or is that just a convention?
  2. Is there any difference between using %MyStruct{} or MyStruct.t() in function specs?
  3. Is there any case where you would use one and not the other?
  4. Is the @type t more “specific” because it can declare the types of various keys in the struct? (Whereas the struct itself only defines the names of the keys, not their data types)

Thanks for any clarifications. I’m sure I missed something in my studies thus far.

6 Likes
2

To answer your question, t() is not special, it is just convention.
One thing to remember is that a struct is just a fancy map.

You can create a type with a map that specifies keys and their types just the same:

  @type special_map :: %{some_key: String.t()}
2 Likes
3

Convention.

Yes. If you will use just %MyStruct{} then the types specified in t() will not be used. So:

@type t :: %MyStruct{a: integer()}

@spec pass(%MyStruct{}) :: term()
def pass(t), do: t

@spec fail(t()) :: term()
def fail(t), do: t

s = %MyStruct{a: "bar"}

pass(s)
fail(s) # this will cause Dialyzer error

If there is defined t() then you should always use that.

Yes, as shown above.

16 Likes
4

Thanks! That makes sense.

5

Another issue worth mentioning is that using %MyModule{} in typespec will create a compile-time dependency, so every time MyModule is changed, the modules that use %MyModule{} in typespecs will need to be recompiled.

4 Likes