diff --git a/NEWS.md b/NEWS.md index 371417e35c74c..3edd1fdc46d25 100644 --- a/NEWS.md +++ b/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 -------------------- diff --git a/base/exports.jl b/base/exports.jl index 2e8f2ccc3d72c..f0e7981215bf4 100644 --- a/base/exports.jl +++ b/base/exports.jl @@ -439,6 +439,7 @@ export zeros, # search, find, match and related functions + contains, eachmatch, endswith, findall, diff --git a/base/strings/search.jl b/base/strings/search.jl index 15d0a968a0226..dbc572dc948fa 100644 --- a/base/strings/search.jl +++ b/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 diff --git a/base/strings/util.jl b/base/strings/util.jl index 22dee5ebd024a..14fc530dfcd7e 100644 --- a/base/strings/util.jl +++ b/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) diff --git a/doc/src/base/strings.md b/doc/src/base/strings.md index 12da6d950abaf..22943329af501 100644 --- a/doc/src/base/strings.md +++ b/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 diff --git a/test/strings/search.jl b/test/strings/search.jl index 8de73e5c652e5..92fc03177dc76 100644 --- a/test/strings/search.jl +++ b/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