296 lines
9.1 KiB
Objective-C
296 lines
9.1 KiB
Objective-C
//
|
|
// MPRange.h
|
|
// MathPad
|
|
//
|
|
// Created by Kim Wittenburg on 18.04.14.
|
|
// Copyright (c) 2014 Kim Wittenburg. All rights reserved.
|
|
//
|
|
|
|
#import "MPExpression.h"
|
|
|
|
|
|
|
|
/// Convenience Constructor Macro
|
|
#define MPMakeRangePath(loc, len) [MPRangePath rangePathWithLocation:(loc) length:(len)]
|
|
|
|
|
|
@class MPRangePath, MPExpression;
|
|
|
|
|
|
/*!
|
|
@class MPRangePath
|
|
@brief @c MPRangePath is like @c NSRange but with an @c NSIndexPath as
|
|
location.
|
|
|
|
@discussion Range paths are intended to address a range (as defined by @c
|
|
NSRange) that resides in a tree structure. Thus the @c location
|
|
property of a range path is a @c NSIndexPath.
|
|
|
|
|
|
@c MPRangePath instances are immutable.
|
|
*/
|
|
@interface MPRangePath : NSObject <NSCopying, NSCoding>
|
|
|
|
|
|
#pragma mark Creation Methods
|
|
/*!
|
|
@methodgroup Creation Methods
|
|
*/
|
|
|
|
|
|
/*!
|
|
@method init
|
|
@brief 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 @c 0.
|
|
|
|
@return A @c MPRangePath instance.
|
|
*/
|
|
- (instancetype)init;
|
|
|
|
|
|
/*!
|
|
@method initWithRange:
|
|
@brief Initializes a newly created range path with the specified range.
|
|
|
|
@discussion This method is a convenience initializer to convert from a @c
|
|
NSRange to a @c MPRangePath. The location of @c aRange is
|
|
translated into a location for the range path.
|
|
|
|
@param aRange
|
|
The range to be converted into a @c MPRangePath.
|
|
|
|
@return A @c MPRangePath instance.
|
|
*/
|
|
- (instancetype)initWithRange:(NSRange)aRange;
|
|
|
|
|
|
/*!
|
|
@method initWithLocation:lenght:
|
|
@brief Initializes a newly created range path with the specified location
|
|
and length.
|
|
|
|
@discussion The last index in the @c location should address 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 @c MPRangePath instance.
|
|
*/
|
|
- (instancetype)initWithLocation:(NSIndexPath *)location
|
|
length:(NSUInteger)length; /* designated initializer */
|
|
|
|
|
|
/*!
|
|
@method rangePath
|
|
@brief Allocates and initializes an empty @c NSRangePath instance.
|
|
|
|
@discussion An empty range path's location has @c 0 indexes and a length of
|
|
@c 0.
|
|
|
|
@return A newly created @c MPRangePath instance.
|
|
*/
|
|
+ (instancetype)rangePath;
|
|
|
|
|
|
/*!
|
|
@method rangePathWithRange:
|
|
@brief Allocates a new @c MPRangePath instance and initializes it with
|
|
the specified location and length.
|
|
|
|
@discussion The location of @c aRange 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 @c MPRangePath instance.
|
|
*/
|
|
+ (instancetype)rangePathWithRange:(NSRange)aRange;
|
|
|
|
|
|
/*!
|
|
@method rangePathWithLocation:length:
|
|
@brief Allocates a new @c MPRangePath 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 @c MPRangePath instance.
|
|
*/
|
|
+ (instancetype)rangePathWithLocation:(NSIndexPath *)location
|
|
length:(NSUInteger)length;
|
|
|
|
|
|
#pragma mark Properties
|
|
/*!
|
|
@methodgroup Properties
|
|
*/
|
|
|
|
|
|
/*!
|
|
@property location
|
|
@brief The location of the first element addressed by the receiver.
|
|
*/
|
|
@property (readonly, nonatomic, strong) NSIndexPath *location;
|
|
|
|
|
|
/*!
|
|
@property length
|
|
@brief 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 NOT considered inside of the range
|
|
path.
|
|
*/
|
|
@property (readonly, nonatomic) NSUInteger length;
|
|
|
|
|
|
/*!
|
|
@method maxRangePath
|
|
@brief Similar to the @c NSRange method @c NSMaxRange this method
|
|
returns the first index after the receiving @c NSRangePath.
|
|
|
|
@return The first index after the receiving @c NSRangePath.
|
|
*/
|
|
- (NSIndexPath *)maxRangePath;
|
|
|
|
|
|
/*!
|
|
@method rangeAtLastIndex
|
|
@brief Returns a @c NSRange 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:
|
|
@brief Checks wether the range path addressed by the receiver includes
|
|
@c location.
|
|
|
|
@discussion The index path is considered inside the receiver if the indexes
|
|
in the receiver's @c location property are equal to the
|
|
respective indexes index in @c location. For the last position of
|
|
the last index of the receiver's @c location 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 @c YES if the range path addressed by the receiver also contains
|
|
@c location, @c NO otherwise.
|
|
*/
|
|
- (BOOL)containsLocation:(NSIndexPath *)location;
|
|
|
|
|
|
/*!
|
|
@method containsRangePath:
|
|
@brief Checks wether the receiver completely contains @c aRangePath.
|
|
|
|
@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 @c aRangePath or (if
|
|
the locations are of the same length) the receiver's range at its
|
|
last index contains the last index's range of @c aRangePath.
|
|
|
|
@param aRangePath
|
|
The range path to check wether it is contained in the receiver.
|
|
|
|
@return @c YES if the range path addressed by the receiver also includes
|
|
@c aRangePath, @c NO otherwise.
|
|
*/
|
|
- (BOOL)containsRangePath:(MPRangePath *)aRangePath;
|
|
|
|
|
|
/*!
|
|
@method isEqualToRangePath:
|
|
@brief Checks wether the receiver and @c aRangePath are equal.
|
|
|
|
@discussion If you know that you are comparing two range paths (that are not
|
|
@c nil) you should use this method over @c -isEqual: because it
|
|
is more performant.
|
|
|
|
@param aRangePath
|
|
The range path to check for equality. If this parameter is @c nil
|
|
this method may raise an exception.
|
|
|
|
@return @c YES if the receiver is equal to @c aRangePath, @c NO
|
|
otherwise.
|
|
*/
|
|
- (BOOL)isEqualToRangePath:(MPRangePath *)aRangePath;
|
|
|
|
@end
|
|
|
|
|
|
|
|
@interface MPExpression (MPRangeExtension)
|
|
|
|
|
|
/*!
|
|
@method subexpressionWithRangePath:
|
|
@brief 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 @c
|
|
NSRangeException 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:
|
|
@brief Replaces the items in the specified range path with the contents
|
|
of @c elements.
|
|
|
|
@discussion All objects in the @c elements array must conform to the @c
|
|
MPExpressionElement protocol. If one or more objects do not
|
|
conform to the protocol a @c MPIllegalElementException will be
|
|
raised.
|
|
|
|
@param rangePath
|
|
The range path to be replaced. The path of the range path is
|
|
expressed in the element reference frame. The range of the range
|
|
path is expressed in the specified @c referenceFrame.
|
|
|
|
@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.
|
|
*/
|
|
- (void)replaceItemsInRangePath:(MPRangePath *)rangePath
|
|
referenceFrame:(MPReferenceFrame)referenceFrame
|
|
withElements:(NSArray *)elements;
|
|
|
|
@end
|