Added -groupBy to NSArray additions

Classes/NSArray+ObjectiveSugar.h

@@ -218,4 +218,13 @@
 
 - (NSArray *)symmetricDifference:(NSArray *)array;
 
+/**
+ Groups the collection by result of the block.
+
+ @return A dictionary where the keys are the evaluated result from
+ the block and the values are arrays of elements in the collection that correspond to the key.
+*/
+
+- (NSDictionary *)groupBy:(id (^)(id object))block;
+
 @end

Classes/NSArray+ObjectiveSugar.m

@@ -176,6 +176,25 @@ - (NSArray *)reverse {
     return self.reverseObjectEnumerator.allObjects;
 }
 
+- (NSDictionary *)groupBy:(id (^)(id object))block {
+	NSMutableDictionary *dictionary  = [NSMutableDictionary dictionary];
+
+	for (id object in self) {
+		id key = block(object);
+
+		if (![key conformsToProtocol:@protocol(NSCopying)]) {
+			[NSException raise:NSGenericException format:@"%@ does not conform to <NSCopying", object];
+		}
+
+		if (!dictionary[key]) {
+			dictionary[key] = [NSMutableArray arrayWithObject:object];
+		} else {
+			[dictionary[key] addObject:object];
+		}
+	}
+	return dictionary;
+}
+
 #pragma mark - Set operations
 
 - (NSArray *)intersectionWithArray:(NSArray *)array {

Classes/NSDictionary+ObjectiveSugar.h

@@ -14,6 +14,8 @@
 - (void)eachKey:(void (^)(id key))block;
 - (void)eachValue:(void (^)(id value))block;
 - (NSArray *)map:(id (^)(id key, id value))block;
+- (NSDictionary *)dictionaryMap:(id (^)(id key, id value))block;
+
 - (BOOL)hasKey:(id)key;
 
 @end

Classes/NSDictionary+ObjectiveSugar.m

@@ -41,6 +41,17 @@ - (NSArray *)map:(id (^)(id key, id value))block {
     return array;
 }
 
+- (NSDictionary *)dictionaryMap:(id (^)(id key, id value))block {
+	NSMutableDictionary *dictionary = [NSMutableDictionary dictionary];
+
+	[self enumerateKeysAndObjectsUsingBlock:^(id key, id obj, BOOL *stop) {
+		id result = block(key, obj);
+		dictionary[key] = result;
+	}];
+
+	return dictionary;
+}
+
 - (BOOL)hasKey:(id)key {
     return !!self[key];
 }

Example/ObjectiveSugarTests/NSArrayCategoriesTests.m

@@ -197,6 +197,24 @@
         });
 
     });
+
+	context(@"grouping", ^{
+		it(@"-groupBy groups array to dictionary where keys are results of block", ^{
+			[[[@[@1, @2, @3, @4, @5, @6] groupBy:^id(NSNumber *object) {
+				return @([object integerValue] % 3);
+			}] should] equal:@{@1: @[@1, @4], @2: @[@2, @5], @0: @[@3, @6]}];
+		});
+
+		it(@"-groupBy throws exception when block result does not conform to <NSCopying>", ^{
+			[[theBlock(^{
+				[@[@1] groupBy:^id(id object) {
+					return [[NSObject alloc] init];
+				}];
+			}) should] raiseWithName:NSGenericException];
+
+		});
+
+	});
 
 });
 

Example/ObjectiveSugarTests/NSDictionaryTests.m

@@ -68,6 +68,20 @@
 
         [[mapped should] equal:sampleDict.allValues];
     });
+
+	it(@"maps new values to existing keys", ^{
+		NSDictionary *result = [sampleDict dictionaryMap:^id(id key, id value) {
+			counter++;
+			return @([value integerValue] + 1);
+		}];
+
+		[[result should] equal:@{
+								@"one" : @2,
+								@"two" : @3,
+								@"three" : @4
+								}];
+
+	});
 });
 
 describe(@"Keys", ^{