Deprecate ismatch(r, s) in favor of contains(s, r)

Author: nalimilan

NEWS.md

@@ -901,6 +901,8 @@ Deprecated or removed
     `findlast`/`findprev` respectively, in combination with the new `equalto` and `occursin`
     predicates for some methods ([#24673]
 
+  * `ismatch(regex, str)` has been deprecated in favor of `contains(str, regex)` ([#24673]).
+
 Command-line option changes
 ---------------------------
 

base/deprecated.jl

@@ -3854,6 +3854,8 @@ end
 @deprecate rsearchindex(s::AbstractString, c::Char) first(findlast(equalto(c), s))
 @deprecate rsearchindex(s::AbstractString, c::Char, i::Integer) first(findprev(equalto(c), s, i))
 
+@deprecate ismatch(r::Regex, s::AbstractString) contains(s, r)
+
 # END 0.7 deprecations
 
 # BEGIN 1.0 deprecations

base/docs/utils.jl

@@ -359,7 +359,7 @@ const builtins = ["abstract type", "baremodule", "begin", "break",
 
 moduleusings(mod) = ccall(:jl_module_usings, Any, (Any,), mod)
 
-filtervalid(names) = filter(x->!ismatch(r"#", x), map(string, names))
+filtervalid(names) = filter(x->!contains(x, r"#"), map(string, names))
 
 accessible(mod::Module) =
     [filter!(s -> !Base.isdeprecated(mod, s), names(mod, true, true));

base/exports.jl

@@ -503,7 +503,6 @@ export
     findnext,
     findprev,
     findnz,
-    ismatch,
     occursin,
     match,
     matchall,

base/interactiveutil.jl

@@ -334,13 +334,13 @@ function versioninfo(io::IO=STDOUT; verbose::Bool=false, packages::Bool=false)
 
     println(io, "Environment:")
     for (k,v) in ENV
-        if ismatch(r"JULIA", String(k))
+        if contains(String(k), r"JULIA")
             println(io, "  $(k) = $(v)")
         end
     end
     if verbose
         for (k,v) in ENV
-            if ismatch(r"PATH|FLAG|^TERM$|HOME", String(k))
+            if contains(String(k), r"PATH|FLAG|^TERM$|HOME")
                 println(io, "  $(k) = $(v)")
             end
         end
@@ -737,7 +737,7 @@ function varinfo(m::Module=Main, pattern::Regex=r"")
                      (value ∈ (Base, Main, Core) ? "" : format_bytes(summarysize(value))),
                      summary(value)]
              end
-             for v in sort!(names(m)) if isdefined(m, v) && ismatch(pattern, string(v)) ]
+             for v in sort!(names(m)) if isdefined(m, v) && contains(string(v), pattern) ]
 
     pushfirst!(rows, Any["name", "size", "summary"])
 

base/libc.jl

@@ -204,7 +204,7 @@ function strptime(fmt::AbstractString, timestr::AbstractString)
     @static if Sys.isapple()
         # if we didn't explicitly parse the weekday or year day, use mktime
         # to fill them in automatically.
-        if !ismatch(r"([^%]|^)%(a|A|j|w|Ow)", fmt)
+        if !contains(fmt, r"([^%]|^)%(a|A|j|w|Ow)")
             ccall(:mktime, Int, (Ref{TmStruct},), tm)
         end
     end

base/linalg/blas.jl

@@ -122,7 +122,7 @@ function check()
     blas = vendor()
     if blas == :openblas || blas == :openblas64
         openblas_config = openblas_get_config()
-        openblas64 = ismatch(r".*USE64BITINT.*", openblas_config)
+        openblas64 = contains(openblas_config, r".*USE64BITINT.*")
         if Base.USE_BLAS64 != openblas64
             if !openblas64
                 @error """

base/linalg/uniformscaling.jl

@@ -55,7 +55,7 @@ getindex(J::UniformScaling, i::Integer,j::Integer) = ifelse(i==j,J.λ,zero(J.λ)
 
 function show(io::IO, J::UniformScaling)
     s = "$(J.λ)"
-    if ismatch(r"\w+\s*[\+\-]\s*\w+", s)
+    if contains(s, r"\w+\s*[\+\-]\s*\w+")
         s = "($s)"
     end
     print(io, "$(typeof(J))\n$s*I")

base/markdown/Common/block.jl

@@ -211,11 +211,11 @@ function admonition(stream::IO, block::MD)
             let untitled = r"^([a-z]+)$",          # !!! <CATEGORY_NAME>
                 titled   = r"^([a-z]+) \"(.*)\"$", # !!! <CATEGORY_NAME> "<TITLE>"
                 line     = strip(readline(stream))
-                if ismatch(untitled, line)
+                if contains(line, untitled)
                     m = match(untitled, line)
                     # When no title is provided we use CATEGORY_NAME, capitalising it.
                     m.captures[1], ucfirst(m.captures[1])
-                elseif ismatch(titled, line)
+                elseif contains(line, titled)
                     m = match(titled, line)
                     # To have a blank TITLE provide an explicit empty string as TITLE.
                     m.captures[1], m.captures[2]
@@ -270,10 +270,10 @@ function list(stream::IO, block::MD)
         indent = isempty(bullet) ? (return false) : length(bullet)
         # Calculate the starting number and regex to use for bullet matching.
         initial, regex =
-            if ismatch(BULLETS, bullet)
+            if contains(bullet, BULLETS)
                 # An unordered list. Use `-1` to flag the list as unordered.
                 -1, BULLETS
-            elseif ismatch(r"^ {0,3}\d+(\.|\))( |$)", bullet)
+            elseif contains(bullet, r"^ {0,3}\d+(\.|\))( |$)")
                 # An ordered list. Either with `1. ` or `1) ` style numbering.
                 r = contains(bullet, ".") ? r"^ {0,3}(\d+)\.( |$)" : r"^ {0,3}(\d+)\)( |$)"
                 Base.parse(Int, match(r, bullet).captures[1]), r

base/markdown/Common/inline.jl

@@ -140,7 +140,7 @@ function _is_mailto(s::AbstractString)
     length(s) < 6 && return false
     # slicing strings is a bit risky, but this equality check is safe
     lowercase(s[1:6]) == "mailto:" || return false
-    return ismatch(_email_regex, s[6:end])
+    return contains(s[6:end], _email_regex)
 end
 
 # –––––––––––

base/markdown/render/rst.jl

@@ -115,7 +115,7 @@ rstinline(io::IO, md::Vector) = !isempty(md) && rstinline(io, md...)
 # rstinline(io::IO, md::Image) = rstinline(io, ".. image:: ", md.url)
 
 function rstinline(io::IO, md::Link)
-    if ismatch(r":(func|obj|ref|exc|class|const|data):`\.*", md.url)
+    if contains(md.url, r":(func|obj|ref|exc|class|const|data):`\.*")
         rstinline(io, md.url)
     else
         rstinline(io, "`", md.text, " <", md.url, ">`_")

base/markdown/render/terminal/formatting.jl

@@ -59,7 +59,7 @@ lines(s) = split(s, "\n")
 
 # This could really be more efficient
 function wrapped_lines(io::IO, s::AbstractString; width = 80, i = 0)
-    if ismatch(r"\n", s)
+    if contains(s, r"\n")
         return vcat(map(s->wrapped_lines(io, s, width = width, i = i), split(s, "\n"))...)
     end
     ws = words(s)

base/methodshow.jl

@@ -202,7 +202,7 @@ function url(m::Method)
     (m.file == :null || m.file == :string) && return ""
     file = string(m.file)
     line = m.line
-    line <= 0 || ismatch(r"In\[[0-9]+\]", file) && return ""
+    line <= 0 || contains(file, r"In\[[0-9]+\]") && return ""
     Sys.iswindows() && (file = replace(file, '\\' => '/'))
     if inbase(M)
         if isempty(Base.GIT_VERSION_INFO.commit)

base/path.jl

@@ -78,7 +78,7 @@ end
 
 
 if Sys.iswindows()
-    isabspath(path::String) = ismatch(path_absolute_re, path)
+    isabspath(path::String) = contains(path, path_absolute_re)
 else
     isabspath(path::String) = startswith(path, '/')
 end
@@ -113,7 +113,7 @@ julia> isdirpath("/home/")
 true
 ```
 """
-isdirpath(path::String) = ismatch(path_directory_re, splitdrive(path)[2])
+isdirpath(path::String) = contains(splitdrive(path)[2], path_directory_re)
 
 """
     splitdir(path::AbstractString) -> (AbstractString, AbstractString)
@@ -218,9 +218,9 @@ function joinpath(a::String, b::String)
     B, b = splitdrive(b)
     !isempty(B) && A != B && return string(B,b)
     C = isempty(B) ? A : B
-    isempty(a)                             ? string(C,b) :
-    ismatch(path_separator_re, a[end:end]) ? string(C,a,b) :
-                                             string(C,a,pathsep(a,b),b)
+    isempty(a)                              ? string(C,b) :
+    contains(a[end:end], path_separator_re) ? string(C,a,b) :
+                                              string(C,a,pathsep(a,b),b)
 end
 joinpath(a::AbstractString, b::AbstractString) = joinpath(String(a), String(b))
 

base/pkg/read.jl

@@ -18,7 +18,7 @@ function available(names=readdir("METADATA"))
         versdir = joinpath("METADATA", pkg, "versions")
         isdir(versdir) || continue
         for ver in readdir(versdir)
-            ismatch(Base.VERSION_REGEX, ver) || continue
+            contains(ver, Base.VERSION_REGEX) || continue
             isfile(versdir, ver, "sha1") || continue
             haskey(pkgs,pkg) || (pkgs[pkg] = Dict{VersionNumber,Available}())
             pkgs[pkg][VersionNumber(ver)] = Available(
@@ -39,7 +39,7 @@ function latest(names=readdir("METADATA"))
         isdir(versdir) || continue
         pkgversions = VersionNumber[]
         for ver in readdir(versdir)
-            ismatch(Base.VERSION_REGEX, ver) || continue
+            contains(ver, Base.VERSION_REGEX) || continue
             isfile(versdir, ver, "sha1") || continue
             push!(pkgversions, VersionNumber(ver))
         end
@@ -114,7 +114,7 @@ function ispinned(prepo::LibGit2.GitRepo)
     LibGit2.isattached(prepo) || return false
     br = LibGit2.branch(prepo)
     # note: regex is based on the naming scheme used in Entry.pin()
-    return ismatch(r"^pinned\.[0-9a-f]{8}\.tmp$", br)
+    return contains(br, r"^pinned\.[0-9a-f]{8}\.tmp$")
 end
 
 function installed_version(pkg::AbstractString, prepo::LibGit2.GitRepo, avail::Dict=available(pkg))

base/pkg/reqs.jl

@@ -26,7 +26,7 @@ struct Requirement <: Line
         end
         isempty(fields) && throw(PkgError("invalid requires entry: $content"))
         package = popfirst!(fields)
-        all(field->ismatch(Base.VERSION_REGEX, field), fields) ||
+        all(field->contains(field, Base.VERSION_REGEX), fields) ||
             throw(PkgError("invalid requires entry for $package: $content"))
         versions = map(VersionNumber, fields)
         issorted(versions) || throw(PkgError("invalid requires entry for $package: $content"))
@@ -58,15 +58,15 @@ function read(readable::Vector{<:AbstractString})
     lines = Line[]
     for line in readable
         line = chomp(line)
-        push!(lines, ismatch(r"^\s*(?:#|$)", line) ? Comment(line) : Requirement(line))
+        push!(lines, contains(line, r"^\s*(?:#|$)") ? Comment(line) : Requirement(line))
     end
     return lines
 end
 
 function read(readable::Union{IO,Base.AbstractCmd})
     lines = Line[]
     for line in eachline(readable)
-        push!(lines, ismatch(r"^\s*(?:#|$)", line) ? Comment(line) : Requirement(line))
+        push!(lines, contains(line, r"^\s*(?:#|$)") ? Comment(line) : Requirement(line))
     end
     return lines
 end

base/random/misc.jl

@@ -432,7 +432,7 @@ let groupings = [1:8; 10:13; 15:18; 20:23; 25:36]
     function UUID(s::AbstractString)
         s = Base.Unicode.lowercase(s)
 
-        if !ismatch(r"^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$", s)
+        if !contains(s, r"^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$")
             throw(ArgumentError("Malformed UUID string"))
         end
 

base/regex.jl

@@ -141,39 +141,19 @@ function getindex(m::RegexMatch, name::Symbol)
 end
 getindex(m::RegexMatch, name::AbstractString) = m[Symbol(name)]
 
-"""
-    ismatch(r::Regex, s::AbstractString) -> Bool
-
-Test whether a string contains a match of the given regular expression.
-
-# Examples
-```jldoctest
-julia> rx = r"a.a"
-r"a.a"
-
-julia> ismatch(rx, "aba")
-true
-
-julia> ismatch(rx, "abba")
-false
-
-julia> rx("aba")
-true
-```
-"""
-function ismatch(r::Regex, s::AbstractString, offset::Integer=0)
+function contains(s::AbstractString, r::Regex, offset::Integer=0)
     compile(r)
     return PCRE.exec(r.regex, String(s), offset, r.match_options,
                      r.match_data)
 end
 
-function ismatch(r::Regex, s::SubString, offset::Integer=0)
+function contains(s::SubString, r::Regex, offset::Integer=0)
     compile(r)
     return PCRE.exec(r.regex, s, offset, r.match_options,
                      r.match_data)
 end
 
-(r::Regex)(s) = ismatch(r, s)
+(r::Regex)(s) = contains(s, r)
 
 """
     match(r::Regex, s::AbstractString[, idx::Integer[, addopts]])

base/repl/REPLCompletions.jl

@@ -116,7 +116,7 @@ function complete_keyword(s::Union{String,SubString{String}})
 end
 
 function complete_path(path::AbstractString, pos; use_envpath=false)
-    if Base.Sys.isunix() && ismatch(r"^~(?:/|$)", path)
+    if Base.Sys.isunix() && contains(path, r"^~(?:/|$)")
         # if the path is just "~", don't consider the expanded username as a prefix
         if path == "~"
             dir, prefix = homedir(), ""
@@ -409,7 +409,7 @@ function afterusing(string::String, startpos::Int)
     r = findfirst(r"\s(gnisu|tropmi)\b", rstr)
     isempty(r) && return false
     fr = reverseind(str, last(r))
-    return ismatch(r"^\b(using|import)\s*((\w+[.])*\w+\s*,\s*)*$", str[fr:end])
+    return contains(str[fr:end], r"^\b(using|import)\s*((\w+[.])*\w+\s*,\s*)*$")
 end
 
 function bslash_completions(string, pos)

base/repl/latex_symbols.jl

@@ -24,7 +24,7 @@ for c in child_nodes(root(xdoc))
             id = attribute(ce, "id")
             U = string(map(s -> Char(parse(Int, s, 16)),
                            split(id[2:end], "-"))...)
-            if ismatch(r"^\\[A-Za-z]+$",L) && !isa(U,String)
+            if contains(L, r"^\\[A-Za-z]+$") && !isa(U,String)
                 if L in Ls
                     println("# duplicated symbol $L ($id)")
                 else

base/strings/search.jl

@@ -448,16 +448,28 @@ julia> findprev("Julia", "JuliaLang", 6)
 findprev(t::AbstractString, s::AbstractString, i::Integer) = _rsearch(s, t, i)
 
 """
-    contains(haystack::AbstractString, needle::Union{AbstractString,Char})
+    contains(haystack::AbstractString, needle::Union{AbstractString,Regex,Char})
 
-Determine whether the second argument is a substring of the first.
+Determine whether the second argument is a substring of the first. If `needle`
+is a regular expression, checks whether `haystack` contains a match.
 
 # Examples
 ```jldoctest
 julia> contains("JuliaLang is pretty cool!", "Julia")
 true
+
+julia> contains("JuliaLang is pretty cool!", 'a')
+true
+
+julia> contains("aba", r"a.a")
+true
+
+julia> contains("abba", r"a.a")
+false
 ```
 """
+function contains end
+
 contains(haystack::AbstractString, needle::Union{AbstractString,Char}) =
     _searchindex(haystack, needle, start(haystack)) != 0
 

base/version.jl

@@ -21,7 +21,7 @@ struct VersionNumber
             if ident isa Integer
                 ident >= 0 || throw(ArgumentError("invalid negative pre-release identifier: $ident"))
             else
-                if !ismatch(r"^(?:|[0-9a-z-]*[a-z-][0-9a-z-]*)$"i, ident) ||
+                if !contains(ident, r"^(?:|[0-9a-z-]*[a-z-][0-9a-z-]*)$"i) ||
                     isempty(ident) && !(length(pre)==1 && isempty(bld))
                     throw(ArgumentError("invalid pre-release identifier: $(repr(ident))"))
                 end
@@ -31,7 +31,7 @@ struct VersionNumber
             if ident isa Integer
                 ident >= 0 || throw(ArgumentError("invalid negative build identifier: $ident"))
             else
-                if !ismatch(r"^(?:|[0-9a-z-]*[a-z-][0-9a-z-]*)$"i, ident) ||
+                if !contains(ident, r"^(?:|[0-9a-z-]*[a-z-][0-9a-z-]*)$"i) ||
                     isempty(ident) && length(bld)!=1
                     throw(ArgumentError("invalid build identifier: $(repr(ident))"))
                 end
@@ -83,7 +83,7 @@ function split_idents(s::AbstractString)
     idents = split(s, '.')
     ntuple(length(idents)) do i
         ident = idents[i]
-        ismatch(r"^\d+$", ident) ? parse(UInt64, ident) : String(ident)
+        contains(ident, r"^\d+$") ? parse(UInt64, ident) : String(ident)
     end
 end
 

doc/src/manual/strings.md

@@ -604,17 +604,17 @@ julia> typeof(ans)
 Regex
 ```
 
-To check if a regex matches a string, use [`ismatch`](@ref):
+To check if a regex matches a string, use [`contains`](@ref):
 
 ```jldoctest
-julia> ismatch(r"^\s*(?:#|$)", "not a comment")
+julia> contains("not a comment", r"^\s*(?:#|$)")
 false
 
-julia> ismatch(r"^\s*(?:#|$)", "# a comment")
+julia> contains("# a comment", r"^\s*(?:#|$)")
 true
 ```
 
-As one can see here, [`ismatch`](@ref) simply returns true or false, indicating whether the
+As one can see here, [`contains`](@ref) simply returns true or false, indicating whether the
 given regex matches the string or not. Commonly, however, one wants to know not just whether a
 string matched, but also *how* it matched. To capture this information about a match, use the
 [`match`](@ref) function instead: