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



@interface NSIndexPath (MPAdditions)


/*!
    @property   firstIndex
    @brief      The first index from the index path.
 
    @discussion If the index path is empty @c NSNotFound is returned.
 */
@property (readonly, nonatomic) NSUInteger firstIndex;


/*!
    @property   lastIndex
    @brief      The last index from the index path.
 
    @discussion If the index path is empty @c NSNotFound is returned.
 */
@property (readonly, nonatomic) NSUInteger lastIndex;


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


/*!
    @method     indexPathByRemovingFirstIndex
    @brief      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:
    @brief      Provides an index path with the given index followed by the
                indexes of the receiver.
 
    @discussion If the receiver does not contain any indexes the given index is
                the only index contained in the returned index path.
 
    @param      index
                The index new index preceeding all others
 
    @return     A new index path with all the receiver's indexes preceeded by @c
                index.
 */
- (NSIndexPath *)indexPathByPreceedingIndex:(NSUInteger)index;


/*!
    @method     indexPathByIncrementingLastIndex
    @brief      Provides an index path with the indexes in the receiving index
                path where the last one is incremented by @c 1.
 
    @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 @c 1.
 */
- (NSIndexPath *)indexPathByIncrementingLastIndex;


/*!
    @method     indexPathByDecrementingLastIndex
    @brief      Provides an index path with the indexes in the receiving index
                path where the last one is decremented by @c 1.
 
    @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 @c 1.
 */
- (NSIndexPath *)indexPathByDecrementingLastIndex;


/*!
    @method     indexPathByRemovingIndexesFrom:
    @brief      Provides an index path with the indexes in the recieving index
                path up to the index at the given position.
 
    @discussion If @c from 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
                @c from.
 */
- (NSIndexPath *)indexPathByRemovingIndexesFrom:(NSUInteger)from;


/*!
    @method     indexPathByRemovingIndexesTo:
    @brief      Provides an index path with the indexes in the receiving index
                path where the first indexes are removed.
 
 
    @discussion @c to specifies the number of indexes to be removed from the
                front. Thus the index at position @c to 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
                @c to ones.
 */
- (NSIndexPath *)indexPathByRemovingIndexesTo:(NSUInteger)to;


/*!
    @method     commonIndexPathWith:
    @brief      Provides an index path that contains the first indexes of the
                receiver that are equal to the given 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 @c indexPath.
 */
- (NSIndexPath *)commonIndexPathWith:(NSIndexPath *)indexPath;

@end