/// Groups the elements in a collection using a block.
///
/// @param collection An object that implements @c NSFastEnumeration.
/// @param block A block that takes an element in @c collection as its only
/// argument and returns a key by which to group the element.
/// The return value is required to implement @c NSCopying.
/// The block must not be @c nil .
///
/// @returns A dictionary that maps the keys returned by @c block to a set of all
/// values in @c collection that share the same key.
///
/// Examples:
/// @code
/// NSArray *numbers = @[ @1, @2, @3, @4, @5 ];
///
/// NSDictionary *grouped = ASTGroupBy(numbers, ^(NSNumber *number){
/// return number.integerValue % 2 == 0 ? @"even" : @"odd";
/// });
///
/// grouped[@"even"]; /// { @2, @4 }
/// grouped[@"odd"]; /// { @1, @3, @5 }
/// @endcode
ASTERISM_OVERLOADABLE NSDictionary *ASTGroupBy(id<NSFastEnumeration> collection, id<NSCopying> (NS_NOESCAPE ^block)(id obj)) {
return __ASTGroupBy_NSFastEnumeration_block(collection, block);
}
