Add a Chapter on Collections

[mfelsche]

As a newcomer to pony (coming from java, scala, python, erlang) i would really really love to see a section about collections in the tutorial as this a pretty important building block of day to day programming (next to primitives, classes, actors ...).

Useful information would be:

• general semantics and use-cases/examples of the collection types provided
  • basics like List, Set, Map behaviour
  • Map vs. MapIs behaviour as special varieties
  • persistent vs. mutable data structures and usage patterns thereof
• showcase useful features like Map.upsert and Map.insert_if_absent

Most of this is not directly uniquely related to pony but knowledge of how to powerful the language is in terms of solving day to day problems would really help getting a feeling about the language and help people get into it.

[mfelsche]

Please also include Array examples

[mfelsche]

I would have started to write up something but i don't feel confident enough with pony yet.

[vak]

I've spent half an hour to implement basic Map container member within a class and ...failed :-/ The type constraints are not clear. Could someone add into tutorial or into example section of repository a clear example on how could one work with Map, please?

[mfelsche]

We agreed on adding a section about collection on the precondition that the actual collection docstrings and package documentation will have some serious overhaul and this section will be more of a starting point for a guided tour of the standard library with pointing people into the right direction and refers to the stdlib docs.

[marctrem]

Ha, I also had a hard time figuring out how to create a HashMap. In case other people end up here as I did:

let m = HashMap[U64, String, HashIs[U64]].create() will do the trick!

As far as I understand (started to read the pony tutorial 2h ago):

• a primitive is a type which can only contain functions (useful to implement stateless traits and interfaces)
• HashIs[A][0] is a primitive which implements both hashable interfaces: Hashable and Hashable64.
• There is no constraint on the type parameter A since you can do (digestof x) on anything (even tags).

Please let me know if my understanding is wrong!

[0] https://github.com/ponylang/ponyc/blob/1b72941baa38cb23cba6fc8f7fb8b4d73cc57b28/packages/collections/hashable.pony#L84

[rhagenson]

Personal opinion significantly in the future of when this issue was last discussed during sync, to add a chapter like this I would want to move Object Capabilities after Generics then put this chapter after Generics.

In brief, currently the order is:

1. Getting Started
2. Types
3. Expressions
4. Reference Capabilities
5. Object Capabilities
6. Generics
7. ...

Changing to:

1. Getting Started
2. Types
3. Expressions
4. Reference Capabilities
5. Generics
6. Collections
7. Object Capabilities
8. ...

[SeanTAllen]

I'm not in favor of "chapter on collections". I'm in favor of adding at the end of the tutorial a "tour through the standard library" that highlights the most commonly used things that we want people to be aware of like net, collections, and what not.

[rhagenson]

@SeanTAllen A tour of the standard library sounds fair. I see that tour being placed after "Gotchas" and before "Where Next?" Any objection to that?

[SeanTAllen]

Sounds good to me @rhagenson.