//
//  NSIndexPath+MPAdditions.h
//  MathKit
//
//  Created by Kim Wittenburg on 23.04.14.
//  Copyright (c) 2014 Kim Wittenburg. All rights reserved.
//


/*!
 @header
 This file contains the <code>NSIndexPath(MPAdditions)</code> category.
 */



/*!
    @category   NSIndexPath (MPAdditions)
    @abstract   This category adds some methods for working with index paths to
                the <code>NSIndexPath</code> class.
 */
@interface NSIndexPath (MPAdditions)

/*!
    @property   firstIndex
    @abstract   The first index from the receiver.
 
    @discussion If the receiver is empty <code>NSNotFound</code> is returned.
 */
@property (readonly, nonatomic) NSUInteger firstIndex;


/*!
    @property   lastIndex
    @abstract   The last index from the receiver.
 
    @discussion If the receiver is empty <code>NSNotFound</code> is returned.
 */
@property (readonly, nonatomic) NSUInteger lastIndex;


/*!
    @method     indexPathByReplacingLastIndexWithIndex:
    @abstract   Provides an index path with the indexes of the receiver where the
                last one is replaced by <code>anIndex</code>.
 
    @discussion If the receiver is empty an index path of length <code>1</code>
                is returned. The last index in the returned index path is
                <code>anIndex</code>.
 
    @param      anIndex
                The index with which to replace the last index in the receiving
                index path.
 
    @return     A new index path with <code>anIndex</code> as its last index.
 */
- (NSIndexPath *)indexPathByReplacingLastIndexWithIndex:(NSUInteger)anIndex;


/*!
    @method     indexPathByRemovingFirstIndex
    @abstract   Provides an index path with the indexes in the receiving index
                path, excluding the first one.
 
    @discussion Returns an empty NSIndexPath instance if the receiving index
                path’s length is 1 or less.
 
    @return     A new index path with the receiving index path’s indexes,
                excluding the first one.
 */
- (NSIndexPath *)indexPathByRemovingFirstIndex;


/*!
    @method     indexPathByPreceedingIndex:
    @abstract   Provides an index path with the specified index followed by the
                indexes of the receiver.
 
    @discussion If the receiver does not contain any indexes the specified index
                is the only index contained in the returned index path.
 
    @param      anIndex
                The index new index preceeding all others
 
    @return     A new index path with all the receiver's indexes preceeded by
                <code>anIndex</code>
 */
- (NSIndexPath *)indexPathByPreceedingIndex:(NSUInteger)anIndex;


/*!
    @method     indexPathByIncrementingLastIndex
    @abstract   Provides an index path with the indexes in the receiving index
                path where the last one is incremented by <code>1</code>.
 
    @discussion If the receiver does not contain any indexes an empty index path
                is returned.

    @return     A new index path with all the receiver's indexes and the last one
                incremented by <code>1</code>.
 */
- (NSIndexPath *)indexPathByIncrementingLastIndex;


/*!
    @method     indexPathByDecrementingLastIndex
    @abstract   Provides an index path with the indexes in the receiving index
                path where the last one is decremented by <code>1</code>.
 
    @discussion If the receiver does not contain any indexes an empty index path
                is returned.
 
    @return     A new index path with all the receiver's indexes and the last one
                decremented by <code>1</code>.
 */
- (NSIndexPath *)indexPathByDecrementingLastIndex;


/*!
    @method     indexPathByRemovingIndexesFrom:
    @abstract   Provides an index path with the indexes in the recieving index
                path up to the index at the specified position.
 
    @discussion If <code>from</code> is greater or equal to the number of indexes
                in the receiving index path only the indexes to the end of the
                receiver are removed.
 
    @param      from
                The position of the first index to be excluded in the returned
                index path.
 
    @return     An index path with all indexes from the receiver up to position
                <code>from</code>.
 */
- (NSIndexPath *)indexPathByRemovingIndexesFrom:(NSUInteger)from;


/*!
    @method     indexPathByRemovingIndexesTo:
    @abstract   Provides an index path with the indexes in the receiving index
                path where the first indexes are removed.
 
 
    @discussion <code>to</code> specifies the number of indexes to be removed
                from the front. Thus the index at position <code>to</code> will
                be included in the returned index path.
 
    @param      to
                The number of indexes to remove from the front.
 
    @return     A new index path with all the receiver's indexes exept the first
                <code>to</code> ones.
 */
- (NSIndexPath *)indexPathByRemovingIndexesTo:(NSUInteger)to;


/*!
    @method     commonIndexPathWith:
    @abstract   Provides an index path that contains the first indexes of the
                receiver that are equal to the specified index path.
 
    @discussion If one index path is completely included in the other a new index
                path is returned that is equal to the contained index path.
 
    @param      indexPath
                The index path to compare the receiver against.
 
    @return     A new index path with the first indexes of the receiver that are
                also present in <code>indexPath</code>.
 */
- (NSIndexPath *)commonIndexPathWith:(NSIndexPath *)indexPath;

@end