_groupBy

Groups the received Things by the specified Property or Expression -- Function

The same Type -> _groupBy (groupExp) -> The same Type

Receives -- The same Type: A List of values to be grouped
groupExp: The expression to apply to each received element, saying what to group it on
Produces: A List of _groupModel values.

This Function takes a list of Things, and collects them into groups based on the given Expression. The Expression may in principle be anything, but is most often a Property on the Things.

The result of this is a List of _groupModel values. _groupModel has two Properties:

_groupKey -- the key that identifies everything in this group
_groupMembers -- the list of values in this group

Don't use _groupMembers directly, though (it's hard to work with); instead, use the _groupElements function, which will fetch the elements the way you expect.

For example, say that My Model has a Property named Score, which is a number from 1-5. I can separate out all of the Instances of My Model based on Score, and print each group, by saying:

[[My Model._instances -> _groupBy(Score) -> 
  ""**Score:** [[_groupKey]]   **Members:** [[_groupElements -> _sort -> _commas]]""]]

This Function is still pretty delicate. If the parameter doesn't evaluate properly on all of the values, you will likely get an error.

ADVANCED: in principle, the data structure returned by _groupBy is a Map. It is somewhat likely that, somewhere down the line, we will add Map as an official Collection, and rewrite this in terms of that.