Deprecate contains to a more general isfound function

While `contains` was generally limited to strings and regular
expressions (after the move from `ismatch` to `contains`), `isfound`
works more generally, as its fallback method is defined in terms of
`findfirst`.

DISTRIBUTING.md

@@ -364,7 +364,7 @@ for result in eachrow(results)
     b = result[:backport]
     if (isna(a) && !isna(b)) || (isna(b) && !isna(a))
         color = :yellow
-    elseif a != b && contains(b, "pass")
+    elseif a != b && isfound("pass", b)
         color = :green
     elseif a != b
         color = :red

NEWS.md

@@ -1067,6 +1067,8 @@ Deprecated or removed
   * The `remove_destination` keyword argument to `cp`, `mv`, and the unexported `cptree`
     has been renamed to `force` ([#25979]).
 
+  * `contains` has been deprecated in favor of a more general `isfound` function ([#26283]).
+
   * The methods of `range` based on positional arguments have been deprecated in favor of
     keyword arguments ([#25896]).
 

base/array.jl

@@ -1684,6 +1684,28 @@ end
 findfirst(testf::Function, A::Union{AbstractArray, AbstractString}) =
     findnext(testf, A, first(keys(A)))
 
+"""
+    isfound(needle, haystack)
+
+Determine whether `needle` is found within `haystack`. This function is effectively
+equivalent to `findfirst(needle, haystack) !== nothing`.
+
+See also [`findfirst`](@ref) and [`any`](@ref).
+
+# Examples
+```jldoctest
+julia> isfound('x', "hexonxonx")
+true
+
+julia> isfound("hi", "hi mom")
+true
+
+julia> isfound(equalto(3), 5:10)
+false
+```
+"""
+isfound(needle, haystack) = findfirst(needle, haystack) !== nothing
+
 """
     findprev(A, i)
 

base/client.jl

@@ -244,11 +244,11 @@ incomplete_tag(ex) = :none
 function incomplete_tag(ex::Expr)
     Meta.isexpr(ex, :incomplete) || return :none
     msg = ex.args[1]
-    contains(msg, "string") && return :string
-    contains(msg, "comment") && return :comment
-    contains(msg, "requires end") && return :block
-    contains(msg, "\"`\"") && return :cmd
-    contains(msg, "character") && return :char
+    isfound("string", msg) && return :string
+    isfound("comment", msg) && return :comment
+    isfound("requires end", msg) && return :block
+    isfound("\"`\"", msg) && return :cmd
+    isfound("character", msg) && return :char
     return :other
 end
 

base/deprecated.jl

@@ -1229,7 +1229,7 @@ end
 @deprecate rsearchindex(s::AbstractString, c::Char) findlast(equalto(c), s)
 @deprecate rsearchindex(s::AbstractString, c::Char, i::Integer) findprev(equalto(c), s, i)
 
-@deprecate ismatch(r::Regex, s::AbstractString) contains(s, r)
+@deprecate ismatch(r::Regex, s::AbstractString) isfound(r, s)
 
 @deprecate findin(a, b) findall(occursin(b), a)
 
@@ -1454,6 +1454,10 @@ function slicedim(A::AbstractVector, d::Integer, i::Number)
     end
 end
 
+# PR #26283
+@deprecate contains(haystack, needle) isfound(needle, haystack)
+@deprecate contains(s::AbstractString, r::Regex, offset::Integer) isfound(r, s, offset=offset)
+
 # Issue #25786
 @deprecate_binding DevNull devnull
 # TODO: When these are removed, also remove the uppercase variants in libuv.jl and stream.jl

base/exports.jl

@@ -447,7 +447,6 @@ export
     zeros,
 
 # search, find, match and related functions
-    contains,
     eachmatch,
     endswith,
     equalto,
@@ -460,6 +459,7 @@ export
     findmax!,
     findnext,
     findprev,
+    isfound,
     occursin,
     match,
     searchsorted,

base/libc.jl

@@ -203,7 +203,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 !contains(fmt, r"([^%]|^)%(a|A|j|w|Ow)")
+        if !isfound(r"([^%]|^)%(a|A|j|w|Ow)", fmt)
             ccall(:mktime, Int, (Ref{TmStruct},), tm)
         end
     end

base/loading.jl

@@ -388,7 +388,7 @@ function project_file_name_uuid_path(project_file::String,
         uuid = dummy_uuid(project_file)
         path = joinpath("src", "$name.jl")
         for line in eachline(io)
-            contains(line, re_section) && break
+            isfound(re_section, line) && break
             if (m = match(re_name_to_string, line)) != nothing
                 name = String(m.captures[1])
             elseif (m = match(re_uuid_to_string, line)) != nothing
@@ -407,7 +407,7 @@ function project_file_manifest_path(project_file::String)::Union{Nothing,String}
     open(project_file) do io
         dir = abspath(dirname(project_file))
         for line in eachline(io)
-            contains(line, re_section) && break
+            isfound(re_section, line) && break
             if (m = match(re_manifest_to_string, line)) != nothing
                 return normpath(joinpath(dir, m.captures[1]))
             end
@@ -494,9 +494,9 @@ function explicit_project_deps_get(project_file::String, name::String)::Union{Bo
         state = :top
         for line in eachline(io)
             if state == :top
-                if contains(line, re_section)
+                if isfound(re_section, line)
                     root_name == name && return root_uuid
-                    state = contains(line, re_section_deps) ? :deps : :other
+                    state = isfound(re_section_deps, line) ? :deps : :other
                 elseif (m = match(re_name_to_string, line)) != nothing
                     root_name = String(m.captures[1])
                 elseif (m = match(re_uuid_to_string, line)) != nothing
@@ -506,7 +506,7 @@ function explicit_project_deps_get(project_file::String, name::String)::Union{Bo
                 if (m = match(re_key_to_string, line)) != nothing
                     m.captures[1] == name && return UUID(m.captures[2])
                 end
-            elseif contains(line, re_section)
+            elseif isfound(re_section, line)
                 state = :deps
             end
         end
@@ -524,7 +524,7 @@ function explicit_manifest_deps_get(manifest_file::String, where::UUID, name::St
         uuid = deps = nothing
         state = :other
         for line in eachline(io)
-            if contains(line, re_array_of_tables)
+            if isfound(re_array_of_tables, line)
                 uuid == where && break
                 uuid = deps = nothing
                 state = :stanza
@@ -533,9 +533,9 @@ function explicit_manifest_deps_get(manifest_file::String, where::UUID, name::St
                     uuid = UUID(m.captures[1])
                 elseif (m = match(re_deps_to_any, line)) != nothing
                     deps = String(m.captures[1])
-                elseif contains(line, re_subsection_deps)
+                elseif isfound(re_subsection_deps, line)
                     state = :deps
-                elseif contains(line, re_section)
+                elseif isfound(re_section, line)
                     state = :other
                 end
             elseif state == :deps && uuid == where
@@ -551,7 +551,7 @@ function explicit_manifest_deps_get(manifest_file::String, where::UUID, name::St
             @warn "Unexpected TOML deps format:\n$deps"
             return nothing
         end
-        contains(deps, repr(name)) || return true
+        isfound(repr(name), deps) || return true
         seekstart(io) # rewind IO handle
         manifest_file_name_uuid(manifest_file, name, io)
     end

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 || contains(file, r"In\[[0-9]+\]") && return ""
+    line <= 0 || isfound(r"In\[[0-9]+\]", file) && return ""
     Sys.iswindows() && (file = replace(file, '\\' => '/'))
     libgit2_id = PkgId(UUID((0x76f85450_5226_5b5a,0x8eaa_529ad045b433)), "LibGit2")
     if inbase(M)

base/mpfr.jl

@@ -936,7 +936,7 @@ end
 
 function _prettify_bigfloat(s::String)::String
     mantissa, exponent = split(s, 'e')
-    if !contains(mantissa, '.')
+    if !isfound('.', mantissa)
         mantissa = string(mantissa, '.')
     end
     mantissa = rstrip(mantissa, '0')

base/path.jl

@@ -78,7 +78,7 @@ end
 
 
 if Sys.iswindows()
-    isabspath(path::String) = contains(path, path_absolute_re)
+    isabspath(path::String) = isfound(path_absolute_re, path)
 else
     isabspath(path::String) = startswith(path, '/')
 end
@@ -113,7 +113,7 @@ julia> isdirpath("/home/")
 true
 ```
 """
-isdirpath(path::String) = contains(splitdrive(path)[2], path_directory_re)
+isdirpath(path::String) = isfound(path_directory_re, splitdrive(path)[2])
 
 """
     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) :
-    contains(a[end:end], path_separator_re) ? string(C,a,b) :
-                                              string(C,a,pathsep(a,b),b)
+    isempty(a)                             ? string(C,b) :
+    isfound(path_separator_re, a[end:end]) ? string(C,a,b) :
+                                             string(C,a,pathsep(a,b),b)
 end
 joinpath(a::AbstractString, b::AbstractString) = joinpath(String(a), String(b))
 

base/regex.jl

@@ -141,19 +141,19 @@ function getindex(m::RegexMatch, name::Symbol)
 end
 getindex(m::RegexMatch, name::AbstractString) = m[Symbol(name)]
 
-function contains(s::AbstractString, r::Regex, offset::Integer=0)
+function isfound(r::Regex, s::AbstractString; offset::Integer=0)
     compile(r)
     return PCRE.exec(r.regex, String(s), offset, r.match_options,
                      r.match_data)
 end
 
-function contains(s::SubString, r::Regex, offset::Integer=0)
+function isfound(r::Regex, s::SubString; offset::Integer=0)
     compile(r)
     return PCRE.exec(r.regex, s, offset, r.match_options,
                      r.match_data)
 end
 
-(r::Regex)(s) = contains(s, r)
+(r::Regex)(s) = isfound(r, s)
 
 """
     match(r::Regex, s::AbstractString[, idx::Integer[, addopts]])

base/strings/search.jl

@@ -425,30 +425,7 @@ julia> findprev("Julia", "JuliaLang", 6)
 """
 findprev(t::AbstractString, s::AbstractString, i::Integer) = _rsearch(s, t, i)
 
-"""
-    contains(haystack::AbstractString, needle::Union{AbstractString,Regex,Char})
-
-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}) =
+isfound(needle::Union{AbstractString,Char}, haystack::AbstractString) =
     _searchindex(haystack, needle, firstindex(haystack)) != 0
 
-in(::AbstractString, ::AbstractString) = error("use contains(x,y) for string containment")
+in(::AbstractString, ::AbstractString) = error("use isfound(x, y) for string containment")

base/uuid.jl

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

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 !contains(ident, r"^(?:|[0-9a-z-]*[a-z-][0-9a-z-]*)$"i) ||
+                if !isfound(r"^(?:|[0-9a-z-]*[a-z-][0-9a-z-]*)$"i, ident) ||
                     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 !contains(ident, r"^(?:|[0-9a-z-]*[a-z-][0-9a-z-]*)$"i) ||
+                if !isfound(r"^(?:|[0-9a-z-]*[a-z-][0-9a-z-]*)$"i, ident) ||
                     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]
-        contains(ident, r"^\d+$") ? parse(UInt64, ident) : String(ident)
+        isfound(r"^\d+$", ident) ? parse(UInt64, ident) : String(ident)
     end
 end
 

contrib/add_license_to_files.jl

@@ -81,7 +81,7 @@ function check_lines!(
     remove = []
     for i in 1:length(lines)
         line = lines[i]
-        if contains(line, checktxt)
+        if isfound(checktxt, line)
             if strip(line) == strip(prefix * checktxt) || strip(line) == strip(checktxt)
                 push!(remove, i)
             else

contrib/fixup_precompile.jl

@@ -1,5 +1,5 @@
 function needs_USE_GPL_LIBS(s::String)
-    contains(s, "CHOLMOD") && return true
+    isfound("CHOLMOD", s) && return true
     return false
 end
 
@@ -24,7 +24,7 @@ function fixup_precompile(new_precompile_file; merge=false)
         for line in eachline(file)
             line = strip(line)
             # filter out closures, which might have different generated names in different environments
-            contains(line, r"#[0-9]") && continue
+            isfound(r"#[0-9]", line) && continue
             # Other stuff than precompile statements might have been written to STDERR
             startswith(line, "precompile(Tuple{") || continue
             # Ok, add the line
@@ -65,4 +65,4 @@ elseif length(ARGS) == 2
     fixup_precompile(joinpath(pwd(), ARGS[2]); merge = true)
 else
     error("invalid arguments")
-end
+end

doc/src/base/arrays.md

@@ -129,6 +129,7 @@ Base.findnext(::Any, ::Integer)
 Base.findnext(::Function, ::Any, ::Integer)
 Base.findprev(::Any, ::Integer)
 Base.findprev(::Function, ::Any, ::Integer)
+Base.isfound
 Base.permutedims
 Base.permutedims!
 Base.PermutedDimsArray

doc/src/base/strings.md

@@ -35,7 +35,6 @@ Base.findfirst(::AbstractString, ::AbstractString)
 Base.findnext(::AbstractString, ::AbstractString, ::Integer)
 Base.findlast(::AbstractString, ::AbstractString)
 Base.findprev(::AbstractString, ::AbstractString, ::Integer)
-Base.contains
 Base.reverse(::Union{String,SubString{String}})
 Base.replace(s::AbstractString, ::Pair)
 Base.split