#Functional.m

Functional.m is an extension for objective-c, that can be used to do functional programming.

Here's the documentation for the individual functions:

The numberArray NSArray contains a collection of NSNumbers, The dict NSDictionary contains the same collection - the keys are the names of the numbers

    NSArray *numberArray = [NSArray arrayFrom:1 To:5];
    NSArray *numberNamesArray = [NSArray arrayWithObjects:@"one", @"two", @"three", @"four", @"five", nil];
    NSDictionary *numberDict = [NSDictionary dictionaryWithObjects:numberArray forKeys:numberNamesArray];

##each

The given iterator runs for each object in the collection.

• - (void) each:(VoidIteratorArrayBlock) block;
• - (void) each:(VoidIteratorDictBlock) block;

Example:

    [numberArray each:^(id obj) {
        NSLog(@"Current Object : %@", obj);
    }];
    
    [numberDict each:^(id key, id value) {
        NSLog(@"%@ => %@", key, value);
    }];

##map

Each object in the collection can be transformed in the iterator.

• - (NSArray *) map:(MapArrayBlock) block;
• - (NSDictionary *) map:(MapDictBlock) block;

Example:

    NSArray *doubleArray = [numberArray map:^NSNumber*(NSNumber *obj) {
        return [NSNumber numberWithInt:([obj intValue]*2)];
    }];
    NSDictionary *doubleDict = [numberDict map:^NSNumber*(id key, NSNumber *obj) {
        return [NSNumber numberWithInt:([obj intValue]*2)];
    }];
    
    NSLog(@"Double : Array %@ - Dict %@", doubleArray, doubleDict);

##reduce

Reduces all objects in the collection to a single value (something like computing the average etc.)

• - (id) reduce:(ReduceArrayBlock) block withInitialMemo:(id) memo;
• - (id) reduce:(ReduceDictBlock) block withInitialMemo:(id) memo;

Example - adds all NSNumbers in the array or dictionary.

    NSNumber *memo = [NSNumber numberWithInt:0];
    
    NSNumber *sumArray = [numberArray reduce:^NSNumber*(NSNumber *memo, NSNumber *cur) {
        return [NSNumber numberWithInt:([memo intValue] + [cur intValue])];
    } withInitialMemo:memo];
    
    NSNumber *sumDict = [numberDict reduce:^NSNumber*(NSNumber *memo, id key, NSNumber *cur) {
        return [NSNumber numberWithInt:([memo intValue] + [cur intValue])];
    } withInitialMemo:memo];
    
    NSLog(@"Sum : Array %@ - Dict %@", sumArray, sumDict);

##filter and reject

Filter gives you only those objects, for that the iterator returns true. Reject removes all objects for that the iterator returns true.

• - (NSArray *) filter:(BoolArrayBlock) block;

• - (NSArray *) reject:(BoolArrayBlock) block;

• - (NSDictionary*) filter:(BoolDictionaryBlock) block;

• - (NSDictionary*) reject:(BoolDictionaryBlock) block;

This example gives you all even (filter) or odd (reject) numbers in the array / dict:

        BoolArrayBlock isEvenArrayBlock = ^BOOL(NSNumber *obj) {
            return (([obj intValue] % 2) == 0);
        };
        BoolDictionaryBlock isEvenDictBlock = ^BOOL(id key, NSNumber *obj) {
            return (([obj intValue] % 2) == 0);
        };
    
        NSArray *evenArr    = [numberArray filter:isEvenArrayBlock];
        NSDictionary *evenDict   = [numberDict filter:isEvenDictBlock];
        NSLog(@"The following elements are even : Array %@ - Dict %@", evenArr, evenDict);
    
    #pragma mark - reject
        NSArray *oddArr = [numberArray reject:isEvenArrayBlock];
        NSDictionary *oddDict = [numberDict reject:isEvenDictBlock];
        NSLog(@"The following elements are odd : Array %@ - Dict %@", oddArr, oddDict);   

##isValidForAll and isValidForAny

isValidForAll returns YES if the iterator returns YES for all elements in the collection. isValidForAny returns YES if the iterator returns YES for at least one object in the collection.

• - (BOOL) isValidForAll:(BoolArrayBlock) block;

• - (BOOL) isValidForAny:(BoolArrayBlock) block;

• - (BOOL) isValidForAll:(BoolDictionaryBlock) block;

• - (BOOL) isValidForAny:(BoolDictionaryBlock) block;

This example checks if all or any elements in the collection are even numbers

    BoolArrayBlock isEvenArrayBlock = ^BOOL(NSNumber *obj) {
        return (([obj intValue] % 2) == 0);
    };
    BoolDictionaryBlock isEvenDictBlock = ^BOOL(id key, NSNumber *obj) {
        return (([obj intValue] % 2) == 0);
    };

    NSLog(@"Only even numbers : Array %d - Dict %d", [numberArray isValidForAll:isEvenArrayBlock], [numberDict isValidForAll:isEvenDictBlock]);
    # pragma mark - isValidForAny
    NSLog(@"Any even numbers : Array %d - Dict %d", [numberArray isValidForAny:isEvenArrayBlock], [numberDict isValidForAny:isEvenDictBlock]);

##countValidEntries

Counts the number of entries in a set, for which the given block returns true:

• - (NSNumber *) countValidEntries:(BoolArrayBlock) block;
• - (NSNumber *) countValidEntries:(BoolDictionaryBlock) block;

    BoolArrayBlock isEvenArrayBlock = ^BOOL(NSNumber *obj) {
        return (([obj intValue] % 2) == 0);
    };
    BoolDictionaryBlock isEvenDictBlock = ^BOOL(id key, NSNumber *obj) {
        return (([obj intValue] % 2) == 0);
    };

    NSNumber *ctEvenArr     = [numberArray countValidEntries:isEvenArrayBlock];
    NSNumber *ctEvenDict    = [numberDict countValidEntries:isEvenDictBlock];
    NSLog(@"The number of even elements are : Array %@ - Dict %@", ctEvenArr, ctEvenDict);

##dropWhile

Drops every entry before the first item the block returns true for.

• - (NSArray *) dropWhile:(BoolArrayBlock) block;

	NSArray *droppedUntilThree = [numberArray dropWhile:^BOOL(NSNumber *nr) {
	    return ([nr integerValue] < 3);
	}];
	NSLog(@"Array from 3 : %@", droppedUntilThree);

##max and min

Return the maximum and the minimum values in a collection. You will have to write a comperator, which compares two elements.

• - (id) max:(CompareArrayBlock) block;

• - (id) min:(CompareArrayBlock) block;

• - (id) max:(CompareDictBlock) block;

• - (id) min:(CompareDictBlock) block;

Here's an example that gets the minimum and the maximum value from the array and dict described above:

        CompareArrayBlock compareArrBlock = ^NSComparisonResult(NSNumber *a, NSNumber *b) {
            return [a compare:b];
        };
    
        CompareDictBlock compareDictBlock = ^NSComparisonResult(id k1, NSNumber *v1, id k2, NSNumber *v2) {
            return [v1 compare:v2];
        };
    
        NSNumber *maxArr    = [numberArray max:compareArrBlock];
        NSNumber *maxDict   = [numberDict max:compareDictBlock];
        NSLog(@"Max : Array %@ - Dict %@", maxArr, maxDict);
    
    #pragma mark - min
        NSNumber *minArr    = [numberArray min:compareArrBlock];
        NSNumber *minDict   = [numberDict min:compareDictBlock];
        NSLog(@"Min : Array %@ - Dict %@", minArr, minDict);

##sort

Sort is actually just an alias for [self sortedArrayUsingComparator:block];

• - (NSArray *) sort:(NSComparator) block;

See NSArray sortedArrayUsingComperator: for reference.

Here's an example:

    NSComperator compareArrBlock = ^NSComparisonResult(NSNumber *a, NSNumber *b) {
        return [a compare:b];
    };

    NSArray *nrReversed = [numberArray reverse];
    NSArray *sorted     = [nrReversed sort:compareArrBlock];
    NSLog(@"%@ becomes %@ when sorted", nrReversed, sorted);

##group

Groups an array by the values returned by the iterator.

• - (NSDictionary *) group:(MapArrayBlock) block;

Here's an example that groups an array into an odd numbers section and an even numbers section:

	NSDictionary *oddEvenArray = [numberArray group:^NSString *(NSNumber *obj) {
        if (([obj intValue] % 2) == 0) return @"even";
        else return @"odd";
    }];
	NSLog(@"Grouped array %@", oddEvenArray);

##times

Call times on an NSNumber (n) to iterate n times over the given block.

• - (void) times:(VoidBlock) block;

Here's a simple example - it prints 'have i told you' once:

    NSNumber *howMany   = [numberArray first];
    [howMany times:^{
        NSLog(@"have i told you?");
    }];

##NSArray additions

###arrayFrom:To:

Creates an array, that contains the range as individual NSNumbers

• + (NSArray *) arrayFrom:(NSInteger) from To:(NSInteger) to;

Example:

	NSArray *rArr = [NSArray arrayFrom:0 To:3];
    NSLog(@"Array from 0 to 3 %@", rArr);

###first

• - (id) first;

Just a shortcut for [array objectAtIndex:0];

###tail

• -(NSArray *) tail;

Extract the elements after the head of the array, which must be non-empty.

###flatten

• -(NSArray *) flatten;

Creates a new array which contains all the elements in the current array, but 'unpacks' any arrays contained in it. Any nested arrays will be replaced by their respective objects, so that the final array only contains non-array objects.

###reverse

• - (NSArray *) reverse;

Returns the reversed array

###arrayUntilIndex and arrayFromIndexOn

These are helper functions. They return the elements of the array they are called on until (excluding) the given index or from the given index on (including).

• - (NSArray *) arrayUntilIndex:(NSInteger) idx;
• - (NSArray *) arrayFromIndexOn:(NSInteger) idx;

	NSArray *untilTwo = [numberArray arrayUntilIndex:2];
	NSArray *afterTwo = [numberArray arrayFromIndexOn:2];
	NSLog(@"The array until idx 2 : %@ and thereafter : %@", untilTwo, afterTwo); // 1,2 and 3,4,5

###bind

• - (NSArray *) bind:(BindArrayBlock) block;

Maps block over the list, then concatenates (flattens) the result, where block is expected to take an item and return an array.

###zip

• - (NSArray *) zip:(NSArray *) rhs;

zip takes two arrays and returns an array of corresponding pairs. If one input list is short, excess elements of the longer array are discarded.