README.md

KVOMutableArray

KVOMutableArray is a proxy object which supports key value observation of NSMutableArray.

Installation

KVOMutableArray is available through CocoaPods. To install it, simply add the following line to your Podfile:

pod "KVOMutableArray"

KVOMutableArray supports monitoring with ReactiveCocoa signals. To enable this feature, add the following line instead:

pod "KVOMutableArray/ReactiveCocoaSupport"

If you don't have CocoaPods installed or integrated into your project, you can learn how to do so here.

Example

To run the example project, clone the repo, and run pod install from the Example directory first.

So what can I do with it?

Receive KVO notificaiton, YEAH!

KVOMutableArray* array = [KVOMutableArray new];
AMBlockToken* token = [array addObserverWithTask:^BOOL(id obj, NSDictionary *change) {
        NSIndexSet *indexes = change[NSKeyValueChangeIndexesKey];
        NSNumber *kind = change[NSKeyValueChangeKindKey];
        NSArray* new = change[NSKeyValueChangeNewKey];
        NSArray* old = change[NSKeyValueChangeOldKey];
        
        if ([kind integerValue] == NSKeyValueChangeInsertion)
        {
            NSLog(@"objects %@ added at indexes: %@", new, indexes);
        } else if ([kind integerValue] == NSKeyValueChangeRemoval)
        {
            NSLog(@"objects %@ removed from indexes: %@", old, indexes);
        }

        return YES;
    }];

Usage

Init array

KVOMutableArray* array = [KVOMutableArray new];
[array addObject:@"hello"];
[array addObject:@"world"];

Alternatively, you can do

KVOMutableArray* array = [[KVOMutableArray alloc] initWithObjects:@(1), @(2), @(3), nil];

Init from the exisiting NSArray

NSArray* someArray = @[@(1), @(2), @(3), @(4)];
KVOMutableArray* array = [[KVOMutableArray alloc] initWithArray:someArray];

Register KVO events

AMBlockToken* token = [array addObserverWithTask:^BOOL(id obj, NSDictionary *change) {
    // handle the event here
}];

Alternatively, you can use ReactiveCocoa signals.

RACSignal* signal = [array changeSignal];
[signal subscribeNext:^(RACTuple* t) {
    NSArray *obj = t.first;
    NSDictionary *change= t.second;
    // handle the event here
        
}];

Stop receiving KVO events

[token removeObserver];

Retrieve the enclosing NSMutableArray object

NSMutableArray* theMutableArray = array.arr;

Add, Remove, Access the objects

Manipulating the objects from KVOMutableArray

KVOMutableArray* array = [[KVOMutableArray alloc] initWithArray:@[@"hello", @"world"]];
[array removeLastObject];
[array addObject:@"awesome!"];
[array removeObjectAtIndex:0];
NSString* awesome = array[0];

Or from the enclosing NSMutableArray

KVOMutableArray* array = [[KVOMutableArray alloc] initWithArray:@[@"hello", @"world"]];
[array.arr removeLastObject];
[array.arr addObject:@"awesome!"];
[array.arr removeObjectAtIndex:0];
NSString* awesome = array.arr[0];

Gotchas

KVOMutableArray is now a subclass of NSMutableArray after 1.0 release. This change makes two gotchas available:

First, the unarchived object is an NSMutableArray, not a KVOMutableArary. No solution on StackOverflow so far.

KVOMutableArray* array = [[KVOMutableArray alloc] initWithArray:@[@(1), @(2), @(3)]];
NSData* data = [NSKeyedArchiver archivedDataWithRootObject:array];

// not a KVOMutableArray
NSMutableArray* unarchived = [NSKeyedUnarchiver unarchiveObjectWithData:data];

Second, the object returns from copy is a NSArray. There is no immutable KVOMutableArray, the only reasonable choice is to return immutable NSArray object.

KVOMutableArray* array = [[KVOMutableArray alloc] init];

// not a KVOMutableArray
NSArray* copy = [array copy];

Requirements

Requires iOS 8.0, and ARC.

How it works

Because NSMutableArray cannot be directly key value observed, we monitor the change events from a property of KVOMutableArray. For more details, check the stackoverflow discussion.

Contributing

Forks, patches and other feedback are welcome.

License

KVOMutableArray is available under the MIT license. See the LICENSE file for more info.