add contains (argument flipped occursin) (#35132)

NEWS.md

@@ -110,6 +110,7 @@ New library functions
 * New function `bitreverse` for reversing the order of bits in a fixed-width integer ([#34791]).
 * New function `bitrotate(x, k)` for rotating the bits in a fixed-width integer ([#33937]).
 * One argument methods `startswith(x)` and `endswith(x)` have been added, returning partially-applied versions of the functions, similar to existing methods like `isequal(x)` ([#33193]).
+* New function `contains(haystack, needle)` and its one argument partially applied form have been added, it acts like `occursin(needle, haystack)`([#35132]).
 
 New library features
 --------------------

base/exports.jl

@@ -439,6 +439,7 @@ export
  zeros,
 
 # search, find, match and related functions
+ contains,
  eachmatch,
  endswith,
  findall,

base/strings/search.jl

@@ -526,6 +526,8 @@ true
 julia> occursin(r"a.a", "abba")
 false
 ```
+
+See also: [`contains`](@ref).
 """
 occursin(needle::Union{AbstractString,AbstractChar}, haystack::AbstractString) =
  _searchindex(haystack, needle, firstindex(haystack)) != 0

base/strings/util.jl

@@ -70,6 +70,33 @@ function endswith(a::Union{String, SubString{String}},
  end
 end
 
+"""
+ contains(haystack::AbstractString, needle)
+
+Return `true` if `haystack` contains `needle`.
+This is the same as `occursin(needle, haystack)`, but is provided for consistency with
+`startswith(haystack, needle)` and `endswith(haystack, needle)`.
+
+# 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
+```
+
+!!! compat "Julia 1.5"
+ The `contains` function requires at least Julia 1.5.
+"""
+contains(haystack::AbstractString, needle) = occursin(needle, haystack)
+
 """
  endswith(suffix)
 
@@ -100,6 +127,17 @@ used to implement specialized methods.
 """
 startswith(s) = Base.Fix2(startswith, s)
 
+"""
+ contains(needle)
+
+Create a function that checks whether its argument contains `needle`, i.e.
+a function equivalent to `haystack -> contains(haystack, needle)`.
+
+The returned function is of type `Base.Fix2{typeof(contains)}`, which can be
+used to implement specialized methods.
+"""
+contains(needle) = Base.Fix2(contains, needle)
+
 """
  chop(s::AbstractString; head::Integer = 0, tail::Integer = 1)
 

doc/src/base/strings.md

@@ -53,6 +53,7 @@ Base.lstrip
 Base.rstrip
 Base.startswith
 Base.endswith
+Base.contains
 Base.first(::AbstractString, ::Integer)
 Base.last(::AbstractString, ::Integer)
 Base.uppercase

test/strings/search.jl

@@ -356,6 +356,13 @@ end
 @test occursin("o", "foo")
 @test occursin('o', "foo")
 
+# contains
+@test contains("foo", "o")
+@test contains("foo", 'o')
+# contains in curried form
+@test contains("o")("foo")
+@test contains('o')("foo")
+
 @test_throws ErrorException "ab" ∈ "abc"
 
 # issue #15723