More real world example in destructive read documentation

[bloodearnest]

In the introductory documentation for assignment and destructive reads (pony-tutorial/types/classes.md), a simple example is given of how you can swap a value in Pony with:

a = b = a

I mentioned this was a bit opaque on twitter, and exchanged some comments with @ponylang account, leading to this issue being filed.

It would perhaps be better to given a more concrete real world example here, or maybe link to the section that documents the "awesome things with a capabilities-secure type system".

[SeanTAllen]

Something like a destructive read to swap an iso would be my idea (like in TCPConnection) but that might be a bit much for an example.

[jemc]

I think we may want to avoid getting into capabilities stuff like iso and ephemerality this early in the tutorial.

Maybe just making it an example with a Map would be enough?

let map = Map[String, U64]
map("key1") = 100
map("key2") = 200
map("key1") = map("key2") = map("key1")

[rhagenson]

There is currently an example of destructive read using an iso later in the tutorial:

https://github.com/ponylang/pony-tutorial/blob/7e880412a2250ddc8c6611066ed613f3ae760766/content/reference-capabilities/consume-and-destructive-read.md#L40-L49

The Twitter thread appears like it was a barrier of first look at syntax, not lack of presence in the tutorial. The use in types/classes:

https://github.com/ponylang/pony-tutorial/blob/7e880412a2250ddc8c6611066ed613f3ae760766/content/types/classes.md#L162-L172

May be a bit much too soon. Do we want a "real world" example using Map (which then might confuse with the square brackets of generics), or for me to modify in-place to present it as a shorthand of syntax for swapping variables?

[SeanTAllen]

I'm thinking that rather than the tutorial, perhaps we want to cover the usage of destructive read in 1 or more pony patterns. As it is, a more "advanced" topic.

At the least using on iso fields is definitely an advanced topic worthy of a pony pattern.

[rhagenson]

I agree on destructive reads as a pattern entry. Destructive reads are an essential part of using Pony to its fullest (IMO), but their use amounts to a pattern as it is not something one must use, but should be aware of when reading Pony code.

[rhagenson]

A "real world example" using something like Map might fit in a Collections chapter as requested in #190

[Theodus]

I think that the destructive read pattern comes up so infrequently in practice that the existing example mentioned by @rhagenson is sufficient for explaining when it may be needed.

[rhagenson]

Added the "good first issue" label because I want someone's perspective on where a review/reminder of destructive read may be useful. The concept is not not covered, but a second mention that is not distracting would be helpful for anyone reading the Tutorial through the first time.