Merge pull request #17519 from Sacha0/convertnote

Augment convert's documentation with a note on aliasing

Author: tkelman

base/docs/helpdb/Base.jl

@@ -8041,6 +8041,38 @@ julia> convert(Rational{Int32}, x)
 julia> convert(Rational{Int64}, x)
 6004799503160661//18014398509481984
 ```
+
+If `T` is a collection type and `x` a collection, the result of `convert(T, x)` may alias
+`x`.
+```jldoctest
+julia> x = Int[1,2,3];
+
+julia> y = convert(Vector{Int}, x);
+
+julia> y === x
+true
+```
+Similarly, if `T` is a composite type and `x` a related instance, the result of
+`convert(T, x)` may alias part or all of `x`.
+```jldoctest
+julia> x = speye(5);
+
+julia> typeof(x)
+SparseMatrixCSC{Float64,Int64}
+
+julia> y = convert(SparseMatrixCSC{Float64,Int64}, x);
+
+julia> z = convert(SparseMatrixCSC{Float32,Int64}, y);
+
+julia> y === x
+true
+
+julia> z === x
+false
+
+julia> z.colptr === x.colptr
+true
+```
 """
 convert
 

doc/stdlib/base.rst

@@ -387,6 +387,39 @@ All Objects
        julia> convert(Rational{Int64}, x)
        6004799503160661//18014398509481984
 
+   If ``T`` is a collection type and ``x`` a collection, the result of ``convert(T, x)`` may alias ``x``\ .
+
+   .. doctest::
+
+       julia> x = Int[1,2,3];
+
+       julia> y = convert(Vector{Int}, x);
+
+       julia> y === x
+       true
+
+   Similarly, if ``T`` is a composite type and ``x`` a related instance, the result of ``convert(T, x)`` may alias part or all of ``x``\ .
+
+   .. doctest::
+
+       julia> x = speye(5);
+
+       julia> typeof(x)
+       SparseMatrixCSC{Float64,Int64}
+
+       julia> y = convert(SparseMatrixCSC{Float64,Int64}, x);
+
+       julia> z = convert(SparseMatrixCSC{Float32,Int64}, y);
+
+       julia> y === x
+       true
+
+       julia> z === x
+       false
+
+       julia> z.colptr === x.colptr
+       true
+
 .. function:: promote(xs...)
 
    .. Docstring generated from Julia source