diff --git a/base/abstractarray.jl b/base/abstractarray.jl index af29aee6a74b6..2c5e3b2682642 100644 --- a/base/abstractarray.jl +++ b/base/abstractarray.jl @@ -2787,6 +2787,11 @@ colons go in this expression. The results are concatenated along the remaining d For example, if `dims` is `[1,2]` and `A` is 4-dimensional, `f` is called on `A[:,:,i,j]` for all `i` and `j`. +Note that `mapslices` makes no guarantees about the order of execution. In addition, `f` is +assumed to be [pure](https://en.wikipedia.org/wiki/Pure_function) when working with sparse +data structures. Using an impure function with `mapslices` may cause bugs on sparse or +diagonal arrays, as `f` may only be called once on duplicated elements. + See also [`eachcol`](@ref), [`eachslice`](@ref). # Examples @@ -2940,6 +2945,11 @@ mapany(f, itr) = Any[f(x) for x in itr] Transform collection `c` by applying `f` to each element. For multiple collection arguments, apply `f` elementwise, and stop when when any of them is exhausted. +Note that `map` makes no guarantees about the order of execution. In addition, `f` is assumed +to be [pure](https://en.wikipedia.org/wiki/Pure_function) when working with sparse data +structures. Using an impure function with `map` may cause bugs on sparse or diagonal arrays, +as `f` may only be called once on duplicated elements. + See also [`map!`](@ref), [`foreach`](@ref), [`mapreduce`](@ref), [`mapslices`](@ref), [`zip`](@ref), [`Iterators.map`](@ref). # Examples @@ -2997,6 +3007,11 @@ end Like [`map`](@ref), but stores the result in `destination` rather than a new collection. `destination` must be at least as large as the smallest collection. +Note that `map!` makes no guarantees about the order of execution. In addition, `f` is assumed +to be [pure](https://en.wikipedia.org/wiki/Pure_function) when working with sparse data +structures. Using an impure function with `map!` may cause bugs on sparse or diagonal arrays, +as `f` may only be called once on duplicated elements. + See also: [`map`](@ref), [`foreach`](@ref), [`zip`](@ref), [`copyto!`](@ref). # Examples diff --git a/base/iterators.jl b/base/iterators.jl index 1b96a24a9c16f..65452fbada9ab 100644 --- a/base/iterators.jl +++ b/base/iterators.jl @@ -27,8 +27,12 @@ export enumerate, zip, rest, countfrom, take, drop, takewhile, dropwhile, cycle, """ Iterators.map(f, iterators...) -Create a lazy mapping. This is another syntax for writing -`(f(args...) for args in zip(iterators...))`. +Create a lazy mapping. + +When calling `Iterators.map`, `f` is assumed to be +[pure](https://en.wikipedia.org/wiki/Pure_function) if working with sparse +data structures. Using an impure function with `map` may cause bugs on sparse or diagonal +arrays, as `f` may only be called once on duplicated elements. !!! compat "Julia 1.6" This function requires at least Julia 1.6. diff --git a/base/reduce.jl b/base/reduce.jl index 13e1b69c79ede..b4fa5eb851552 100644 --- a/base/reduce.jl +++ b/base/reduce.jl @@ -277,6 +277,11 @@ In general, it will be necessary to provide `init` to work with empty collection intermediate collection needs to be created. See documentation for [`reduce`](@ref) and [`map`](@ref). +Note that `mapreduce` makes no guarantees about the order of execution. In addition, `f` is +assumed to be [pure](https://en.wikipedia.org/wiki/Pure_function) when working with sparse +data structures. Using an impure function with `mapreduce` may cause bugs on sparse or +diagonal arrays, as `f` may only be called once on duplicated elements. + !!! compat "Julia 1.2" `mapreduce` with multiple iterators requires Julia 1.2 or later.