Skip to content

Document map behavior on sparse data structures #44233

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 6 commits into
base: master
Choose a base branch
from
Open

Document map behavior on sparse data structures #44233

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
a71efe0
Document `map` behavior
Feb 17, 2022
64a654e
clearer wording
Feb 17, 2022
4d75c5d
Merge branch 'master' into Document-sparsity-behavior
Mar 23, 2022
65a3ca6
Merge branch 'master' into Document-sparsity-behavior
Mar 30, 2022
06fb5e7
Add more docs
Apr 3, 2022
923443f
document other functions
Apr 3, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions base/abstractarray.jl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
8 changes: 6 additions & 2 deletions base/iterators.jl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
5 changes: 5 additions & 0 deletions base/reduce.jl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down