Dynamic/static arrays: Fix some doc errors #629
Conversation
Fix some documentation errors, around dynamic array semantics and static array syntax. - Add a note about the need for assumeSafeAppend in order to regrow a dynamic array. - Add examples for static arrays as lvalues (for copying and setting). - Soften an over-strong claim in ctod.dd. - Also tweak some heading levels and such.
|
|
||
| s[] = t; // the 3 elements of t[3] are copied into s[3] | ||
| s[] = t[]; // the 3 elements of t[3] are copied into s[3] | ||
| d[] = t; // the 3 elements of t are copied into d (unlike "d = t") |
There was a problem hiding this comment.
I would add a note what d = t does. You could add an example, e.g.:
int[] e = new int[3];
e = t;
e[0] = 10;
assert(t[0] == 10);There was a problem hiding this comment.
Well, it was already mentioned on line 160 ("a = s" there), and this section is focused on copying.
I agree with a few points you may be implicitly making:
- Sample code should use assert in this way to 'demonstrate' things, especially surprising things like this one.
- These semantics are surprising enough to warrant more exposition.
- This documentation is grouped by operation (such as copying), which only answers half of the questions a reader will have. The other half is: Given a particular syntax, like "array1 = array2;" what does it mean for a dynamic array vs. a static array?
I haven't decided what solution to propose, but here's a possible thought:
Perhaps this should be divided into a few sections - first considering only copying/assignment,
next adding concatentation and 'array-setting', and finally more esoteric things like prefix vs. postfix notation.
And then within each of the first two sections, explore all the interactions, in both 'directions' (that is, ordered by syntax and ordered by semantics).
There was a problem hiding this comment.
If it's already mentioned, then no need to worry. Looks good then.
|
Sorry for allowing this to go stale. Could you rebase this, and then I'll merge it? Thanks for the work so far! |
|
LGTM but please rebase. |
|
closing until we hear back from @AndrewGodfrey. Alternatively, @AndrejMitrovic are you familiar enough with this to take it over? |
|
I can't say right now when I'll have time. From: Andrei Alexandrescumailto:notifications@github.com LGTM but please rebase. Reply to this email directly or view it on GitHub: |
|
sounds good thx - reopen when ready |
Split out the less controversial fixes from #623:
Fix some documentation errors, around dynamic array semantics and static array syntax.