Define copy for immutable values

[bkamins]

Following the discussion in https://discourse.julialang.org/t/coordinating-community-efforts-to-enrich-function-docs/80338/8 I propose to add the following catch-all method for copy (tentative):

function copy(x::T) where T
    ismutable(x) || return x
    throw(ArgumentError("copy for values of type $T is not supported."))
end

However, maybe there are reasons why there is no such definition present?

[KristofferC]

See the discussion in #31995 (comment).

[bkamins]

So in short:

1. copy should be defined for mutable types only.
2. the fact that currently copy works for some immutable types is a left-over and is present only to reduce breakage? (unfortunately there are many such cases in practice)

If this is the case then probably this can be closed, but maybe a docstring of copy should be improved to reduce users' confusion?

[bkamins]

Maybe we can add one more point:

3. copy can be also defined for lazy structures (like views, transpose, adjoint) in which case it materializes them.

I assume this is also an intended use of copy?

[KristofferC]

Yes, I think that has became the de facto way of doing that (although it feels slightly weird).

[StefanKarpinski]

For what it's worth I've always felt that defining copy methods for immutable objects that just return their argument is fine but Jeff seems to feel strongly that this is not good.

[Tokazama]

Maybe we can add one more point:

3. copy can be also defined for lazy structures (like views, transpose, adjoint) in which case it materializes them.

I assume this is also an intended use of copy?

Is this intended to be a general pattern throughout the Julia ecosystem or just for those array types mentioned?

[bkamins]

Is this intended to be a general pattern throughout the Julia ecosystem or just for those array types mentioned?

I guess this is the point of this issue - I would like to settle the rules and write them down in the docsting of copy so that newcomers are clear what to expect (copy is a function that you learn very early when using Julia so it is important to have a precise contract for it IMHO; this issue was prompted by the documentation improvement initiative of @johnmyleswhite).

My feeling is like @KristofferC - it has become a de-facto way of doing this. Though maybe materialize would be a better function to achieve such effect. But for now I would prefer to focus on deciding the contract for copy in this issue.

[Tokazama]

materialize sounds like a better name for that to me since we use that for broadcasting too.

[Tokazama]

Iterators don't follow this pattern. For example, copy(Iterators.reverse([1, 2, 3])) errors.

[jakobnissen]

I would also like to point out that the proposed fallback implementation is wrong - for example, Sets are immutable according to ismutable, but has mutable semantics because they contain a field that can be mutated. For the proposed implementation to work, there would need to be a way to query if an object is semantically mutable which is not something we have.

[nsajko]

If the fallback were to use isbits(x) instead of ismutable(x) I think it would work as intended:

function copy(x::T) where {T}
    isbits(x) || throw(ArgumentError("copy for values of type $T is not supported."))
    x
end

[nsajko]

Although possibly ArgumentError is not the best exception type to use, xref #50196.