//
//  MPRangePath.h
//  MathKit
//
//  Created by Kim Wittenburg on 18.04.14.
//  Copyright (c) 2014 Kim Wittenburg. All rights reserved.
//

#import "MPExpression.h"


/*!
 @header
 This file contains the <code>MPRangePath</code> class.
 
 The <code>MPRangePath</code> combines an <code>NSIndexPath</code> with a
 <code>NSRange</code>. A range path is used in a tree structure to identify a
 number of subsequent nodes. This is achieved by combining a range path that
 stores the location of the first node in the tree with an integer that stores
 the number of nodes that should be included in the range path.
 */


/*!
    @define     MPMakeRangePath
    @abstract   Creates a new <code>NSRangePath</code> instance with the given
                location and length.
 
    @param      loc
                The location of the first included item. This must be an
                <code>NSIndexPath</code> instance.
 
    @param      len
                The number of nodes to include in the range path.
 
    @return     A new range path.
 */
#define MPMakeRangePath(loc, len) [MPRangePath rangePathWithLocation:(loc) length:(len)]



@class MPRangePath, MPExpression;


/*!
    @class      MPRangePath
    @abstract   A <code>MPRangePath</code> instance identifies a range of
                subsequent nodes in a tree structure.
 
    @discussion <code>MPRangePath</code> instances are immutable.
 */
@interface MPRangePath : NSObject <NSCopying, NSCoding>

#pragma mark Creation Methods
/*!
 @methodgroup Creation Methods
 */


/*!
    @method     init
    @abstract   Initializes an empty range path.
 
    @discussion This method is a convenience initializer to create a range path
                with an empty location and a length of <code>0</code>.
 
    @return     A new <code>MPRangePath</code> instance.
 */
- (instancetype)init;


/*!
    @method     initWithRange:
    @abstract   Initializes a newly created range path with the specified range.
 
    @discussion This method is a convenience initializer to convert from a
                <code>NSRange</code> struct to a <code>MPRangePath</code>
                instance. The location of the created range path is an index path
                of length <code>1</code>.
 
    @param      aRange
                The range to be converted into a <code>MPRangePath</code>.
 
    @return     A <code>MPRangePath</code> instance.
 */
- (instancetype)initWithRange:(NSRange)aRange;


/*!
    @method     initWithLocation:lenght:
    @abstract   Initializes a newly created range path with the specified location
                and length.
 
    @discussion The last index in the <code>location</code> addresses the first
                item that is actually selected.
 
    @param      location
                The location of the first element that should be addressed by
                this range path.
 
    @param      length
                The number of elements to be addressed by this range path.
 
    @return     A <code>MPRangePath</code> instance.
 */
- (instancetype)initWithLocation:(NSIndexPath *)location
                          length:(NSUInteger)length; /* designated initializer */


/*!
    @method     rangePath
    @abstract   Allocates and initializes an empty <code>NSRangePath</code>
                instance.
 
    @discussion An empty range path's location has <code>0</code> indexes and a
                length of <code>0</code>.

    @return     A newly created <code>MPRangePath</code> instance.
 */
+ (instancetype)rangePath;


/*!
    @method     rangePathWithRange:
    @abstract   Allocates a new <code>MPRangePath</code> instance and initializes
                it with the specified location and length.
 
    @discussion The location of <code>aRange</code> is translated into an index
                path for the range path.
 
    @param      aRange
                The range to be converted into a range path.
 
    @return     A newly created <code>MPRangePath</code> instance.
 */
+ (instancetype)rangePathWithRange:(NSRange)aRange;


/*!
    @method     rangePathWithLocation:length:
    @abstract   Allocates a new <code>MPRangePath</code> instance and initializes
                it with the specified location and length.

    @param      location
                The location of the first element that should be addressed by the
                range path.
 
    @param      length
                The number of elements that should be addressed by the range
                path.
 
    @return     A newly created <code>MPRangePath</code> instance.
 */
+ (instancetype)rangePathWithLocation:(NSIndexPath *)location
                           length:(NSUInteger)length;


#pragma mark Properties
/*!
 @methodgroup Properties
 */


/*!
    @property   location
    @abstract   The location of the first element addressed by the receiver.
 */
@property (readonly, nonatomic, strong) NSIndexPath *location;


/*!
    @property   length
    @abstract   The number of elements addressed by the receiver. The element
                addressed by the last index of the location property plus the
                length of the receiver is <b>not</b> considered inside of the
                range path.
 */
@property (readonly, nonatomic) NSUInteger length;


/*!
    @method     maxRangePath
    @abstract   Similar to the <code>NSRange</code> function
                <code>NSMaxRange</code> this method returns the first index after
                the receiving <code>NSRangePath</code>.
 
    @return     The first index after the receiving <code>NSRangePath</code>.
 */
- (NSIndexPath *)maxRangePath;


/*!
    @method     rangeAtLastIndex
    @abstract   Returns a <code>NSRange</code> constructed from the last index of
                the receiver's location and the receiver's length.
 
    @return     The range identifying the elements at the last index in the
                receiver's index path.
 */
- (NSRange)rangeAtLastIndex;


#pragma mark Working With Ranges
/*!
 @methodgroup Working With Ranges
 */


/*!
    @method     containsLocation:
    @abstract   Checks wether the range path addressed by the receiver includes
                <code>location</code>.
 
    @discussion The index path is considered inside the receiver if the indexes
                in the receiver's <code>location</code> property are equal to the
                respective indexes index in <code>location</code>. For the last
                position of the last index of the receiver's
                <code>location</code> it is also valid if the respective index is
                inside the range at the last index.
 
    @param      location
                The index path to check wether it is contained in the receiver.
 
    @return     <code>YES</code> if the range path addressed by the receiver also
                contains <code>location,</code> <code>NO</code> otherwise.
 */
- (BOOL)containsLocation:(NSIndexPath *)location;


/*!
    @method     containsRangePath:
    @abstract   Checks wether the receiver completely contains
                <code>aRangePath</code>.
 
    @discussion A range path is contained by another range path if either the
                receiver's range at its last index contains the index at the
                respective location of the location path of
                <code>aRangePath</code> or (if the locations are of the same
                length) the receiver's range at its last index contains the last
                index's range of <code>aRangePath</code>.
 
    @param      aRangePath
                The range path to check wether it is contained in the receiver.
 
    @return     <code>YES</code> if the range path addressed by the receiver also
                includes <code>aRangePath,</code> <code>NO</code> otherwise.
 */
- (BOOL)containsRangePath:(MPRangePath *)aRangePath;


/*!
    @method     isEqualToRangePath:
    @abstract   Checks wether the receiver and <code>aRangePath</code> are equal.
 
    @discussion If you know that you are comparing two range paths (that are not
                <code>nil</code>) you should prefer this method over
                <code>isEqual:</code> because it is more performant.
 
    @param      aRangePath
                The range path to check for equality. If this parameter is
                <code>nil</code> this method may raise an exception.
 
    @return     <code>YES</code> if the receiver is equal to
                <code>aRangePath</code>, <code>NO</code> otherwise.
 */
- (BOOL)isEqualToRangePath:(MPRangePath *)aRangePath;

@end



@interface MPExpression (MPRangeExtension)

/*!
    @method     subexpressionWithRangePath:
    @abstract   Creates a new expression with the symbols in the specified range
                path.
 
    @discussion The elements in the newly created expression are copied to the
                new exoression. The range path is specified in the length
                reference frame.
 
                If the specified range exceeds the receiver's bounds a
                <code>NSRangeException</code> is raised.
 
    @param      aRangePath
                The range path from which to create the new expression.
 
    @return     A new expression.
 */
- (MPExpression *)subexpressionWithRangePath:(MPRangePath *)aRangePath
                              referenceFrame:(MPReferenceFrame)referenceFrame;


/*!
    @method     replaceItemsInRangePath:referenceFrame:withElements:
    @abstract   Replaces the items in the specified range path with the contents
                of <code>elements</code>.
 
    @discussion All objects in the <code>elements</code> array must conform to
                the <code>@link
                //apple_ref/occ/intf/MPExpressionElement@/link</code> protocol.
                If one or more objects do not conform to the protocol a
                <code>@link
                //apple_ref/c/data/MPIllegalElementException@/link</code> is
                raised.
 
    @param      rangePath
                The range path to be replaced. The location of the range path
                (except for the last index) is expressed in the element reference
                frame. The range of the range path is expressed in the specified
                <code>referenceFrame</code>.
 
    @param      referenceFrame
                The reference frame to use. This only applies to the range at the
                last index of the range path. The path of the range path is
                always expressed in the element reference frame.
 
    @param      elements
                The elements replacing the ones in the specified range path.
 */
- (void)replaceItemsInRangePath:(MPRangePath *)rangePath
                 referenceFrame:(MPReferenceFrame)referenceFrame
                   withElements:(NSArray *)elements;

@end