Added Documentation
This commit is contained in:
Kim Wittenburg
@@ -9,8 +9,30 @@
|
||||
#import "MPExpression.h"
|
||||
|
||||
|
||||
/*!
|
||||
@header
|
||||
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.
|
||||
*/
|
||||
|
||||
/// Convenience Constructor Macro
|
||||
|
||||
/*!
|
||||
@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)]
|
||||
|
||||
|
||||
@@ -19,19 +41,13 @@
|
||||
|
||||
/*!
|
||||
@class MPRangePath
|
||||
@brief @c MPRangePath is like @c NSRange but with an @c NSIndexPath as
|
||||
location.
|
||||
@abstract A <code>MPRangePath</code> instance identifies a range of
|
||||
subsequent nodes in a tree structure.
|
||||
|
||||
@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.
|
||||
@discussion <code>MPRangePath</code> instances are immutable.
|
||||
*/
|
||||
@interface MPRangePath : NSObject <NSCopying, NSCoding>
|
||||
|
||||
|
||||
#pragma mark Creation Methods
|
||||
/*!
|
||||
@methodgroup Creation Methods
|
||||
@@ -40,39 +56,40 @@
|
||||
|
||||
/*!
|
||||
@method init
|
||||
@brief Initializes an empty range path.
|
||||
@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 @c 0.
|
||||
@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 @c MPRangePath instance.
|
||||
@return A new <code>MPRangePath</code> instance.
|
||||
*/
|
||||
- (instancetype)init;
|
||||
|
||||
|
||||
/*!
|
||||
@method initWithRange:
|
||||
@brief Initializes a newly created range path with the specified range.
|
||||
@abstract 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.
|
||||
@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 @c MPRangePath.
|
||||
The range to be converted into a <code>MPRangePath</code>.
|
||||
|
||||
@return A @c MPRangePath instance.
|
||||
@return A <code>MPRangePath</code> instance.
|
||||
*/
|
||||
- (instancetype)initWithRange:(NSRange)aRange;
|
||||
|
||||
|
||||
/*!
|
||||
@method initWithLocation:lenght:
|
||||
@brief Initializes a newly created range path with the specified location
|
||||
@abstract 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.
|
||||
@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
|
||||
@@ -81,7 +98,7 @@
|
||||
@param length
|
||||
The number of elements to be addressed by this range path.
|
||||
|
||||
@return A @c MPRangePath instance.
|
||||
@return A <code>MPRangePath</code> instance.
|
||||
*/
|
||||
- (instancetype)initWithLocation:(NSIndexPath *)location
|
||||
length:(NSUInteger)length; /* designated initializer */
|
||||
@@ -89,36 +106,37 @@
|
||||
|
||||
/*!
|
||||
@method rangePath
|
||||
@brief Allocates and initializes an empty @c NSRangePath instance.
|
||||
@abstract Allocates and initializes an empty <code>NSRangePath</code>
|
||||
instance.
|
||||
|
||||
@discussion An empty range path's location has @c 0 indexes and a length of
|
||||
@c 0.
|
||||
@discussion An empty range path's location has <code>0</code> indexes and a
|
||||
length of <code>0</code>.
|
||||
|
||||
@return A newly created @c MPRangePath instance.
|
||||
@return A newly created <code>MPRangePath</code> instance.
|
||||
*/
|
||||
+ (instancetype)rangePath;
|
||||
|
||||
|
||||
/*!
|
||||
@method rangePathWithRange:
|
||||
@brief Allocates a new @c MPRangePath instance and initializes it with
|
||||
the specified location and length.
|
||||
@abstract Allocates a new <code>MPRangePath</code> 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.
|
||||
@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 @c MPRangePath instance.
|
||||
@return A newly created <code>MPRangePath</code> instance.
|
||||
*/
|
||||
+ (instancetype)rangePathWithRange:(NSRange)aRange;
|
||||
|
||||
|
||||
/*!
|
||||
@method rangePathWithLocation:length:
|
||||
@brief Allocates a new @c MPRangePath instance and initializes it with
|
||||
the specified location and 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
|
||||
@@ -128,7 +146,7 @@
|
||||
The number of elements that should be addressed by the range
|
||||
path.
|
||||
|
||||
@return A newly created @c MPRangePath instance.
|
||||
@return A newly created <code>MPRangePath</code> instance.
|
||||
*/
|
||||
+ (instancetype)rangePathWithLocation:(NSIndexPath *)location
|
||||
length:(NSUInteger)length;
|
||||
@@ -142,35 +160,36 @@
|
||||
|
||||
/*!
|
||||
@property location
|
||||
@brief The location of the first element addressed by the receiver.
|
||||
@abstract 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
|
||||
@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 NOT considered inside of the range
|
||||
path.
|
||||
length of the receiver is <b>not</b> 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.
|
||||
@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 @c NSRangePath.
|
||||
@return The first index after the receiving <code>NSRangePath</code>.
|
||||
*/
|
||||
- (NSIndexPath *)maxRangePath;
|
||||
|
||||
|
||||
/*!
|
||||
@method rangeAtLastIndex
|
||||
@brief Returns a @c NSRange constructed from the last index of the
|
||||
receiver's location and the receiver's length.
|
||||
@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.
|
||||
@@ -186,57 +205,60 @@
|
||||
|
||||
/*!
|
||||
@method containsLocation:
|
||||
@brief Checks wether the range path addressed by the receiver includes
|
||||
@c location.
|
||||
@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 @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.
|
||||
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 @c YES if the range path addressed by the receiver also contains
|
||||
@c location, @c NO otherwise.
|
||||
@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:
|
||||
@brief Checks wether the receiver completely contains @c aRangePath.
|
||||
@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 @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.
|
||||
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 @c YES if the range path addressed by the receiver also includes
|
||||
@c aRangePath, @c NO otherwise.
|
||||
@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:
|
||||
@brief Checks wether the receiver and @c aRangePath are equal.
|
||||
@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
|
||||
@c nil) you should use this method over @c -isEqual: because it
|
||||
is more performant.
|
||||
<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 @c nil
|
||||
this method may raise an exception.
|
||||
The range path to check for equality. If this parameter is
|
||||
<code>nil</code> this method may raise an exception.
|
||||
|
||||
@return @c YES if the receiver is equal to @c aRangePath, @c NO
|
||||
otherwise.
|
||||
@return <code>YES</code> if the receiver is equal to
|
||||
<code>aRangePath</code>, <code>NO</code> otherwise.
|
||||
*/
|
||||
- (BOOL)isEqualToRangePath:(MPRangePath *)aRangePath;
|
||||
|
||||
@@ -249,15 +271,15 @@
|
||||
|
||||
/*!
|
||||
@method subexpressionWithRangePath:
|
||||
@brief Creates a new expression with the symbols in the specified range
|
||||
@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 @c
|
||||
NSRangeException is raised.
|
||||
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.
|
||||
@@ -270,23 +292,30 @@
|
||||
|
||||
/*!
|
||||
@method replaceItemsInRangePath:referenceFrame:withElements:
|
||||
@brief Replaces the items in the specified range path with the contents
|
||||
of @c elements.
|
||||
@abstract Replaces the items in the specified range path with the contents
|
||||
of <code>elements</code>.
|
||||
|
||||
@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
|
||||
@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 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.
|
||||
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
|
||||
|
||||
Reference in New Issue
Block a user