diff --git a/base/docs/helpdb/Base.jl b/base/docs/helpdb/Base.jl index 698602b5f1854..d03e6fbca2784 100644 --- a/base/docs/helpdb/Base.jl +++ b/base/docs/helpdb/Base.jl @@ -8129,6 +8129,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 diff --git a/doc/stdlib/base.rst b/doc/stdlib/base.rst index f961e60fa2270..1ab5dc5cbb08a 100644 --- a/doc/stdlib/base.rst +++ b/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