@spec compile(binary(), binary() | [re_option()]) :: {: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, {~c"nothing to repeat", 0}}

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

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

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

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

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

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

@spec named_captures(t(), String.t(), [{:return, :binary | :index}]) :: 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

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

Returns a list of names in the regex.

Examples

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

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

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.

@spec replace(t(), String.t(), String.t() | (... -> String.t()), [
  {:global, boolean()}
]) :: 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"

@spec run(t(), binary(), [run_option()]) ::
  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. See the "Captures" section 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}]

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

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

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

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

• :return - when set to :index, returns byte index and match length. Defaults to :binary.
• :capture - what to capture in the result. See the "Captures" section 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/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"]]

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

Returns the regex source as a binary.

Examples

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

@spec split(t(), String.t(),
  parts: pos_integer() | :infinity,
  trim: boolean(),
  on: capture_option(),
  include_captures: boolean()
) :: [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. See the "Captures" section 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"]

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

@spec version() :: term()

Returns the version of the underlying Regex engine.