D-Programming-Language/dlang.org — pull request #623 by AndrewGodfrey (2014-08-01 08:22:53+00:00)
Title: Dynamic arrays: Fix some doc errors, and introduce the term 'array reference' to reduce confusion.

Discussion thread: http://forum.dlang.org/post/loekwubzykmysrdzwpak@forum.dlang.org

Changes:
- Where it says 'dynamic array', instead say 'array reference'.
Rationale:
1) When an array reference is an lvalue, it behaves like a reference, not a dynamic array.
2) When you shrink and later regrow an array reference, without using assumeSafeAppend(),
reallocation occurs. This behavior seems reasonable, but it is not expected behavior
for a dynamic array.
- Retain the term 'dynamic array' when we're referring to the GC-allocated array
that these types often refer to. Those act like arrays and are somewhat dynamic.
- Fix an error in expression.dd - the definition of identity for array references.

In arrays.dd:
- Fix some example code which didn't compile (especially around pointers).
- Reorder - introduce slices early, 'slicing' much later. Move "Array Declarations" later still.
- Add code cases around "s = " where s is a static array. The current version of arrays.dd
seems to think this is meaningless, but I found otherwise through experimentation.

Notes (things I didn't do):

- abi.dd: The section named "Reference types" is slightly affected. It could add that array references are
an exception to what it says there.
- d-array-article.dd: Some of this article is affected, it needs careful editing. Perhaps
the need for it is eliminated but perhaps not.
- ctod.dd: This makes the claim that "D supports dynamic arrays, which can be easily resized", which
I find overstating it. The example given only shows growing, not shrinking, and
it shows only a single array reference giving the impression of a one-to-one relationship
where there is actually in general a many-to-one relationship.
- My search/replace would have missed where "dynamic array" has a linebreak between the two words
in the .dd file. I noticed one case in overview.dd (but for that one, I prefer to leave it saying
"dynamic array").
- Where I found "static or dynamic array" I wrote "static array or array reference".
I'm inclined to think we don't need the "static" qualifier anymore, so
maybe these should now read "array or array reference".