841 lines
29 KiB
Objective-C
841 lines
29 KiB
Objective-C
//
|
|
// MPExpression.h
|
|
// MathPad
|
|
//
|
|
// Created by Kim Wittenburg on 10.08.14.
|
|
// Copyright (c) 2014 Kim Wittenburg. All rights reserved.
|
|
//
|
|
|
|
|
|
|
|
/*!
|
|
@const MPIllegalElementException
|
|
@brief Name for an exception that is raised if an invalid element is
|
|
added to an expression.
|
|
|
|
@discussion This exception may be raised during initialization of an
|
|
expression or when the expression is mutated. This exception
|
|
always contains the @c MPIllegalElementExceptionElementKey key in
|
|
its @c userInfo dictionary.
|
|
*/
|
|
FOUNDATION_EXPORT NSString *const MPIllegalElementException;
|
|
|
|
|
|
/*!
|
|
@const MPIllegalElementExceptionElementKey
|
|
@brief Predefined key for the invalid element that caused an exception
|
|
to be raised.
|
|
|
|
@discussion The invalid element can be of any type.
|
|
*/
|
|
FOUNDATION_EXPORT NSString *const MPIllegalElementExceptionElementKey;
|
|
|
|
|
|
/*!
|
|
@typedef MPReferenceFrame
|
|
@brief A reference frame describes what an @em item in an expression is.
|
|
|
|
@discussion Reference frames have to be passed in multiple methods of the @c
|
|
MPExpression class. You can convert between reference frames
|
|
using the following methods:
|
|
<pre>
|
|
@textblock
|
|
- convertIndexFromReferenceFrame:toReferenceFrame:
|
|
- convertIndexFromReferenceFrame:toReferenceFrame:offset:
|
|
@/textblock
|
|
</pre>
|
|
|
|
There are three different types of items (reference frames):
|
|
symbols, tokens and elements. A symbol is the smalles possible
|
|
unit in an expression. Thus a token consists of one or more
|
|
symbols. Similarly an element consists of one or more tokens.
|
|
|
|
@constant MPElementReferenceFrame
|
|
Specifies that items should be interpreted as elements. An
|
|
element is either a @c NSString object or a @c MPFunction object.
|
|
|
|
@constant MPSymbolReferenceFrame
|
|
Specifies that items should be interpreted as symbols. A symbol
|
|
can be a single character (represented by the @c NSString class)
|
|
or a @c MPFunction object.
|
|
|
|
@constant MPTokenReferenceFrame
|
|
Specifies that items should be interpreted as tokens. A token is
|
|
a logical unit of content in an expression. This can be a single
|
|
character (e.g. '+'), an arbitrary number of characters (e.g. a
|
|
number) or a @c MPFunction object.
|
|
|
|
All tokens conform to the @c MPToken protocol.
|
|
*/
|
|
typedef NS_ENUM(NSUInteger, MPReferenceFrame) {
|
|
MPElementReferenceFrame,
|
|
MPSymbolReferenceFrame,
|
|
MPTokenReferenceFrame
|
|
};
|
|
|
|
|
|
|
|
@class MPExpression, MPFunction, MPRangePath, MPParsedExpression;
|
|
@protocol MPExpressionElement, MPToken;
|
|
|
|
|
|
/*!
|
|
@class MPExpression
|
|
@brief An @c MPExpression object is the base object for any mathematical
|
|
expression.
|
|
|
|
@discussion Every expression consists of string elements (represented by the
|
|
@c NSString class) and function elements (represented by the @c
|
|
MPFunction class). Functions likewise can have expressions as
|
|
elements (also called <i>children</i> in this context). Both
|
|
expressions and functions are mutable. Through this organization
|
|
expression are organized in a tree-like structure called the
|
|
'expression tree'.
|
|
|
|
An expression can evaluate itself giving you either a
|
|
result or possibly an error if the expression was not constructed
|
|
correctly or could not be evaluated.
|
|
*/
|
|
@interface MPExpression : NSObject <NSCopying, NSCoding>
|
|
|
|
|
|
#pragma mark Creation Methods
|
|
/*!
|
|
@methodgroup Creation Methods
|
|
*/
|
|
|
|
|
|
/*!
|
|
@method init
|
|
@brief Initlializes a newly created expression.
|
|
|
|
@discussion This method is a convenience initializer to initialize an
|
|
expression with @c 0 elements.
|
|
|
|
@return An expression.
|
|
*/
|
|
- (instancetype)init;
|
|
|
|
|
|
/*!
|
|
@method initWithElement:
|
|
@brief Initializes a newly created expression with @c element.
|
|
|
|
@discussion This method is a convenience initializer to initialize an
|
|
expression with a single element.
|
|
|
|
@param element
|
|
The element to be added to the expression. The @c element will be
|
|
copied.
|
|
|
|
@return An expression initialized with @c element.
|
|
*/
|
|
- (instancetype)initWithElement:(id<MPExpressionElement>)element;
|
|
|
|
|
|
/*!
|
|
@method initWithElements:
|
|
@brief Initializes a newly created expression with the specified
|
|
elements.
|
|
|
|
@discussion All elements must conform to the @c MPExpressionElement protocol.
|
|
If one or more objects do not conform to that protocol an @c
|
|
MPIllegalElementException is raised.
|
|
|
|
This method is the designated initializer for the @c MPExpression
|
|
class.
|
|
|
|
@param elements
|
|
The elements that should be added to the expression. Every
|
|
element must conform to the @c MPExpressionElement protocol. Each
|
|
element is copied and the copy is then added to the expression.
|
|
The object in the @c elements array is not modified.
|
|
|
|
@return An expression containing @c elements.
|
|
*/
|
|
- (instancetype)initWithElements:(NSArray *)elements; /* designated initializer */
|
|
|
|
|
|
#pragma mark Querying Expressions
|
|
/*!
|
|
@methodgroup Querying Expressions
|
|
*/
|
|
|
|
|
|
/*!
|
|
@property parent
|
|
@brief The receiver's parent.
|
|
|
|
@discussion Expressions are organized in a tree-like structure. Through this
|
|
property an expression's containing function can be accessed.
|
|
@warning You should never set this property manually. If you are
|
|
implementing a custom subclass of @c MPFunction use the @c
|
|
MPFunctionAccessorImplementation macro.
|
|
|
|
@return The parent of the receiver or @c nil if the receiver is the root
|
|
expression.
|
|
*/
|
|
@property (nonatomic, weak) MPFunction *parent;
|
|
|
|
|
|
/*!
|
|
@method rootExpression
|
|
@brief Returns the root expression from the receiver's expression tree.
|
|
|
|
@discussion The root expression is the ultimate parent of all expressions and
|
|
functions in the expression tree. A root expression does not have
|
|
a parent.
|
|
|
|
@return The root expression from the receiver's expression tree.
|
|
*/
|
|
- (MPExpression *)rootExpression;
|
|
|
|
|
|
/*!
|
|
@method indexPath
|
|
@brief Returns the index path of the receiver in the expression tree.
|
|
|
|
@discussion The index path is calculated by going up the expression tree
|
|
collecting the respective index of the receiver. The indexes are
|
|
expressed in the element reference frame. If any of the indexes
|
|
exceed the respective receiver's bounds a @c NSRangeException is
|
|
raised.
|
|
|
|
@return The index path of the receiver in the expression tree.
|
|
*/
|
|
- (NSIndexPath *)indexPath;
|
|
|
|
|
|
/*!
|
|
@method countItemsInReferenceFrame:
|
|
@brief Returns the number of items in the receiver in the respective
|
|
reference frame.
|
|
|
|
@param referenceFrame
|
|
The reference frame that should be used to count the items.
|
|
|
|
@return The current number of items in the receiver counted in the
|
|
specified reference frame.
|
|
*/
|
|
- (NSUInteger)countItemsInReferenceFrame:(MPReferenceFrame)referenceFrame;
|
|
|
|
|
|
/*!
|
|
@method itemAtIndex:referenceFrame:
|
|
@brief Returns the item at @c anIndex.
|
|
|
|
@discussion The item is not copied before it is returned. So be aware that
|
|
if you mutate a @c MPFunction object returned from this function
|
|
the changes will be reflected in the receiver.
|
|
|
|
@param anIndex
|
|
The index of the item. If the index is greater than the number of
|
|
items for the respective reference frame an @c NSRangeException
|
|
is raised.
|
|
|
|
@param referenceFrame
|
|
The reference frame that should be used to identify the item at
|
|
@c anIndex.
|
|
|
|
@return The item at @c anIndex.
|
|
*/
|
|
- (id)itemAtIndex:(NSUInteger)anIndex
|
|
referenceFrame:(MPReferenceFrame)referenceFrame;
|
|
|
|
|
|
/*!
|
|
@method elementAtIndex:referenceFrame:
|
|
@brief Returns the element at the specified index.
|
|
|
|
@discussion An element is either a string or a function. If @c anIndex
|
|
specifies a position inside a string the complete string element
|
|
is returned.
|
|
|
|
This method does not return any item in any reference frame but
|
|
only complete elements. Use @c -itemAtIndex:referenceFrame: for
|
|
that purpose.
|
|
|
|
@param anIndex
|
|
The index of the element.
|
|
|
|
@param referenceFrame
|
|
The reference frame @c anIndex is specified in.
|
|
|
|
@return The item at @c anIndex.
|
|
*/
|
|
- (id<MPExpressionElement>)elementAtIndex:(NSUInteger)anIndex
|
|
referenceFrame:(MPReferenceFrame)referenceFrame;
|
|
|
|
/*!
|
|
@method indexOfElement:
|
|
@brief Returns the index of @c element or @c NSNotFound if it was not
|
|
found.
|
|
|
|
@param element
|
|
The element to find.
|
|
|
|
@return The index of @c element expressed in the element reference frame.
|
|
*/
|
|
- (NSUInteger)indexOfElement:(id<MPExpressionElement>)element;
|
|
|
|
|
|
/*!
|
|
@method itemsInRange:referenceFrame:
|
|
@brief Returns an array of the items that are located in the specified
|
|
range.
|
|
|
|
@discussion The objects in the returned array are not copied before they are
|
|
returned. You should be aware of the fact that mutations to any
|
|
returned objects will be reflected in the receiver.
|
|
|
|
If the @c range exceeds the receiver's bounds an @c
|
|
NSRangeException is raised.
|
|
|
|
@param aRange
|
|
The requested range within the receiver's bounds.
|
|
|
|
@param referenceFrame
|
|
The referenceFrame @c aRange is expressed in.
|
|
|
|
@return An array of objects that conform to the @c MPExpressionElement
|
|
protocol (that is @c NSString objects and @c MPFunction objects).
|
|
The length of the returned array is equal to the length of the
|
|
specified range.
|
|
*/
|
|
- (NSArray *)itemsInRange:(NSRange)aRange
|
|
referenceFrame:(MPReferenceFrame)referenceFrame;
|
|
|
|
|
|
/*!
|
|
@method allItemsInReferenceFrame:
|
|
@brief Returns an array of all items in the receiver for the specified
|
|
reference frame.
|
|
|
|
@discussion The elements in the returned array are not copied before they are
|
|
returned so be aware that mutations to any of the returned
|
|
objects will be reflected in the receiver.
|
|
|
|
@return An array of all items in the receiver.
|
|
*/
|
|
- (NSArray *)allItemsInReferenceFrame:(MPReferenceFrame)referenceFrame;
|
|
|
|
|
|
/*!
|
|
@method elementAtIndexPath:
|
|
@brief Returns the element at the specified index path.
|
|
|
|
@discussion This method @em walks down the expression tree (including
|
|
functions) using the specified index path and finds the
|
|
corresponding element. The returned object can be an @c NSString,
|
|
a @c MPFunction or an @c MPExpression depending on the element @c
|
|
indexPath points to. If any of the indexes exceed the bounds of
|
|
the respective receiver an @c NSRangeException is raised.
|
|
|
|
If the index path does not contain any indexes the receiver
|
|
itself is returned.
|
|
|
|
@param indexPath
|
|
The index path the required object is located at. The indexes are
|
|
expressed in the element reference frame.
|
|
|
|
@return The element located at @c indexPath. The element is not copied
|
|
before it is returned. Be aware of the fact that any mutations
|
|
made to the returned object are reflected in the receiver.
|
|
*/
|
|
- (id)elementAtIndexPath:(NSIndexPath *)indexPath;
|
|
|
|
|
|
/*!
|
|
@method convertIndex:fromReferenceFrame:toReferenceFrame:
|
|
@brief Converts an index from one reference frame to another.
|
|
|
|
@discussion This method ignores any offsets into items the conversion between
|
|
reference frames can cause. If you are interested in the offset
|
|
use @c -convertIndex:fromReferenceFrame:toReferenceFrame:offset:
|
|
instead.
|
|
|
|
@param anIndex
|
|
The index to be converted.
|
|
|
|
@param fromReferenceFrame
|
|
The reference frame @c anIndex is specified in.
|
|
|
|
@param toReferenceFrame
|
|
The reference frame @c anIndex should be converted to.
|
|
|
|
@return An index specified in the @c toReferenceFrame. If @c anIndex
|
|
specifies a location inside an item in the @c toReferenceFrame
|
|
the index of the corresponding item is returned.
|
|
*/
|
|
- (NSUInteger)convertIndex:(NSUInteger)anIndex
|
|
fromReferenceFrame:(MPReferenceFrame)fromReferenceFrame
|
|
toReferenceFrame:(MPReferenceFrame)toReferenceFrame;
|
|
|
|
|
|
/*!
|
|
@method convertIndex:fromReferenceFrame:toReferenceFrame:offset:
|
|
@brief Converts an index from one reference frame to another.
|
|
|
|
@discussion If @c anIndex specifies a location inside an item in the @c
|
|
toReferenceFrame the index of the corresponding item is returned.
|
|
|
|
@param anIndex
|
|
The index to be converted.
|
|
|
|
@param fromReferenceFrame
|
|
The reference frame @c anIndex is specified in.
|
|
|
|
@param toReferenceFrame
|
|
The reference frame @c anIndex should be converted to.
|
|
|
|
@param offset
|
|
This output parameter will be set to the number of symbols that
|
|
are between the location specified by @c anIndex and the index
|
|
that is actually returned. The offset is specified in the symbol
|
|
reference frame. If you are not interested in the offset pass
|
|
@c NULL.
|
|
|
|
@return An index specified in the @c toReferenceFrame corresponding to
|
|
@c anIndex.
|
|
*/
|
|
- (NSUInteger)convertIndex:(NSUInteger)anIndex
|
|
fromReferenceFrame:(MPReferenceFrame)fromReferenceFrame
|
|
toReferenceFrame:(MPReferenceFrame)toReferenceFrame
|
|
offset:(out NSUInteger *)offset;
|
|
|
|
|
|
/*!
|
|
@method convertRange:fromReferenceFrame:toReferenceFrame:
|
|
@brief Converts a range from one reference frame to another.
|
|
|
|
@discussion This method just converts the location and target of the range
|
|
separately using @c
|
|
-convertIndex:fromReferenceFrame:toReferenceFrame:. This method
|
|
ensures that the returned range definitely includes all items
|
|
that were specified by @c aRange.
|
|
|
|
This method ignores the possibility that the returned range may
|
|
include more than @a aRange. If you need that information use
|
|
@c -convertRange:fromReferenceFrame:toReferenceFrame:leadingOffset:trailingOffset:.
|
|
|
|
@param aRange
|
|
The range to be converted.
|
|
|
|
@param fromReferenceFrame
|
|
The reference frame @c aRange is specified in.
|
|
|
|
@param toReferenceFrame
|
|
The reference frame @c aRange is to be converted to.
|
|
|
|
@return A range in the @c toReferenceFrame that includes the the items
|
|
specified by @c aRange.
|
|
*/
|
|
- (NSRange)convertRange:(NSRange)aRange
|
|
fromReferenceFrame:(MPReferenceFrame)fromReferenceFrame
|
|
toReferenceFrame:(MPReferenceFrame)toReferenceFrame;
|
|
|
|
|
|
/*!
|
|
@method convertRange:fromReferenceFrame:toReferenceFrame:leadingOffset:trailingOffset:
|
|
@brief Converts a range from one reference frame to another.
|
|
|
|
@discussion This method just converts the location and target of the range
|
|
separately using @c
|
|
-convertIndex:fromReferenceFrame:toReferenceFrame:. This method
|
|
ensures that the returned range definitely includes all items
|
|
that were specified by @c aRange.
|
|
|
|
@param aRange
|
|
The range to be converted.
|
|
|
|
@param fromReferenceFrame
|
|
The reference frame @c aRange is specified in.
|
|
|
|
@param toReferenceFrame
|
|
The reference frame @c aRange is to be converted to.
|
|
|
|
@param leadingOffset
|
|
The offset of the location of the returned range in respect to
|
|
the location of @c aRange.
|
|
|
|
@param trailingOffset
|
|
The offset of the last index in the range in respect to the last
|
|
index of @c aRange.
|
|
|
|
@return A range in the @c toReferenceFrame that includes the the items
|
|
specified by @c aRange.
|
|
*/
|
|
- (NSRange)convertRange:(NSRange)aRange
|
|
fromReferenceFrame:(MPReferenceFrame)fromReferenceFrame
|
|
toReferenceFrame:(MPReferenceFrame)toReferenceFrame
|
|
leadingOffset:(NSUInteger *)leadingOffset
|
|
trailingOffset:(NSUInteger *)trailingOffset;
|
|
|
|
|
|
#pragma mark Mutating Expressions
|
|
/*!
|
|
@methodgroup Mutating Expressions
|
|
*/
|
|
|
|
|
|
/*!
|
|
@method replaceItemsInRange:referenceFrame:withElements:
|
|
@brief Replaces the elements in the specified range with the contents of
|
|
the @c elements array.
|
|
|
|
@discussion This is the most primitive mutation method of @c MPExpression.
|
|
Every other mutating method utlimately must call this method.
|
|
|
|
After the receiver has been mutated the integrety of the receiver
|
|
is restored. That basically means that subsequent strings are
|
|
joined and empty strings removed. After restoring integrity the
|
|
receiver sends a @c
|
|
-changedElementsInIndexedRangePath:replacementLength: to
|
|
itself. For more information see the documentation on that
|
|
method.
|
|
|
|
@param aRange
|
|
The @c range of symbols (including functions) to replace.
|
|
|
|
@param referenceFrame
|
|
The reference frame @c aRange is specified in.
|
|
|
|
@param elements
|
|
The elements that should replace the symbols specified by @c
|
|
range.
|
|
*/
|
|
- (void)replaceItemsInRange:(NSRange)aRange
|
|
referenceFrame:(MPReferenceFrame)referenceFrame
|
|
withElements:(NSArray *)elements;
|
|
|
|
|
|
/*!
|
|
@method changedElementsInRangePath:replacementLength:
|
|
@brief Called after the receiver has been mutated.
|
|
|
|
@discussion This method does nothing more than notify it's parent that it has
|
|
been mutated at the receiver's index. If you need to know about
|
|
changes in an expression you should override this method instead
|
|
of @c -replaceSymbolsInRange:withElements: because this method
|
|
gives you information about the number of elements changed during
|
|
the mutation.
|
|
|
|
@param rangePath
|
|
The range path at which the receiver was changed starting at the
|
|
receiver. The range addressed by @c rangePath is expressed in the
|
|
element reference frame.
|
|
|
|
@param replacementLength
|
|
The number of elements replacing the elements specified by @c
|
|
rangePath (also specified in the element reference frame).
|
|
*/
|
|
- (void)changedElementsInRangePath:(MPRangePath *)rangePath
|
|
replacementLength:(NSUInteger)replacementLength;
|
|
|
|
|
|
/*!
|
|
@method subexpressionFromIndex:referenceFrame:
|
|
@brief Creates an expression from the items in the receiver from the
|
|
specified index to the end.
|
|
|
|
@discussion The items from the receiver are copied. Mutations to the returned
|
|
expression will not change the receiver.
|
|
|
|
@param from
|
|
The index from which to start constructing the subexpression.
|
|
|
|
@param referenceFrame
|
|
The reference frame @c from is specified in.
|
|
|
|
@return An expression containing the items from the specified index to
|
|
the end of the receiver.
|
|
*/
|
|
- (MPExpression *)subexpressionFromIndex:(NSUInteger)from
|
|
referenceFrame:(MPReferenceFrame)referenceFrame;
|
|
|
|
|
|
/*!
|
|
@method subexpressionToIndex:referenceFrame:
|
|
@brief Creates an expression from the items in the receiver from the
|
|
first item to the end.
|
|
|
|
@discussion The items from the receiver are copied. Mutations to the returned
|
|
expression will not change the receiver.
|
|
|
|
@param to
|
|
The index of the first element not to include in the newly
|
|
constructed subexpression.
|
|
|
|
@param referenceFrame
|
|
The reference frame @c to is specified in.
|
|
|
|
@return An expression containing the items from the first item to the one
|
|
at the specified index.
|
|
*/
|
|
- (MPExpression *)subexpressionToIndex:(NSUInteger)to
|
|
referenceFrame:(MPReferenceFrame)referenceFrame;
|
|
|
|
|
|
/*!
|
|
@method subexpressionWithRange:referenceFrame:
|
|
@brief Creates an expression from the items in the receiver within the
|
|
specified range.
|
|
|
|
@discussion The items from the receiver are copied. Mutations to the returned
|
|
expression will not change the receiver.
|
|
|
|
@param aRange
|
|
Specifies the items to be included in the newly created
|
|
subexpression.
|
|
|
|
@param referenceFrame
|
|
The reference frame @c aRange is specified in.
|
|
|
|
@return An expression containing the items in @c aRange.
|
|
*/
|
|
- (MPExpression *)subexpressionWithRange:(NSRange)aRange
|
|
referenceFrame:(MPReferenceFrame)referenceFrame;
|
|
|
|
|
|
#pragma mark Evaluating Expressions
|
|
/*!
|
|
@methodgroup Evaluating Expressions
|
|
*/
|
|
|
|
|
|
/*!
|
|
@method evaluateWitErrors:
|
|
@brief Evaluates the receiver.
|
|
|
|
@discussion This is a convenience method for evaluating an expression. If you
|
|
want more control over the evaluation process use @c -parse
|
|
instead.
|
|
|
|
@param errors
|
|
If the receiver (or any of its elements) contain syntax errors or
|
|
can not be evaluated this parameter is set to an appropriate
|
|
value. All items in the array are @c NSError instances. This
|
|
parameter is never set to an empty array.
|
|
Pass @c NULL if you are not interested in any errors that might
|
|
occur.
|
|
|
|
@return The result of the evaluation or @c nil of the receiver could not
|
|
be evaluated. In that case the @c error parameter is set to an
|
|
appropriate value.
|
|
*/
|
|
- (NSDecimalNumber *)evaluateWithErrors:(NSArray *__autoreleasing *)errors;
|
|
|
|
|
|
/*!
|
|
@method parse:
|
|
@brief Parses the receiver.
|
|
|
|
@discussion This is a convenience method that calls @c
|
|
-parseExpectingVariable:errors: with @c NO as the first argument.
|
|
|
|
@param errors
|
|
If the receiver (or any of its elements) contain syntax errors
|
|
this parameter is set to an appropriate value. All items in the
|
|
array are @c NSError instances. This parameter is never set to an
|
|
empty array.
|
|
Pass @c NULL if you are not interested in any errors that might
|
|
occur.
|
|
|
|
@return A @c MPParsedExpression object that represents the receiver and
|
|
can be evaluated or @c nil if an error occurs. In that case the
|
|
@c errors parameter is set to an array containing at least one
|
|
@c NSError instance.
|
|
*/
|
|
- (MPParsedExpression *)parse:(NSArray *__autoreleasing *)errors;
|
|
|
|
|
|
/*!
|
|
@method parseExpectingVariable:errors:
|
|
@brief Parses the receiver.
|
|
|
|
@param flag
|
|
If @c YES the receiver must (exept for whitespaces) begin with a
|
|
single letter followed by an equals sign. If it doesn't the
|
|
expression is considered invalid. Specify @c NO If the expression
|
|
should be evaluatable by itself.
|
|
|
|
@param errors
|
|
If the receiver (or any of its elements) contain syntax errors
|
|
this parameter is set to an appropriate value. All items in the
|
|
array are @c NSError instances. This parameter is never set to an
|
|
empty array.
|
|
Pass @c NULL if you are not interested in any errors that might
|
|
occur.
|
|
|
|
@return A @c MPParsedExpression object that represents the receiver and
|
|
can be evaluated or @c nil if an error occurs. In that case the
|
|
@c errors parameter is set to an array containing at least one
|
|
@c NSError instance.
|
|
*/
|
|
- (MPParsedExpression *)parseExpectingVariable:(BOOL)flag
|
|
errors:(NSArray *__autoreleasing *)errors;
|
|
|
|
@end
|
|
|
|
|
|
|
|
/*!
|
|
@category MPExpression (MPExpressionConvenience)
|
|
@brief This category defines convenience methods for the @c MPExpression
|
|
class.
|
|
|
|
@discussion All convenience methods are completely defined in terms of other
|
|
methods of the @c MPExpression class.
|
|
*/
|
|
@interface MPExpression (MPExpressionConvenience)
|
|
|
|
#pragma mark Querying Expressions
|
|
/*!
|
|
@methodgroup Querying Expressions
|
|
*/
|
|
|
|
|
|
/*!
|
|
@method countElements
|
|
@brief Returns the number of elements in the receiver.
|
|
|
|
@return The number of elements in the receiver expressed in the element
|
|
reference frame.
|
|
*/
|
|
- (NSUInteger)countElements;
|
|
|
|
|
|
/*!
|
|
@method countSymbols
|
|
@brief Returns the number of symbols in the receiver.
|
|
|
|
@return The number of symbols in the receiver expressed in the symbol
|
|
reference frame.
|
|
*/
|
|
- (NSUInteger)countSymbols;
|
|
|
|
|
|
/*!
|
|
@method countTokens
|
|
@brief Returns the number of tokens in the receiver.
|
|
|
|
@return The number of tokens in the receiver expressed in the token
|
|
reference frame.
|
|
*/
|
|
- (NSUInteger)countTokens;
|
|
|
|
|
|
/*!
|
|
@method elementAtIndex:
|
|
@brief Returns the element at the specified index.
|
|
|
|
@param anIndex
|
|
The index of the element specified in the element reference
|
|
frame.
|
|
|
|
@return The element at @c anIndex.
|
|
*/
|
|
- (id<MPExpressionElement>)elementAtIndex:(NSUInteger)anIndex;
|
|
|
|
|
|
/*!
|
|
@method symbolAtIndex:
|
|
@brief Returns the symbol at the specified index.
|
|
|
|
@param anIndex
|
|
The index of the symbol specified in the symbol reference frame.
|
|
|
|
@return The symbol at @c anIndex.
|
|
*/
|
|
- (id<MPExpressionElement>)symbolAtIndex:(NSUInteger)anIndex;
|
|
|
|
|
|
/*!
|
|
@method tokenAtIndex:
|
|
@brief Returns the token at the specified index.
|
|
|
|
@param anIndex
|
|
The index of the token specified in the token reference frame.
|
|
|
|
@return The token at @c anIndex.
|
|
*/
|
|
- (id<MPToken>)tokenAtIndex:(NSUInteger)anIndex;
|
|
|
|
|
|
#pragma mark Mutating Expressions
|
|
/*!
|
|
@methodgroup Mutating Expressions
|
|
*/
|
|
|
|
|
|
/*!
|
|
@method appendElement:
|
|
@brief Appends @c anElement to the receiver.
|
|
|
|
@param anElement
|
|
The element to append to the receiver.
|
|
*/
|
|
- (void)appendElement:(id<MPExpressionElement>)anElement;
|
|
|
|
|
|
/*!
|
|
@method appendElements:
|
|
@brief Appends the objects from @c elements to the receiver.
|
|
|
|
@param elements
|
|
The elements to append to the receiver.
|
|
*/
|
|
- (void)appendElements:(NSArray *)elements;
|
|
|
|
|
|
/*!
|
|
@method insertElement:atIndex:referenceFrame:
|
|
@brief Inserts @c anElement at the specified index.
|
|
|
|
@param anElement
|
|
The element to be inserted.
|
|
|
|
@param index
|
|
The index where to insert @c anElement.
|
|
|
|
@param referenceFrame
|
|
The reference frame @c index is specified in.
|
|
*/
|
|
- (void)insertElement:(id<MPExpressionElement>)anElement
|
|
atIndex:(NSUInteger)index
|
|
referenceFrame:(MPReferenceFrame)referenceFrame;
|
|
|
|
|
|
/*!
|
|
@method insertElements:atIndex:referenceFrame:
|
|
@brief Inserts @c elements at the specified index.
|
|
|
|
@param elements
|
|
The elements to be inserted.
|
|
|
|
@param index
|
|
The index where to insert @c elements.
|
|
|
|
@param referenceFrame
|
|
The reference frame @c index is specified in.
|
|
*/
|
|
- (void)insertElements:(NSArray *)elements
|
|
atIndex:(NSUInteger)index
|
|
referenceFrame:(MPReferenceFrame)referenceFrame;
|
|
|
|
|
|
/*!
|
|
@method deleteElementsInRange:
|
|
@brief Removes the elements specified by @c range from the receiver.
|
|
|
|
@param range
|
|
The range of items to remove from the receiver.
|
|
|
|
@param referenceFrame
|
|
The reference frame @c range is specified in.
|
|
*/
|
|
- (void)deleteElementsInRange:(NSRange)range
|
|
referenceFrame:(MPReferenceFrame)referenceFrame;
|
|
|
|
@end
|