Regex

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

Kernel.sigil_r/2 ) or ~R (see Kernel.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

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 , etc. 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.

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.

regex?(term) deprecated
Returns true if the given term is a regex. Otherwise returns false .

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

t()

@type t() :: %Regex{

opts: binary(),
re_pattern: term(),
re_version: term(),
source: binary()
}

Functions

compile(source, options \\ "")

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

compile!(source, options \\ "")

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

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

errors.

escape(string)

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

match?(regex, string)

@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

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

@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

names(regex)

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

Returns a list of names in the regex.

Examples

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

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

Returns the regex options as a string.

Examples

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

re_pattern(regex)

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

Returns the underlying re_pattern in the regular expression.

recompile(regex) (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.

recompile!(regex) (since 1.4.0)

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

Recompiles the existing regular expression and raises Regex.CompileError

in case of errors.

regex?(term)
This function is deprecated. Use Kernel.is_struct/2 or pattern match on
%Regex{} instead.

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

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

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

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

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

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

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

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

source(regex)

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

Returns the regex source as a binary.

Examples

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

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

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

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

version() (since 1.4.0)

@spec version() :: term()

Returns the version of the underlying Regex engine.

Built using ExDoc (v0.29.4) for the Elixir programming language