Add section documenting tuple unpacking

[WardBrian]

Submission Checklist

• Builds locally
• New functions marked with `r since("VERSION")`
• Declare copyright holder and open-source license: see below

Summary

Docs for stan-dev/stanc3#1360. Unfortunately I dropped the ball on documenting this earlier, so we will need to re-build the docs for the current release after this (and hopefully #678)

Copyright and Licensing

Please list the copyright holder for the work you are submitting (this will be you or your assignee, such as a university or company):
Simons Foundation

By submitting this pull request, the copyright holder is agreeing to license the submitted work under the following licenses:

• Code: BSD 3-clause (https://opensource.org/licenses/BSD-3-Clause)
• Documentation: CC BY-ND 4.0 (https://creativecommons.org/licenses/by-nd/4.0/)

[bob-carpenter]

Typo and some questions that should be resolved.

[bob-carpenter]

Would it help to say these aren't general lvalues but must be indexes? That is, we can't have indexed expressions on the LHS can we?

Would it also help to say that the parens are required, unlike in Python?

[WardBrian]

You can have an indexed expression on the left hand side, but it is required to be unique. This sort of also answers your follow-up question, which is we implemented an overly conservative approach that means you cannot assign to different sub-parts of the same variable at the same time, since it would be impossible to statically check in general.

For example, the following is forbidden by stanc:

data {
  tuple(array[3] int, array[4] int) x;
}
model {
  array[7] real x_flat;
    // ILLEGAL
  (x_flat[ : 3], x_flat[3 : ]) = x;
}

[bob-carpenter]

[optional]
I would use lower case t or x for the tuple here to avoid confusion with T being read as a generic type.

[bob-carpenter]

I think the nesting needs an example. I'm imagining (i, (r, z)) = x or something like that?

[WardBrian]

Yes. I've updated the existing example to do both at once following some re-ordering of paragraphs here.

[bob-carpenter]

This seems to say it's general, but the earlier description says it's just variables. Which is it? And if it's indexed, how do we avoid aliasing or check when it's now a runtime issue?

[WardBrian]

Updated the earlier description. See above for how we avoid aliasing, but the short version is the statement that the same variable may not appear more than once is correct. This is a bit overly-conservative, but does prevent the aliasing problem for indexed assignments appearing here.

[bob-carpenter]

Thanks for the updates.