Regex — Elixir v1.16.3

Search documentation of Elixir

# View Source Regex (Elixir v1.16.3)

Provides regular expressions for Elixir.

Regex is based on PCRE (Perl Compatible Regular Expressions) and built on top of Erlang's `:re` module. More information can be found in the `:re` module documentation.

Regular expressions in Elixir can be created using the sigils `~r` (see `sigil_r/2`):

    # A simple regular expression that matches foo anywhere in the string
    ~r/foo/

    # A regular expression with case insensitive and Unicode options
    ~r/foo/iu

Regular expressions created via sigils are pre-compiled and stored in the `.beam` file. Note that this may be a problem if you are precompiling Elixir, see the "Precompilation" section for more information.

A Regex is represented internally as the `Regex` struct. Therefore, `%Regex{}` can be used whenever there is a need to match on them. Keep in mind that all of the structs fields are private. There is also not guarantee two regular expressions from the same source are equal, for example:

    ~r/(?<foo>.)(?<bar>.)/ == ~r/(?<foo>.)(?<bar>.)/

may return `true` or `false` depending on your machine, endianness, available optimizations and others. You can, however, retrieve the source of a compiled regular expression by accessing the `source` field, and then compare those directly:

    ~r/(?<foo>.)(?<bar>.)/.source == ~r/(?<foo>.)(?<bar>.)/.source

## Escapes

Escape sequences are split into two categories.

### Non-printing characters

- `\a` - Alarm, that is, the BEL character (hex 07)
- `\e` - Escape (hex 1B)
- `\f` - Form feed (hex 0C)
- `\n` - Line feed (hex 0A)
- `\r` - Carriage return (hex 0D)
- `\t` - Tab (hex 09)
- `\xhh` - Character with hex code hh
- `\x{hhh..}` - Character with hex code hhh..

`\u` and `\U` are not supported. Other escape sequences, such as `\ddd` for octals, are supported but discouraged.

### Generic character types

- `\d` - Any decimal digit
- `\D` - Any character that is not a decimal digit
- `\h` - Any horizontal whitespace character
- `\H` - Any character that is not a horizontal whitespace character
- `\s` - Any whitespace character
- `\S` - Any character that is not a whitespace character
- `\v` - Any vertical whitespace character
- `\V` - Any character that is not a vertical whitespace character
- `\w` - Any "word" character
- `\W` - Any "non-word" character

## Modifiers

The modifiers available when creating a Regex are:

- `:unicode` (u) - enables Unicode specific patterns like `\p` and causes character classes like `\w`, `\W`, `\s`, and the like to also match on Unicode (see examples below in "Character classes"). It expects valid Unicode strings to be given on match

- `:caseless` (i) - adds case insensitivity

- `:dotall` (s) - causes dot to match newlines and also set newline to anycrlf; the new line setting can be overridden by setting `(*CR)` or `(*LF)` or `(*CRLF)` or `(*ANY)` according to `:re` documentation

- `:multiline` (m) - causes `^` and `$` to mark the beginning and end of each line; use `\A` and `\z` to match the end or beginning of the string

- `:extended` (x) - whitespace characters are ignored except when escaped and allow `#` to delimit comments

- `:firstline` (f) - forces the unanchored pattern to match before or at the first newline, though the matched text may continue over the newline

- `:ungreedy` (U) - inverts the "greediness" of the regexp (the previous `r` option is deprecated in favor of `U`)

The options not available are:

- `:anchored` - not available, use `^` or `\A` instead
- `:dollar_endonly` - not available, use `\z` instead
- `:no_auto_capture` - not available, use `?:` instead
- `:newline` - not available, use `(*CR)` or `(*LF)` or `(*CRLF)` or `(*ANYCRLF)` or `(*ANY)` at the beginning of the regexp according to the `:re` documentation

## Captures

Many functions in this module handle what to capture in a regex match via the `:capture` option. The supported values are:

- `:all` - all captured subpatterns including the complete matching string (this is the default)

- `:first` - only the first captured subpattern, which is always the complete matching part of the string; all explicitly captured subpatterns are discarded

- `:all_but_first` - all but the first matching subpattern, i.e. all explicitly captured subpatterns, but not the complete matching part of the string

- `:none` - does not return matching subpatterns at all

- `:all_names` - captures all named subpattern matches in the Regex as a list ordered alphabetically by the names of the subpatterns

- `list(binary)` - a list of named captures to capture

## Character classes

Regex supports several built in named character classes. These are used by enclosing the class name in `[: :]` inside a group. For example:

    iex> String.match?("123", ~r/^[[:alnum:]]+$/)
    true
    iex> String.match?("123 456", ~r/^[[:alnum:][:blank:]]+$/)
    true

The supported class names are:

- alnum - Letters and digits
- alpha - Letters
- blank - Space or tab only
- cntrl - Control characters
- digit - Decimal digits (same as \d)
- graph - Printing characters, excluding space
- lower - Lowercase letters
- print - Printing characters, including space
- punct - Printing characters, excluding letters, digits, and space
- space - Whitespace (the same as \s from PCRE 8.34)
- upper - Uppercase letters
- word - "Word" characters (same as \w)
- xdigit - Hexadecimal digits

There is another character class, `ascii`, that erroneously matches Latin-1 characters instead of the 0-127 range specified by POSIX. This cannot be fixed without altering the behaviour of other classes, so we recommend matching the range with `[\\0-\x7f]` instead.

Note the behaviour of those classes may change according to the Unicode and other modifiers:

    iex> String.match?("josé", ~r/^[[:lower:]]+$/)
    false
    iex> String.match?("josé", ~r/^[[:lower:]]+$/u)
    true
    iex> Regex.replace(~r/\s/, "Unicode\u00A0spaces", "-")
    "Unicode spaces"
    iex> Regex.replace(~r/\s/u, "Unicode\u00A0spaces", "-")
    "Unicode-spaces"

## Precompilation

Regular expressions built with sigil are precompiled and stored in `.beam` files. Precompiled regexes will be checked in runtime and may work slower between operating systems and OTP releases. This is rarely a problem, as most Elixir code shared during development is compiled on the target (such as dependencies, archives, and escripts) and, when running in production, the code must either be compiled on the target (via `mix compile` or similar) or released on the host (via `mix releases` or similar) with a matching OTP, operating system and architecture as the target.

If you know you are running on a different system than the current one and you are doing multiple matches with the regex, you can manually invoke `Regex.recompile/1` or `Regex.recompile!/1` to perform a runtime version check and recompile the regex if necessary.

# Summary

## Types

t()

## Functions

compile(source, options \\ "")

Compiles the regular expression.

compile!(source, options \\ "")

Compiles the regular expression and raises `Regex.CompileError` in case of errors.

escape(string)

Escapes a string to be literally matched in a regex.

match?(regex, string)

Returns a boolean indicating whether there was a match or not.

named_captures(regex, string, options \\ [])

Returns the given captures as a map or `nil` if no captures are found.

names(regex)

Returns a list of names in the regex.

opts(regex)

Returns the regex options, as a string or list depending on how it was compiled.

re_pattern(regex)

Returns the underlying `re_pattern` in the regular expression.

recompile(regex)

Recompiles the existing regular expression if necessary.

recompile!(regex)

Recompiles the existing regular expression and raises `Regex.CompileError` in case of errors.

replace(regex, string, replacement, options \\ [])

Receives a regex, a binary and a replacement, returns a new binary where all matches are replaced by the replacement.

run(regex, string, options \\ [])

Runs the regular expression against the given string until the first match. It returns a list with all captures or `nil` if no match occurred.

scan(regex, string, options \\ [])

Same as `run/3`, but scans the target several times collecting all matches of the regular expression.

source(regex)

Returns the regex source as a binary.

split(regex, string, options \\ [])

Splits the given target based on the given pattern and in the given number of parts.

version()

Returns the version of the underlying Regex engine.

# Types

Link to this type

# t()

View Source

    @type t() :: %Regex{
      opts: binary() | [term()],
      re_pattern: term(),
      re_version: term(),
      source: binary()
    }

# Functions

Link to this function

# compile(source, options \\ "")

View Source

    @spec compile(binary(), binary() | [term()]) :: {:ok, t()} | {:error, any()}

Compiles the regular expression.

The given options can either be a binary with the characters representing the same regex options given to the `~r` (see `sigil_r/2`) sigil, or a list of options, as expected by the Erlang's `:re` module.

It returns `{:ok, regex}` in case of success, `{:error, reason}` otherwise.

## Examples

    iex> Regex.compile("foo")
    {:ok, ~r/foo/}

    iex> Regex.compile("*foo")
    {:error, {'nothing to repeat', 0}}

    iex> Regex.compile("foo", "i")
    {:ok, ~r/foo/i}

    iex> Regex.compile("foo", [:caseless])
    {:ok, Regex.compile!("foo", [:caseless])}

Link to this function

# compile!(source, options \\ "")

View Source

    @spec compile!(binary(), binary() | [term()]) :: t()

Compiles the regular expression and raises `Regex.CompileError` in case of errors.

Link to this function

# escape(string)

View Source

    @spec escape(String.t()) :: String.t()

Escapes a string to be literally matched in a regex.

## Examples

    iex> Regex.escape(".")
    "\\."

    iex> Regex.escape("\\what if")
    "\\\\what\\ if"

Link to this function

# match?(regex, string)

View Source

    @spec match?(t(), String.t()) :: boolean()

Returns a boolean indicating whether there was a match or not.

## Examples

    iex> Regex.match?(~r/foo/, "foo")
    true

    iex> Regex.match?(~r/foo/, "bar")
    false

Elixir also provides text-based match operator `=~/2` and function `String.match?/2` as an alternative to test strings against regular expressions and strings.

Link to this function

# named_captures(regex, string, options \\ [])

View Source

    @spec named_captures(t(), String.t(), [term()]) :: map() | nil

Returns the given captures as a map or `nil` if no captures are found.

## Options

- `:return` - when set to `:index`, returns byte index and match length. Defaults to `:binary`.

## Examples

    iex> Regex.named_captures(~r/c(?<foo>d)/, "abcd")
    %{"foo" => "d"}

    iex> Regex.named_captures(~r/a(?<foo>b)c(?<bar>d)/, "abcd")
    %{"bar" => "d", "foo" => "b"}

    iex> Regex.named_captures(~r/a(?<foo>b)c(?<bar>d)/, "efgh")
    nil

Link to this function

# names(regex)

View Source

    @spec names(t()) :: [String.t()]

Returns a list of names in the regex.

## Examples

    iex> Regex.names(~r/(?<foo>bar)/)
    ["foo"]

Link to this function

# opts(regex)

View Source

    @spec opts(t()) :: String.t() | [term()]

Returns the regex options, as a string or list depending on how it was compiled.

See the documentation of `Regex.compile/2` for more information.

## Examples

    iex> Regex.opts(~r/foo/m)
    "m"

    iex> Regex.opts(Regex.compile!("foo", [:caseless]))
    [:caseless]

Link to this function

# re_pattern(regex)

View Source

    @spec re_pattern(t()) :: term()

Returns the underlying `re_pattern` in the regular expression.

Link to this function

# recompile(regex)

View Source (since 1.4.0)

    @spec recompile(t()) :: {:ok, t()} | {:error, any()}

Recompiles the existing regular expression if necessary.

This checks the version stored in the regular expression and recompiles the regex in case of version mismatch.

Link to this function

# recompile!(regex)

View Source (since 1.4.0)

    @spec recompile!(t()) :: t()

Recompiles the existing regular expression and raises `Regex.CompileError` in case of errors.

Link to this function

# replace(regex, string, replacement, options \\ [])

View Source

    @spec replace(t(), String.t(), String.t() | (... -> String.t()), [term()]) ::
      String.t()

Receives a regex, a binary and a replacement, returns a new binary where all matches are replaced by the replacement.

The replacement can be either a string or a function that returns a string. The resulting string is used as a replacement for every match.

When the replacement is a string, it allows specific captures of the match using brackets at the regex expression and accessing them in the replacement via `\N` or `\g{N}`, where `N` is the number of the capture. In case `\0` is used, the whole match is inserted. Note that in regexes the backslash needs to be escaped, hence in practice you'll need to use `\\N` and `\\g{N}`.

When the replacement is a function, it allows specific captures too. The function may have arity N where each argument maps to a capture, with the first argument being the whole match. If the function expects more arguments than captures found, the remaining arguments will receive `""`.

## Options

- `:global` - when `false`, replaces only the first occurrence (defaults to `true`)

## Examples

    iex> Regex.replace(~r/d/, "abc", "d")
    "abc"

    iex> Regex.replace(~r/b/, "abc", "d")
    "adc"

    iex> Regex.replace(~r/b/, "abc", "[\\0]")
    "a[b]c"

    iex> Regex.replace(~r/a(b|d)c/, "abcadc", "[\\1]")
    "[b][d]"

    iex> Regex.replace(~r/\.(\d)$/, "500.5", ".\\g{1}0")
    "500.50"

    iex> Regex.replace(~r/a(b|d)c/, "abcadc", fn _, x -> "[#{x}]" end)
    "[b][d]"

    iex> Regex.replace(~r/(\w+)@(\w+).(\w+)/, "abc@def.com", fn _full, _c1, _c2, c3 -> "TLD: #{c3}" end)
    "TLD: com"

    iex> Regex.replace(~r/a/, "abcadc", "A", global: false)
    "Abcadc"

Link to this function

# run(regex, string, options \\ [])

View Source

    @spec run(t(), binary(), [term()]) :: nil | [binary()] | [{integer(), integer()}]

Runs the regular expression against the given string until the first match. It returns a list with all captures or `nil` if no match occurred.

## Options

- `:return` - when set to `:index`, returns byte index and match length. Defaults to `:binary`.
- `:capture` - what to capture in the result. Check the moduledoc for `Regex` to see the possible capture values.
- `:offset` - (since v1.12.0) specifies the starting offset to match in the given string. Defaults to zero.

## Examples

    iex> Regex.run(~r/c(d)/, "abcd")
    ["cd", "d"]

    iex> Regex.run(~r/e/, "abcd")
    nil

    iex> Regex.run(~r/c(d)/, "abcd", return: :index)
    [{2, 2}, {3, 1}]

Link to this function

# scan(regex, string, options \\ [])

View Source

    @spec scan(t(), String.t(), [term()]) :: [[String.t()]] | [[{integer(), integer()}]]

Same as `run/3`, but scans the target several times collecting all matches of the regular expression.

A list of lists is returned, where each entry in the primary list represents a match and each entry in the secondary list represents the captured contents.

## Options

- `:return` - when set to `:index`, returns byte index and match length. Defaults to `:binary`.
- `:capture` - what to capture in the result. Check the moduledoc for `Regex` to see the possible capture values.
- `:offset` - (since v1.12.0) specifies the starting offset to match in the given string. Defaults to zero.

## Examples

    iex> Regex.scan(~r/c(d|e)/, "abcd abce")
    [["cd", "d"], ["ce", "e"]]

    iex> Regex.scan(~r/c(?:d|e)/, "abcd abce")
    [["cd"], ["ce"]]

    iex> Regex.scan(~r/e/, "abcd")
    []

    iex> Regex.scan(~r/\p{Sc}/u, "$, £, and €")
    [["$"], ["£"], ["€"]]

    iex> Regex.scan(~r/=+/, "=ü†ƒ8===", return: :index)
    [[{0, 1}], [{9, 3}]]

Link to this function

# source(regex)

View Source

    @spec source(t()) :: String.t()

Returns the regex source as a binary.

## Examples

    iex> Regex.source(~r/foo/)
    "foo"

Link to this function

# split(regex, string, options \\ [])

View Source

    @spec split(t(), String.t(), [term()]) :: [String.t()]

Splits the given target based on the given pattern and in the given number of parts.

## Options

- `:parts` - when specified, splits the string into the given number of parts. If not specified, `:parts` defaults to `:infinity`, which will split the string into the maximum number of parts possible based on the given pattern.

- `:trim` - when `true`, removes empty strings (`""`) from the result. Defaults to `false`.

- `:on` - specifies which captures to split the string on, and in what order. Defaults to `:first` which means captures inside the regex do not affect the splitting process. Check the moduledoc for `Regex` to see the possible capture values.

- `:include_captures` - when `true`, includes in the result the matches of the regular expression. The matches are not counted towards the maximum number of parts if combined with the `:parts` option. Defaults to `false`.

## Examples

    iex> Regex.split(~r{-}, "a-b-c")
    ["a", "b", "c"]

    iex> Regex.split(~r{-}, "a-b-c", parts: 2)
    ["a", "b-c"]

    iex> Regex.split(~r{-}, "abc")
    ["abc"]

    iex> Regex.split(~r{}, "abc")
    ["", "a", "b", "c", ""]

    iex> Regex.split(~r{a(?<second>b)c}, "abc")
    ["", ""]

    iex> Regex.split(~r{a(?<second>b)c}, "abc", on: [:second])
    ["a", "c"]

    iex> Regex.split(~r{(x)}, "Elixir", include_captures: true)
    ["Eli", "x", "ir"]

    iex> Regex.split(~r{a(?<second>b)c}, "abc", on: [:second], include_captures: true)
    ["a", "b", "c"]

Link to this function

# version()

View Source (since 1.4.0)

    @spec version() :: term()

Returns the version of the underlying Regex engine.