Compiles the regular expression.

The given options can either be a binary with the characters representing the same regex options given to the ~r 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}}

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

Returns the given captures as a map or nil if no captures are found. The option :return can be set to :index to get indexes back.

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

Returns the regex options as a string.

Examples

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

Returns the underlying re_pattern in the regular expression.

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.

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

Returns true if the given term is a regex. Otherwise returns false.

Examples

iex> Regex.regex?(~r/foo/)
true

iex> Regex.regex?(0)
false

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. The string is used as a replacement for every match and it allows specific captures to be accessed via \N or \g{N}, where N is 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, 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/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

• :return - sets to :index to return indexes. Defaults to :binary.
• :capture - what to capture in the result. Check the moduledoc for Regex to see the possible capture values.

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

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 - sets to :index to return indexes. Defaults to :binary.
• :capture - what to capture in the result. Check the moduledoc for Regex to see the possible capture values.

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 €")
[["$"], ["£"], ["€"]]

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

• :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.

• :include_captures - when true, includes in the result the matches of the regular expression. 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"]

Returns the version of the underlying Regex engine.