Operators reference — Elixir v1.16.3

Search documentation of Elixir

# View Source Operators reference

This document is a complete reference of operators in Elixir, how they are parsed, how they can be defined, and how they can be overridden.

## Operator precedence and associativity

The following is a list of all operators that Elixir is capable of parsing, ordered from higher to lower precedence, alongside their associativity:

Operator | Associativity
--- | ---
`@` | Unary
`.` | Left
`+` `-` `!` `^` `not` | Unary
`**` | Left
`*` `/` | Left
`+` `-` | Left
`++` `--` `+++` `---` `..` `<>` | Right
`in` `not in` | Left
`|>` `<<<` `>>>` `<<~` `~>>` `<~` `~>` `<~>` | Left
`<` `>` `<=` `>=` | Left
`==` `!=` `=~` `===` `!==` | Left
`&&` `&&&` `and` | Left
`||` `|||` `or` | Left
`=` | Right
`&` | Unary
`=>` (valid only inside `%{}`) | Right
`|` | Right
`::` | Right
`when` | Right
`<-` `\\` | Left

## General operators

Elixir provides the following built-in operators:

- `+` and `-` - unary positive/negative
- `+`, `-`, `*`, and `/` - basic arithmetic operations
- `++` and `--` - list concatenation and subtraction
- `and` and `&&` - strict and relaxed boolean "and"
- `or` and `||` - strict and relaxed boolean "or"
- `not` and `!` - strict and relaxed boolean "not"
- `in` and `not in` - membership
- `@` - module attribute
- `..`, `..`, and `..//` - range creation
- `<>` - binary concatenation
- `|>` - pipeline
- `=~` - text-based match

Many of those can be used in guards; consult the list of allowed guard functions and operators.

Additionally, there are a few other operators that Elixir parses but doesn't actually use. See Custom and overridden operators below for a list and for guidelines about their use.

Some other operators are special forms and cannot be overridden:

- `^` - pin operator
- `.` - dot operator
- `=` - match operator
- `&` - capture operator
- `::` - type operator

Finally, these operators appear in the precedence table above but are only meaningful within certain constructs:

- `=>` - see `%{}`
- `when` - see Guards
- `<-` - see `for` and `with`
- `\\` - see Default arguments

## Comparison operators

Elixir provides the following built-in comparison operators (all of which can be used in guards):

- `==` - equal to
- `===` - strictly equal to
- `!=` - not equal to
- `!==` - strictly not equal to
- `<` - less-than
- `>` - greater-than
- `<=` - less-than or equal to
- `>=` - greater-than or equal to

The only difference between `==` and `===` is that `===` is strict when it comes to comparing integers and floats:

    iex> 1 == 1.0
    true
    iex> 1 === 1.0
    false

`!=` and `!==` act as the negation of `==` and `===`, respectively.

## Custom and overridden operators

### Defining custom operators

Elixir is capable of parsing a predefined set of operators. It's not possible to define new operators (as supported by some languages). However, not all operators that Elixir can parse are used by Elixir: for example, `+` and `||` are used by Elixir for addition and boolean or, but `<~>` is not used (but valid).

To define an operator, you can use the usual `def*` constructs (`def`, `defp`, `defmacro`, and so on) but with a syntax similar to how the operator is used:

    defmodule MyOperators do
      # We define ~> to return the maximum of the given two numbers,
      # and <~ to return the minimum.

      def a ~> b, do: max(a, b)
      def a <~ b, do: min(a, b)
    end

To use the newly defined operators, you have to import the module that defines them:

    iex> import MyOperators
    iex> 1 ~> 2
    2
    iex> 1 <~ 2
    1

The following is a table of all the operators that Elixir is capable of parsing, but that are not used by default:

- `|||`
- `&&&`
- `<<<`
- `>>>`
- `<<~`
- `~>>`
- `<~`
- `~>`
- `<~>`
- `+++`
- `---`

The following operators are used by the `Bitwise` module when imported: `&&&`, `<<<`, `>>>`, and `|||`. See the documentation for `Bitwise` for more information.

Note that the Elixir community generally discourages custom operators. They can be hard to read and even more to understand, as they don't have a descriptive name like functions do. That said, some specific cases or custom domain specific languages (DSLs) may justify these practices.

It is also possible to replace predefined operators, such as `+`, but doing so is extremely discouraged.

← Previous Page Naming conventions
Next Page → Patterns and guards