From e6c6a43652190f007cc3e40590dc594fb82a8c22 Mon Sep 17 00:00:00 2001 From: Simeon Schaub Date: Wed, 10 Feb 2021 12:54:23 +0100 Subject: [PATCH] clarify documentation for @view (#39542) * clarify documentation for at-view * fix typo * Apply suggestions from code review Co-authored-by: Matt Bauman Co-authored-by: Matt Bauman --- base/views.jl | 21 +++++++++++++++++---- 1 file changed, 17 insertions(+), 4 deletions(-) diff --git a/base/views.jl b/base/views.jl index ccf24d4cdea3a7..f60dc04094a430 100644 --- a/base/views.jl +++ b/base/views.jl @@ -77,10 +77,23 @@ end """ @view A[inds...] -Creates a `SubArray` from an indexing expression. This can only be applied directly to a -reference expression (e.g. `@view A[1,2:end]`), and should *not* be used as the target of -an assignment (e.g. `@view(A[1,2:end]) = ...`). See also [`@views`](@ref) -to switch an entire block of code to use views for slicing. +Transform the indexing expression `A[inds...]` into the equivalent [`view`](@ref) call. + +This can only be applied directly to a single indexing expression and is particularly +helpful for expressions that include the special `begin` or `end` indexing syntaxes +like `A[begin, 2:end-1]` (as those are not supported by the normal [`view`](@ref) +function). + +Note that `@view` cannot be used as the target of a regular assignment (e.g., +`@view(A[1, 2:end]) = ...`), nor would the un-decorated +[indexed assignment](@ref man-indexed-assignment) (`A[1, 2:end] = ...`) +or broadcasted indexed assignment (`A[1, 2:end] .= ...`) make a copy. It can be useful, +however, for _updating_ broadcasted assignments like `@view(A[1, 2:end]) .+= 1` +because this is a simple syntax for `@view(A[1, 2:end]) .= @view(A[1, 2:end]) + 1`, +and the indexing expression on the right-hand side would otherwise make a +copy without the `@view`. + +See also [`@views`](@ref) to switch an entire block of code to use views for non-scalar indexing. !!! compat "Julia 1.5" Using `begin` in an indexing expression to refer to the first index requires at least