/*
 *  HOMIteration.h
 *  HigherOrderMessaging
 *
 *  Created by Ofri Wolfus on 10/09/05.
 *  Copyright 2005 Ofri Wolfus. All rights reserved.
 *
 */

#import <HigherOrderMessaging/HOM.h>

/*!
 * @header HOMIteration
 * HOMIteration defines the general HOM messages for collection objects.
 * @copyright Created by Ofri Wolfus on 10/09/05. Copyright 2004-2005 Ofri Wolfus. All rights reserved.
 * @updated 2005-09-05
 * @version 0.1
 */

/*!
 * @protocol HOMIteration
 * @abstract HOMIteration defines the general HOM collection messages.
 * All HOM enabled collection object should implement this protocol.
 */
@protocol HOMIteration

/*!
 * @method collect
 * @abstract Makes all objects of the receiver perform the argument message, and returns the results of the messages.
 * @discussion The receiver will loop through all it's objects, make them perform the argument message, and will collect the results.
 * The argument message must return a pointer value.
 */
- (id)collect;

/*!
 * @method select
 * @abstract Returns all objects of the receiver that returned YES for the argument message.
 * @discussion The receiver will loop through all it's objects and will return only the ones the returned YES for the argument message.
 * The argument message must return a BOOL value or otherwise nil will be returned.
 * The return value of the argument message must be a pointer.
 */
- (id)select;

/*!
 * @method reject
 * @abstract Returns all objects of the receiver that returned NO for the argument message.
 * @discussion The receiver will loop through all it's objects and will return only the ones the returned NO for the argument message.
 * The argument message must return a BOOL value or otherwise nil will be returned.
 * The return value of the argument message must be a BOOL.
 * This is the opposite of -select.
 */
- (id)reject;

/*!
 * @method each
 * @abstract Returns an iterated object (argument) for use with the do prefix message.
 * @discussion See the documentation of -do and Higher_Order_Messaging_OOPSLA_2005.pdf for more info about the combination of both.
 * In addition, the <code>each</code> method can be used as a prefix message that will forward the argument message to all objects of the collection (the receiver).
 * For example, lets say you want to call <code>doSomething:a with:b</code> on all objects of a collection. In that case you would do it like this: <code>[[collection each] doSomething:a with:b]</code>.
 */
- (id)each;

/*!
 * @method selectWhere
 * @abstract Returns all objects of the receiver that returned YES for the second argument message.
 * @discussion The receiver will collect the results of the first argument message and will then select the only ones that returned YES for the second argument message.
 */
- (id)selectWhere;

/*!
 * @method singleSelect
 * @abstract This method does the same as -select but returns one, and only one, object or nil.
 */
- (id)singleSelect;

/*!
 * @method singleReject
 * @abstract This method does the same as -reject but returns one, and only one, object or nil.
 */
- (id)singleReject;

/*!
 * @method singleSelectWhere
 * @abstract This is a combination of -selectWhere and -singleSelect. It does the same as -selectWhere, but always returns one object or nil.
 */
- (id)singleSelectWhere;

@end