Regex(Elixir v1.18.3)
View SourceProvides regular expressions for Elixir.
Regex is based on PCRE (Perl Compatible Regular Expressions) andbuilt on top of Erlang's:re module. More information can be foundin the:re module documentation.
Regular expressions in Elixir can be created using the sigils~r (seesigil_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/iuRegular expressions created via sigils are pre-compiled and storedin the.beam file. Note that this may be a problem if you are precompilingElixir, see the "Precompilation" section for more information.
A Regex is represented internally as theRegex 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 isalso not guarantee two regular expressions from the same source areequal, for example:
~r/(?<foo>.)(?<bar>.)/==~r/(?<foo>.)(?<bar>.)/may returntrue orfalse depending on your machine, endianness,available optimizations and others. You can, however, retrieve the sourceof a compiled regular expression by accessing thesource field, and thencompare those directly:
~r/(?<foo>.)(?<bar>.)/.source==~r/(?<foo>.)(?<bar>.)/.sourceEscapes
Escape sequences are split into two categories.
Non-printing characters
\a- Alarm, that is, the BEL character (hex 07)\e- Escape (hex 1B)\f- Form feed (hex 0C)\n- Line feed (hex 0A)\r- Carriage return (hex 0D)\t- Tab (hex 09)\xhh- Character with hex code hh\x{hhh..}- Character with hex code hhh..
\u and\U are not supported. Other escape sequences, such as\dddfor octals, are supported but discouraged.
Generic character types
\d- Any decimal digit\D- Any character that is not a decimal digit\h- Any horizontal whitespace character\H- Any character that is not a horizontal whitespace character\s- Any whitespace character\S- Any character that is not a whitespace character\v- Any vertical whitespace character\V- Any character that is not a vertical whitespace character\w- Any "word" character\W- Any "non-word" character
Modifiers
The modifiers available when creating a Regex are:
:unicode(u) - enables Unicode specific patterns like\pand causescharacter classes like\w,\W,\s, and the like to also match on Unicode(see examples below in "Character classes"). It expects valid Unicodestrings to be given on match:caseless(i) - adds case insensitivity:dotall(s) - causes dot to match newlines and also set newline toanycrlf; the new line setting can be overridden by setting(*CR)or(*LF)or(*CRLF)or(*ANY)according to:redocumentation:multiline(m) - causes^and$to mark the beginning and end ofeach line; use\Aand\zto match the end or beginning of the string:extended(x) - whitespace characters are ignored except when escapedor within[..], and allow#to delimit comments:firstline(f) - forces the unanchored pattern to match before or at thefirst newline, though the matched text may continue over the newline:ungreedy(U) - inverts the "greediness" of the regexp(the previousroption is deprecated in favor ofU)
The options not available are:
:anchored- not available, use^or\Ainstead:dollar_endonly- not available, use\zinstead: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:redocumentation
Captures
Many functions in this module handle what to capture in a regexmatch 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 thecomplete matching part of the string; all explicitly captured subpatternsare discarded:all_but_first- all but the first matching subpattern, i.e. allexplicitly captured subpatterns, but not the complete matching part ofthe string:none- does not return matching subpatterns at all:all_names- captures all named subpattern matches in the Regex as a listorderedalphabetically by the names of the subpatternslist(binary | atom)- a list of named captures to capture
Character classes
Regex supports several built in named character classes. These are used byenclosing the class name in[: :] inside a group. For example:
iex>String.match?("123",~r/^[[:alnum:]]+$/)trueiex>String.match?("123 456",~r/^[[:alnum:][:blank:]]+$/)trueThe 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 matchesLatin-1 characters instead of the 0-127 range specified by POSIX. Thiscannot be fixed without altering the behavior of other classes, so werecommend matching the range with[\\0-\x7f] instead.
Note the behavior of those classes may change according to the Unicodeand other modifiers:
iex>String.match?("josé",~r/^[[:lower:]]+$/)falseiex>String.match?("josé",~r/^[[:lower:]]+$/u)trueiex>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 slowerbetween operating systems and OTP releases. This is rarely a problem, as most Elixir codeshared during development is compiled on the target (such as dependencies,archives, and escripts) and, when running in production, the code must eitherbe compiled on the target (viamix compile or similar) or released on thehost (viamix releases or similar) with a matching OTP, operating systemand architecture as the target.
If you know you are running on a different system than the current one andyou are doing multiple matches with the regex, you can manually invokeRegex.recompile/1 orRegex.recompile!/1 to perform a runtime versioncheck and recompile the regex if necessary.
Summary
Functions
Compiles the regular expression.
Compiles the regular expression and raisesRegex.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 ornil if no captures are found.
Returns a list of names in the regex.
Returns the regex options.
Returns the underlyingre_pattern in the regular expression.
Recompiles the existing regular expression if necessary.
Recompiles the existing regular expression and raisesRegex.CompileError in case of errors.
Receives a regex, a binary and a replacement, returns a newbinary 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 ornil if no match occurred.
Same asrun/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 ofparts.
Returns the version of the underlying Regex engine.
Types
Functions
Compiles the regular expression.
The given options can either be a binary with the charactersrepresenting the same regex options given to the~r (seesigil_r/2) sigil, or a list of options, asexpected 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 raisesRegex.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")trueiex>Regex.match?(~r/foo/,"bar")falseElixir also provides text-based match operator=~/2 and functionString.match?/2 asan alternative to test strings against regular expressions andstrings.
Returns the given captures as a map ornil 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")nilReturns a list of names in the regex.
Examples
iex>Regex.names(~r/(?<foo>bar)/)["foo"]Returns the regex options.
See the documentation ofRegex.compile/2 for more information.
Examples
iex>Regex.opts(~r/foo/m)[:multiline]iex>Regex.opts(Regex.compile!("foo",[:caseless]))[:caseless]Returns the underlyingre_pattern in the regular expression.
Recompiles the existing regular expression if necessary.
This checks the version stored in the regular expressionand recompiles the regex in case of version mismatch.
Recompiles the existing regular expression and raisesRegex.CompileError in case of errors.
Receives a regex, a binary and a replacement, returns a newbinary 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 matchusing brackets at the regex expression and accessing them in the replacementvia\N or\g{N}, whereN is the number of the capture. In case\0 isused, the whole match is inserted. Note that in regexes the backslash needsto 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 morearguments 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/(\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 ornil 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" sectionto 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")niliex>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 asrun/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 amatch 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" sectionto 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"]]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 ofparts.
Options
:parts- when specified, splits the string into the given number ofparts. If not specified,:partsdefaults to:infinity, which willsplit the string into the maximum number of parts possible based on thegiven pattern.:trim- whentrue, removes empty strings ("") from the result.Defaults tofalse.:on- specifies which captures to split the string on, and in whatorder. Defaults to:firstwhich means captures inside the regex do notaffect the splitting process. See the"Captures" sectionto see the possible capture values.:include_captures- whentrue, includes in the result the matches ofthe regular expression. The matches are not counted towards the maximumnumber of parts if combined with the:partsoption. 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"]iex>Regex.split(~r/-/,"-a-b--c",trim:true)["a","b","c"]@spec version() ::term()
Returns the version of the underlying Regex engine.