Regex — Elixir v1.18.3 (original) (raw)

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

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

Generic character types

Modifiers

The modifiers available when creating a Regex are:

The options not available are:

Captures

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

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:

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 behavior of other classes, so we recommend matching the range with [\\0-\x7f] instead.

Note the behavior 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 .beamfiles. 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 invokeRegex.recompile/1 or Regex.recompile!/1 to perform a runtime version check and recompile the regex if necessary.

Summary

Functions

Compiles the regular expression.

Escapes a string to be literally matched in a regex.

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

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

Returns a list of names in the regex.

Returns the regex options.

Returns the underlying re_pattern in the regular expression.

Recompiles the existing regular expression if necessary.

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

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

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.

Same as run/3 but returns all non-overlapping matches of the regular expression.

Returns the regex source as a binary.

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

Returns the version of the underlying Regex engine.

Types

Functions

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

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

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

Regex.compile("*foo")
#=> {:error, {~c"nothing to repeat", 0}}

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

Escapes a string to be literally matched in a regex.

Examples

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

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

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.

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

Options

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

Returns a list of names in the regex.

Examples

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

@spec opts(t()) :: [term()]

Returns the regex options.

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

Examples

iex> Regex.opts(~r/foo/m)
[:multiline]

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

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

Returns the underlying re_pattern in the regular expression.

@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.

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

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

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

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"

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

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}]

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

iex> Regex.run(~r/c(?<foo>d)/, "abcd", capture: ["foo", "bar"])
["d", ""]

Same as run/3 but returns all non-overlapping 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

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/ab|bc|cd/, "abcd")
[["ab"], ["cd"]]

iex> Regex.scan(~r/ab|bc|cd/, "abbccd")
[["ab"], ["bc"], ["cd"]]

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

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

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

Returns the regex source as a binary.

Examples

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

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

Options

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"]

iex> Regex.split(~r/-/, "-a-b--c", trim: true)
["a", "b", "c"]

@spec version() :: term()

Returns the version of the underlying Regex engine.