Improve docs for immutable composite type behavior as function arguments

[GravityAssisted]

In continuation from: https://groups.google.com/d/msg/julia-users/ZjOHONlVhsQ/eUBW51B5CgAJ

The statement from the docs:

"An object with an immutable type is passed around (both in assignment statements and in function calls) by copying, whereas a mutable type is passed around by reference."

is misleading and may not always be true (see discussion posted above).

My limited understanding and discussion with people on google groups suggests that the compiler is free to either copy or reference immutables (both singular or array of composite types ).

thanks,
Nitin

[JeffBezanson]

+1 Indeed, the whole point of immutable is that you can't tell whether the value was "copied".

[goelakash]

So from:

To recap, two essential properties define immutability in Julia:

• An object with an immutable type is passed around (both in assignment statements and in function calls) by copying, whereas a mutable type is passed around by reference.
• It is not permitted to modify the fields of a composite immutable type.

Could be changed to:

So essentially, It is not permitted to modify the fields of a composite immutable type.

[315234]

Is the following a manifestation of this issue?

function normalize!(data)
    data /= data[end]
end

data = fill(3.0, 10)
normalize!(data)
println(data[end])

I would expect this to print "1.0", instead it prints "3.0".

[yuyichao]

No, it is simply because /= is not a in-place update operator #249

[StefanKarpinski]

Even if /= were an in-place operator, this would still not work because floats are immutable and Julia functions cannot change bindings in the calling scope.

[mbauman]

This line fortunately no longer appears in the docs.