ETCollection documentation

Authors

Quentin Mathe (qmathe@club-internet.fr)
NSObject and collection class additions like a collection protocol.

Copyright: (C) 2007 Quentin Mathe


Contents -

  1. Software documentation for the ETCollectionTrait class
  2. Software documentation for the ETMutableCollectionTrait class
  3. Software documentation for the NSArray(ETCollection) category
  4. Software documentation for the NSArray(Etoile) category
  5. Software documentation for the NSCountedSet(ETCollection) category
  6. Software documentation for the NSDictionary(ETCollection) category
  7. Software documentation for the NSDictionary(Etoile) category
  8. Software documentation for the NSIndexSet(ETCollection) category
  9. Software documentation for the NSMutableArray(ETCollectionMutation) category
  10. Software documentation for the NSMutableArray(Etoile) category
  11. Software documentation for the NSMutableDictionary(DictionaryOfLists) category
  12. Software documentation for the NSMutableDictionary(ETCollectionMutation) category
  13. Software documentation for the NSMutableIndexSet(ETCollectionMutation) category
  14. Software documentation for the NSMutableOrderedSet(ETCollectionMutation) category
  15. Software documentation for the NSMutableSet(ETCollectionMutation) category
  16. Software documentation for the NSObject(ETBatchCollectionMutation) informal protocol
  17. Software documentation for the NSObject(ETCollectionMutationKVOSupport) category
  18. Software documentation for the NSOrderedSet(ETCollection) category
  19. Software documentation for the NSSet(ETCollection) category
  20. Software documentation for the ETCollection protocol
  21. Software documentation for the ETCollectionMutation protocol
  22. Software documentation for the ETKeyedCollection protocol
  23. ETCollection types
  24. ETCollection constants

Software documentation for the ETCollectionTrait class

ETCollectionTrait : NSObject

Declared in:
ETCollection.h
Conforms to:
ETCollection

@group Collection Protocols

This trait implements all ETCollection protocol methods, except -content and -contentArray , for which concrete implementations must be provided by the target class.

Any method provided by ETCollectionTrait can be overriden by implementing the method in the target class.

Here is a simple example that implements a complete mutable collection API. In addition to ETCollectionTrait, it also leverages ETMutableCollectionTrait to do so.

@interface MyCollection : NSObject >ETCollection, ETCollectionMutation<
{
	NSMutableArray *things;
}

@end

#pragma GCC diagnostic ignored "-Wprotocol"

@implementation

+ (void) initialize
{
	if (self != [MyCollection class])
		return;

	[self applyTraitFromClass: [ETCollection class]];
	[self applyTraitFromClass: [ETMutableCollection class]];
}

// Omitted initialization and deallocation methods

- (id) content
{
	return things;
}

- (NSArray *) contentArray
{
	return [NSArray arrayWithArray: things];
}

- (void) insertObject: (id)object atIndex: (NSUInteger)index hint: (id)hint
{
	if (index == ETUndeterminedIndex)
	{
		[things addObject: object];
	}
	else
	{
		[things insertObject: object atIndex: index];
	}
}

- (void) removeObject: (id)object atIndex: (NSUInteger)index hint: (id)hint
{
	if (index == ETUndeterminedIndex)
	{
		[things removeObject: object];
	}
	else
	{
		[things removeObjectAtIndex: index];
	}
}

@end 

Software documentation for the ETMutableCollectionTrait class

ETMutableCollectionTrait : ETCollectionTrait

Declared in:
ETCollection.h
Conforms to:
ETCollectionMutation

@group Collection Protocols

This trait implements all ETCollectionMutation protocol methods, except -insertObject:atIndex:hint: and -removeObject:atIndex:hint: , for which concrete implementations must be provided by the target class.

Any method provided by ETMutableCollectionTrait can be overriden by implementing the method in the target class.

For a use case example, see ETCollectionTrait.

Software documentation for the NSArray(ETCollection) category

NSArray(ETCollection)

Declared in:
ETCollection.h
Conforms to:
ETCollection

@group Collection Protocols

Method summary

mutableClass 

+ (Class) mutableClass;

Returns NSMutableDictionary class.


content 

- (id) content;
Description forthcoming.

contentArray 

- (NSArray*) contentArray;
Description forthcoming.

isOrdered 

- (BOOL) isOrdered;
Description forthcoming.

viewpointArray 

- (NSArray*) viewpointArray;
Description forthcoming.

Software documentation for the NSArray(Etoile) category

NSArray(Etoile)

Declared in:
ETCollection.h

@group Collection Additions

Method summary

arrayByRemovingObject: 

- (NSArray*) arrayByRemovingObject: (id)anObject;

Returns a new array by copying the receiver and removing the objects equal to the given one.


arrayByRemovingObjectsInArray: 

- (NSArray*) arrayByRemovingObjectsInArray: (NSArray*)anArray;

Returns a new array by copying the receiver and removing the objects equal to those contained in the given array.


filteredArrayUsingPredicate: ignoringObjects: 

- (NSArray*) filteredArrayUsingPredicate: (NSPredicate*)aPredicate ignoringObjects: (NSSet*)ignoredObjects;

Returns a filtered array as -filteredArrayWithPredicate: does but always includes in the new array the given objects to be ignored by the filtering.


firstObject 

- (id) firstObject;

Returns the first object in the array, otherwise returns nil if the array is empty.


firstObjectMatchingValue: forKey: 

- (id) firstObjectMatchingValue: (id)value forKey: (NSString*)key;

Deprecated

Same as the -objectsMatchingValue:forKey: , except it returns the first object that matches the receiver.

Nil is returned when no object can be matched.


objectsMatchingValue: forKey: 

- (NSArray*) objectsMatchingValue: (id)value forKey: (NSString*)key;

@taskunit Deprecated

Deprecated

Returns the objects on which -valueForKey: returns a value that matches the given one.

For every object in the receiver, -valueForKey: will be invoked with the given key.

NSArray *personsNamedJohn = [persons objectsMatchingValue: @"John" forKey: @"name"];

You should now use -filteredArrayUsingPredicate or -filter instead. For example:

NSArray *personsNamedJohn = [persons filteredArrayUsingPredicate: 
	[NSPredicate predicateWithFormat: @"name == %@", @"John"]];

Deprecated

Returns the objects on which -valueForKey: returns a value that matches the given one.

For every object in the receiver, -valueForKey: will be invoked with the given key.

NSArray *personsNamedJohn = [persons objectsMatchingValue: @"John" forKey: @"name"];

You should now use -filteredArrayUsingPredicate or -filter instead. For example:

NSArray *personsNamedJohn = [persons filteredArrayUsingPredicate: 
	[NSPredicate predicateWithFormat: @"name == %@", @"John"]];

Software documentation for the NSCountedSet(ETCollection) category

NSCountedSet(ETCollection)

Declared in:
ETCollection.h

@group Collection Protocols

NSCountedSet is a NSMutableSet subclass and thereby inherits the collection protocol methods implemented in NSSet(ETCollection).

Method summary

mutableClass 

+ (Class) mutableClass;

Returns self, the NSCountedSet class.

NSCountedSet is always mutable and has not immutable equivalent.


Software documentation for the NSDictionary(ETCollection) category

NSDictionary(ETCollection)

Declared in:
ETCollection.h
Conforms to:
ETKeyedCollection

@group Collection Protocols

Method summary

mutableClass 

+ (Class) mutableClass;

Returns NSMutableDictionary class.


arrayRepresentation 

- (NSArray*) arrayRepresentation;
Description forthcoming.

content 

- (id) content;
Description forthcoming.

contentArray 

- (NSArray*) contentArray;
Description forthcoming.

identifierAtIndex: 

- (NSString*) identifierAtIndex: (NSUInteger)index;
Description forthcoming.

isKeyed 

- (BOOL) isKeyed;
Description forthcoming.

viewpointArray 

- (NSArray*) viewpointArray;
Description forthcoming.

Software documentation for the NSDictionary(Etoile) category

NSDictionary(Etoile)

Declared in:
ETCollection.h

@group Collection Additions

Method summary

containsKey: 

- (BOOL) containsKey: (NSString*)aKey;

Returns whether the dictionary contains the given key among -allKeys .


Software documentation for the NSIndexSet(ETCollection) category

NSIndexSet(ETCollection)

Declared in:
ETCollection.h
Conforms to:
ETCollection

@group Collection Protocols

Method summary

mutableClass 

+ (Class) mutableClass;

Returns NSMutableIndexSet class.


content 

- (id) content;
Description forthcoming.

contentArray 

- (NSArray*) contentArray;
Description forthcoming.

objectEnumerator 

- (NSEnumerator*) objectEnumerator;
Description forthcoming.

Software documentation for the NSMutableArray(ETCollectionMutation) category

NSMutableArray(ETCollectionMutation)

Declared in:
ETCollection.h
Conforms to:
ETCollectionMutation

@group Collection Protocols

For NSMutableArray, -insertObject:atIndex: raises an exception when the index is ETUndeterminedIndex.

Software documentation for the NSMutableArray(Etoile) category

NSMutableArray(Etoile)

Declared in:
ETCollection.h

@group Collection Additions

Method summary

removeObjectsFromIndex: 

- (void) removeObjectsFromIndex: (NSUInteger)anIndex;

Removes the objects located between anIndex and the end of the array.

The object located at anIndex is included in the removed objects.


Software documentation for the NSMutableDictionary(DictionaryOfLists) category

NSMutableDictionary(DictionaryOfLists)

Declared in:
ETCollection.h

@group Collection Additions

Extension to NSMutableDictionary for a common case where each key may map to several values.

Method summary

addObject: forKey: 

- (void) addObject: (id)anObject forKey: (id)aKey;

Adds an object for the specific key. If there is no value for this key, it is added. If there is an existing value and it is a mutable array, then the object is added to the array. If it is not a mutable array, the existing object and the new object are both added to a new array, which is set for this key in the dictionary.


Software documentation for the NSMutableDictionary(ETCollectionMutation) category

NSMutableDictionary(ETCollectionMutation)

Declared in:
ETCollection.h
Conforms to:
ETCollectionMutation

@group Collection Protocols

Software documentation for the NSMutableIndexSet(ETCollectionMutation) category

NSMutableIndexSet(ETCollectionMutation)

Declared in:
ETCollection.h
Conforms to:
ETCollectionMutation

@group Collection Protocols

Software documentation for the NSMutableOrderedSet(ETCollectionMutation) category

NSMutableOrderedSet(ETCollectionMutation)

Declared in:
ETCollection.h
Conforms to:
ETCollectionMutation
Description forthcoming.

Software documentation for the NSMutableSet(ETCollectionMutation) category

NSMutableSet(ETCollectionMutation)

Declared in:
ETCollection.h
Conforms to:
ETCollectionMutation

@group Collection Protocols

Software documentation for the NSObject(ETBatchCollectionMutation) informal protocol

NSObject(ETBatchCollectionMutation)

Declared in:
ETCollection.h

@group Collection Protocols

Any mutable collection can also implement the optional methods listed below.

EtoileUI will use these methods when possible.
Initially you can skip implementing them. Later, they can be implemented to speed up the communication between your model collections and the layout items that represent them at the UI level. In addition, these methods allows to react to batch insertion and removal at the model level (e.g. in reply to a pick and drop).

You are not required to implement every method when a class adopts this informal protocol.

When a collection is received in argument, the collection type can be checked to know whether the code needs to convert the collection or not, to remove or insert its content in the receiver. In most cases, the code below is a useless optimization (the else branch is good enough).

if ([[aCollection content] isArray] == NO)
{
	[personIvarArray addObjectsFromArray: (NSArray *)aCollection];
}
else
{
	[personIvarArray addObjectsFromArray: [aCollection contentArray]];
}

See NSObject+Model for other methods such as -isArray .

Method summary

insertCollection: atIndexes: 

- (void) insertCollection: (id<ETCollection>)objects atIndexes: (NSIndexSet*)indexes;

Inserts the given collection elements at separate indexes.

When the collection is not ordered, the indexes are ignored.

The element are inserted one-by-one by increasing index value while iterating over the indexes. When the greatest index is reached and several elements remain to be inserted, they are inserted at that same index.
For a more precise description of the behavior ordered collection should comply to, see -[NSArray insertObjects:atIndexes:] in Cocoa documentation.


removeObjectAtIndexes: 

- (void) removeObjectAtIndexes: (NSIndexSet*)indexes;

Removes the elements at the given indexes from the collection.

You should only implement this method when the collection is ordered.


removesCollection: 

- (void) removesCollection: (id<ETCollection>)objects;

Removes the elements from the collection.


Software documentation for the NSObject(ETCollectionMutationKVOSupport) category

NSObject(ETCollectionMutationKVOSupport)

Declared in:
ETCollection.h
Description forthcoming.
Method summary

didChangeValueForKey: atIndexes: withObjects: mutationKind: 

- (void) didChangeValueForKey: (NSString*)key atIndexes: (NSIndexSet*)indexes withObjects: (NSArray*)objects mutationKind: (ETCollectionMutationKind)mutationKind;
Description forthcoming.

willChangeValueForKey: atIndexes: withObjects: mutationKind: 

- (void) willChangeValueForKey: (NSString*)key atIndexes: (NSIndexSet*)indexes withObjects: (NSArray*)objects mutationKind: (ETCollectionMutationKind)mutationKind;
Description forthcoming.

Software documentation for the NSOrderedSet(ETCollection) category

NSOrderedSet(ETCollection)

Declared in:
ETCollection.h
Conforms to:
ETCollection
Description forthcoming.

Software documentation for the NSSet(ETCollection) category

NSSet(ETCollection)

Declared in:
ETCollection.h
Conforms to:
ETCollection

@group Collection Protocols

Method summary

mutableClass 

+ (Class) mutableClass;

Returns NSMutableSet class.


content 

- (id) content;
Description forthcoming.

contentArray 

- (NSArray*) contentArray;
Description forthcoming.

viewpointArray 

- (NSArray*) viewpointArray;
Description forthcoming.

Software documentation for the ETCollection protocol

ETCollection

Declared in:
ETCollection.h
Conforms to:
NSObject

@group Collection Protocols

Basic collection protocol that all collections must support. EtoileFoundation extends Foundation classes such as NSArray, NSDictionary, NSSet and NSIndexSet to adopt this protocol. EtoileUI extends NSView in the same way.

With this protocol, the collection content can be accessed and queried in various ways but cannot be mutated.

Given most protocol method implementations remains the same accross collection classes, we provide ETCollectionTrait as a reusable ETCollection implementation.

The two primitives methods are -content and -contentArray . These methods must be implemented in the collection class in all cases. See ETCollectionTrait.

When you write a new class that includes a to-many relationship, it should conform to ETCollection. If several to-many relationships exist, you should pick the dominant relationship that best represents the main content. A good hint is to pick the most recurrent way to browse the content with a UI, and the relationship traversed in such a case.
EtoileUI can automatically present collection-like content and support navigation into it when represented objects bound to ETLayoutItemGroup conform to ETCollection.

Note: In future, we will provide a viewpoint mechanism to view or traverse objects through their non-dominant to-many relationships.

Method summary

containsCollection: 

- (BOOL) containsCollection: (id<ETCollection>)objects;

Returns whether every element in the given collection are included in the receiver.


containsObject: 

- (BOOL) containsObject: (id)anObject;

Returns whether the element is included in the collection.


content 

- (id) content;

Returns the underlying data structure object holding the content or self when the protocol is adopted by a class which is a content data structure by itself (like NSArray, NSDictionary, NSSet etc.).

Content by its very nature is always a collection of other objects. As such, content may hold one or no objects (empty collection).

When adopted, this method must never return nil.


contentArray 

- (NSArray*) contentArray;

Returns the content as a new NSArray-based collection of objects.

When adopted, this method must never return nil, you should generally return an empty NSArray instead.


count 

- (NSUInteger) count;

Returns the number of elements hold by the receiver.


countByEnumeratingWithState: objects: count: 

- (NSUInteger) countByEnumeratingWithState: (NSFastEnumerationState*)state objects: (id*)objects count: (NSUInteger)count;

Returns a C array through objects which can be used to iterate over the content in several quick passes until 0 is returned.

Each time the method is called, the C array contains a new content portion to be iterated over.

The method returns the number of objects in the C array.

The count argument must be used to indicate the maximum number of objects allowed in the C array to be returned.

See NSFastEnumeration protocol.


isEmpty 

- (BOOL) isEmpty;

Returns YES when the collection contains no elements, otherwise returns NO.


isKeyed 

- (BOOL) isKeyed;

Returns whether the receiveir stores the elements by key.

If the receivers returns YES, it must implement -arrayRepresentation .
-arrayRepresentation must return the content as a key-value pair array.


isOrdered 

- (BOOL) isOrdered;

Returns whether the receiveir stores the elements in a sorted order or not.


objectEnumerator 

- (NSEnumerator*) objectEnumerator;

Returns an enumerator which can be used as a conveniency to iterate over the elements of the content one-by-one.


viewpointArray 

- (NSArray*) viewpointArray;

Returns the collection represented as viewpoints on the collection elements.


Software documentation for the ETCollectionMutation protocol

ETCollectionMutation

Declared in:
ETCollection.h

@group Collection Protocols

Additional collection protocol that all mutable collections must support. EtoileFoundation extends Foundation classes such as NSMutableArray, NSMutableDictionary, NSMutableSet, NSCountedSet and NSMutableIndexSet to adopt this protocol. EtoileUI extends NSView in the same way.

Given most protocol method implementations remains the same accross collection classes, we provide ETMutableCollectionTrait as a reusable ETCollectionMutation implementation.

The two primitive methods are -insertObject:atIndex:hint: and -removeObject:atIndex:hint: . These methods must be implemented in the collection class in all cases. See ETMutableCollectionTrait.

When you write a new class that includes a mutable to-many relationship, it should conform to ETCollectionMutation, based on the rules presented in ETCollection documentation.
EtoileUI can automatically mutate collection-like content and support turning user actions (e.g. drag an drop) into collection operations, when represented objects bound to ETLayoutItemGroup conform to ETCollectionMutation in addition to ETCollection.

Method summary

addObject: 

- (void) addObject: (id)object;

Adds the element to the collection.

A collection can raise an exception on a nil object.

When the collection is ordered, the element is inserted as the last element.


insertObject: atIndex: 

- (void) insertObject: (id)object atIndex: (NSUInteger)index;

Inserts the element at the given index in the collection.

A collection can raise an exception on a nil object.
An ordered collection can raise an exception on an invalid index such as ETUndeterminedIndex (this is not the same behavior than -insertObject:atIndex:hint:).

When the collection is not ordered, the index is ignored and the behavior is the same than -addObject: .


insertObject: atIndex: hint: 

- (void) insertObject: (id)object atIndex: (NSUInteger)index hint: (id)hint;

Inserts the element at the given index in the collection, by making adjustments based on the hint if needed.

The element to be inserted must never be nil. The collection can raise an exception in such case.

If the collection is not ordered, the index can be ignored (the insertion becomes an addition), but otherwise it must not.

If the index is ETUndeterminedIndex, the insertion must be treated as an addition and the object inserted in last position if the collection is ordered e.g. NSMutableArray. See also -addObject: .

If the hint is not nil, the collection can test the hint type. If the hint matches its expectation, it's up to the collection to choose another index and/or another element to insert. Both the custom index and element can be provided by the hint.
The collection must continue to behave in a predictable way (as detailed above) when no hint is provided.


insertObjects: atIndexes: hints: 

- (void) insertObjects: (NSArray*)objects atIndexes: (NSIndexSet*)indexes hints: (NSArray*)hints;
Description forthcoming.

removeObject: 

- (void) removeObject: (id)object;

Removes the element from the collection.

A collection can raise an exception on a nil object.


removeObject: atIndex: hint: 

- (void) removeObject: (id)object atIndex: (NSUInteger)index hint: (id)hint;

Removes the element at the given index from the collection, by making adjustments based on the hint if needed.

The element can be nil, but then the index must not be ETUndeterminedIndex. Otherwise the collection can raise an exception.

If the collection is not ordered, the index can be ignored, but otherwise it must not.

If the index is ETUndeterminedIndex, all occurences of the element must be removed from the collection.

If both the element and index are valid, the element should be ignored and priority must be given to the index to locate the objects to remove (this rule is subject to change a bit).

If the hint is not nil, the collection can test the hint type. If the hint matches its expectation, it's up to the collection to choose another index and/or another element to remove. Both the custom index and element can be provided by the hint.
The collection must continue to behave in a predictable way (as detailed above) when no hint is provided.
If the hint can provide both a custom element and index, as stated previously, priority must be given to the index to locate the objects to remove.


removeObjectAtIndex: 

- (void) removeObjectAtIndex: (NSUInteger)index;

Removes the element at the given index from the collection.

An ordered collection can raise an exception on an invalid index such as ETUndeterminedIndex.

When the collection is not ordered, an exception should be raised.


removeObjects: atIndexes: hints: 

- (void) removeObjects: (NSArray*)objects atIndexes: (NSIndexSet*)indexes hints: (NSArray*)hints;
Description forthcoming.

Software documentation for the ETKeyedCollection protocol

ETKeyedCollection

Declared in:
ETCollection.h
Conforms to:
ETCollection
Description forthcoming.
Method summary

arrayRepresentation 

- (NSArray*) arrayRepresentation;

Returns an ETKeyValuePair array where every entry present in the keyed collection is turned into a pair object.

The returned array is autoreleased.


ETCollection types

ETCollectionMutationKind

typedef enum ... ETCollectionMutationKind;
Description forthcoming.

ETCollection constants

ETUndeterminedIndex

const NSUInteger ETUndeterminedIndex;

Marks an element which shouldn't be considered bound to a particular index in an ordered collection or whose index isn't yet determined.
For use cases, see ETCollectionMutation.

With EtoileUI, can be used to indicate a drop is not an insertion at precise index but a simple drop on.