From 8e3f1d5faa16fecf07c3c97383d66029fd068ac4 Mon Sep 17 00:00:00 2001 From: pabloferz Date: Sat, 22 Oct 2016 18:13:22 -0500 Subject: [PATCH] News and docs for #18965 --- NEWS.md | 4 ++++ base/broadcast.jl | 18 ++++++++++++------ doc/manual/arrays.rst | 2 +- doc/stdlib/arrays.rst | 11 ++++++++--- 4 files changed, 25 insertions(+), 10 deletions(-) diff --git a/NEWS.md b/NEWS.md index edf49a6e89f9da..d11e57a9a3d829 100644 --- a/NEWS.md +++ b/NEWS.md @@ -24,6 +24,9 @@ This section lists changes that do not have deprecation warnings. * `broadcast` now handles tuples, and treats any argument that is not a tuple or an array as a "scalar" ([#16986]). + * `broadcast` now treats `Ref` (except for `Ptr`) arguments as 0-dimensional + arrays ([#18965]). + Library improvements -------------------- @@ -691,4 +694,5 @@ Language tooling improvements [#18442]: https://github.com/JuliaLang/julia/issues/18442 [#18473]: https://github.com/JuliaLang/julia/issues/18473 [#18839]: https://github.com/JuliaLang/julia/issues/18839 +[#18965]: https://github.com/JuliaLang/julia/issues/18965 [#19018]: https://github.com/JuliaLang/julia/issues/19018 diff --git a/base/broadcast.jl b/base/broadcast.jl index 1c0afd876a19fc..92972c5c58884e 100644 --- a/base/broadcast.jl +++ b/base/broadcast.jl @@ -267,15 +267,16 @@ end """ broadcast(f, As...) -Broadcasts the arrays, tuples and/or scalars `As` to a container of the +Broadcasts the arrays, tuples, `Ref` and/or scalars `As` to a container of the appropriate type and dimensions. In this context, anything that is not a -subtype of `AbstractArray` or `Tuple` is considered a scalar. The resulting -container is established by the following rules: +subtype of `AbstractArray`, `Ref` (except for `Ptr`s) or `Tuple` is considered +a scalar. The resulting container is established by the following rules: - If all the arguments are scalars, it returns a scalar. - If the arguments are tuples and zero or more scalars, it returns a tuple. - - If there is at least an array in the arguments, it returns an array - (and treats tuples as 1-dimensional arrays) expanding singleton dimensions. + - If there is at least an array or a `Ref` in the arguments, it returns an array + (and treats any `Ref` as a 0-dimensional array of its contents and any tuple + as a 1-dimensional array) expanding singleton dimensions. A special syntax exists for broadcasting: `f.(args...)` is equivalent to `broadcast(f, args...)`, and nested `f.(g.(args...))` calls are fused into a @@ -317,11 +318,16 @@ julia> abs.((1, -2)) julia> broadcast(+, 1.0, (0, -2.0)) (1.0,-1.0) -julia> broadcast(+, 1.0, (0, -2.0), [1]) +julia> broadcast(+, 1.0, (0, -2.0), Ref(1)) 2-element Array{Float64,1}: 2.0 0.0 +julia> (+).([[0,2], [1,3]], Ref{Vector{Int}}([1,-1])) +2-element Array{Array{Int64,1},1}: + [1,1] + [2,2] + julia> string.(("one","two","three","four"), ": ", 1:4) 4-element Array{String,1}: "one: 1" diff --git a/doc/manual/arrays.rst b/doc/manual/arrays.rst index ba99ceb0419731..b36d8a9bab66e5 100644 --- a/doc/manual/arrays.rst +++ b/doc/manual/arrays.rst @@ -526,7 +526,7 @@ function elementwise: Elementwise operators such as ``.+`` and ``.*`` perform broadcasting if necessary. There is also a :func:`broadcast!` function to specify an explicit destination, and :func:`broadcast_getindex` and :func:`broadcast_setindex!` that broadcast the indices before indexing. Moreover, ``f.(args...)`` is equivalent to ``broadcast(f, args...)``, providing a convenient syntax to broadcast any function (:ref:`man-dot-vectorizing`). -Additionally, :func:`broadcast` is not limited to arrays (see the function documentation), it also handles tuples and treats any argument that is not an array or a tuple as a "scalar". +Additionally, :func:`broadcast` is not limited to arrays (see the function documentation), it also handles tuples and treats any argument that is not an array, tuple or `Ref` (except for `Ptr`) as a "scalar". .. doctest:: diff --git a/doc/stdlib/arrays.rst b/doc/stdlib/arrays.rst index 7bcdfa25f602c3..35bda247f1ec90 100644 --- a/doc/stdlib/arrays.rst +++ b/doc/stdlib/arrays.rst @@ -642,11 +642,11 @@ All mathematical operations and functions are supported for arrays .. Docstring generated from Julia source - Broadcasts the arrays, tuples and/or scalars ``As`` to a container of the appropriate type and dimensions. In this context, anything that is not a subtype of ``AbstractArray`` or ``Tuple`` is considered a scalar. The resulting container is established by the following rules: + Broadcasts the arrays, tuples, ``Ref`` and/or scalars ``As`` to a container of the appropriate type and dimensions. In this context, anything that is not a subtype of ``AbstractArray``\ , ``Ref`` (except for ``Ptr``\ s) or ``Tuple`` is considered a scalar. The resulting container is established by the following rules: * If all the arguments are scalars, it returns a scalar. * If the arguments are tuples and zero or more scalars, it returns a tuple. - * If there is at least an array in the arguments, it returns an array (and treats tuples as 1-dimensional arrays) expanding singleton dimensions. + * If there is at least an array or a ``Ref`` in the arguments, it returns an array (and treats any ``Ref`` as a 0-dimensional array of its contents and any tuple as a 1-dimensional array) expanding singleton dimensions. A special syntax exists for broadcasting: ``f.(args...)`` is equivalent to ``broadcast(f, args...)``\ , and nested ``f.(g.(args...))`` calls are fused into a single broadcast loop. @@ -687,11 +687,16 @@ All mathematical operations and functions are supported for arrays julia> broadcast(+, 1.0, (0, -2.0)) (1.0,-1.0) - julia> broadcast(+, 1.0, (0, -2.0), [1]) + julia> broadcast(+, 1.0, (0, -2.0), Ref(1)) 2-element Array{Float64,1}: 2.0 0.0 + julia> (+).([[0,2], [1,3]], Ref{Vector{Int}}([1,-1])) + 2-element Array{Array{Int64,1},1}: + [1,1] + [2,2] + julia> string.(("one","two","three","four"), ": ", 1:4) 4-element Array{String,1}: "one: 1"