Elixir v1.9.2 Regex View Source
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. Notice 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 it is not guaranteed 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 change modifiers like\w
,\W
,\s
and friends to also match on Unicode. It expects valid Unicode strings to be given on matchcaseless
(i) - adds case insensitivitydotall
(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
documentationmultiline
(m) - causes^
and$
to mark the beginning and end of each line; use\A
and\z
to match the end or beginning of the stringextended
(x) - whitespace characters are ignored except when escaped and allow#
to delimit commentsfirstline
(f) - forces the unanchored pattern to match before or at the first newline, though the matched text may continue over the newlineungreedy
(U) - inverts the "greediness" of the regexp (the previousr
option is deprecated in favor ofU
)
The options not available are:
anchored
- not available, use^
or\A
insteaddollar_endonly
- not available, use\z
insteadno_auto_capture
- not available, use?:
insteadnewline
- 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 names in the Regexlist(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
- ascii - Character codes 0-127
- 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
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
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, OS and architecture
as as the target.
If you know you are running on a different system that 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.
Link to this section Summary
Functions
Compiles the regular expression.
Compiles the regular expression and raises Regex.CompileError
in case of errors.
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 as a string.
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.
Returns true
if the given term
is a regex.
Otherwise returns false
.
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 scans the target several times collecting all
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.
Link to this section Types
Specs
Link to this section Functions
Specs
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}}
Specs
Compiles the regular expression and raises Regex.CompileError
in case of errors.
Specs
Escapes a string to be literally matched in a regex.
Examples
iex> Regex.escape(".")
"\\."
iex> Regex.escape("\\what if")
"\\\\what\\ if"
Specs
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
Specs
Returns the given captures as a map or nil
if no captures are found.
Options
:return
- set to:index
to return 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
Specs
Returns a list of names in the regex.
Examples
iex> Regex.names(~r/(?<foo>bar)/)
["foo"]
Specs
Returns the regex options as a string.
Examples
iex> Regex.opts(~r(foo)m)
"m"
Specs
Returns the underlying re_pattern
in the regular expression.
Specs
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.
Specs
Recompiles the existing regular expression and raises Regex.CompileError
in case of errors.
Specs
Returns true
if the given term
is a regex.
Otherwise returns false
.
Examples
iex> Regex.regex?(~r/foo/)
true
iex> Regex.regex?(0)
false
Specs
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
- whenfalse
, replaces only the first occurrence (defaults totrue
)
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"
Specs
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
- set to:index
to return byte index and match length. Defaults to:binary
.:capture
- what to capture in the result. Check the moduledoc forRegex
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}]
Specs
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
- set to:index
to return byte index and match length. Defaults to:binary
.:capture
- what to capture in the result. Check the moduledoc forRegex
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 €")
[["$"], ["£"], ["€"]]
iex> Regex.scan(~r/=+/, "=ü†ƒ8===", return: :index)
[[{0, 1}], [{9, 3}]]
Specs
Returns the regex source as a binary.
Examples
iex> Regex.source(~r(foo))
"foo"
Specs
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
- whentrue
, removes empty strings (""
) from the result. Defaults tofalse
.: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
- whentrue
, includes in the result the matches of the regular expression. Defaults tofalse
.
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"]
Specs
version() :: term()
Returns the version of the underlying Regex engine.