Reorganized File Structure
Added Documentation
This commit is contained in:
Kim Wittenburg
910
MathKit/MPExpression.h
Normal file
910
MathKit/MPExpression.h
Normal file
@@ -0,0 +1,910 @@
|
||||
//
|
||||
// MPExpression.h
|
||||
// MathPad
|
||||
//
|
||||
// Created by Kim Wittenburg on 10.08.14.
|
||||
// Copyright (c) 2014 Kim Wittenburg. All rights reserved.
|
||||
//
|
||||
|
||||
|
||||
/*!
|
||||
@header
|
||||
The <code>MPExpression</code> class is used to represent a mathematical
|
||||
expression. It is used in the storage layer of the MathKit Expression System. An
|
||||
instance of the <code>MPExpression</code> class stores all contents related to
|
||||
an expression and can manipulate them. However it is not able to evaluate the
|
||||
represented expression by itself.
|
||||
|
||||
<h2>Structure of an Expression</h2>
|
||||
|
||||
Expressions consist of two types of elements: string elements and function
|
||||
elements. String elements are represented by the <code>NSString</code> class.
|
||||
In a valid expression string elements can only contain ASCII valid characters.
|
||||
(and some other special characters) that make sense in a mathematical context.
|
||||
Functions are represented by the <code>MPFunction</code> class. Functions
|
||||
represent everything beyond simple text (such as powers, parenthesis and roots).
|
||||
|
||||
An expression should be pictured as a sequence of symbols that can either be
|
||||
characters or functions. For the purposes of easier processing of expressions
|
||||
it is possible to access complete string or function elements. Also there is a
|
||||
third way of accessing an expression's contents: You can query individual tokens
|
||||
of an expression. Tokens represent logical units inside an expression. For more
|
||||
information on tokens see the <code>MPToken</code> class.
|
||||
|
||||
<h2>The Expression Tree</h2>
|
||||
Like expressions functions can likewise 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 <i>expression tree</i>. See <code>MPFunction</code> for
|
||||
details.
|
||||
|
||||
<h2>Terminology</h2>
|
||||
|
||||
When working with expressions note that there is a special terminology for an
|
||||
expression's contents:
|
||||
|
||||
<b>Element:</b><br />
|
||||
An element is either an instance of the <code>NSString</code> or <code>
|
||||
MPFunction</code> class. String elements can be multiple characters long. For
|
||||
example the expression <code>4+2²</code> consists of one string element
|
||||
(<code>"4+2"</code>) and one function element (the square function). All
|
||||
elements conform to the <code>MPExpressionElement</code> protocol.
|
||||
|
||||
<b>Token:</b><br />
|
||||
Tokens are logical units within an expression. For example the expression
|
||||
<code>4+2²</code> consists of 4 tokens: A number token (<code>4</code>), a plus
|
||||
sign token (<code>+</code>), another number (<code>2</code>) and a power token
|
||||
(the square function). All tokens conform to the <code>MPToken</code> protocol.
|
||||
|
||||
<b>Symbol:</b><br />
|
||||
Symbols are the smallest possible part of an expression. A symbol is either a
|
||||
single character or a single function. For example the expression
|
||||
<code>4+2²</code> consists of 4 symbols: The characters <code>"4"</code>,
|
||||
<code>"+"</code> and <code>"2"</code> and the square function.
|
||||
|
||||
<b>Item:</b></br />
|
||||
The term <i>item</i> is used to describe any of the previous. When the term
|
||||
<i>item</i> is used in the name of a function or method it necessary to specify
|
||||
what exactly an item is supposed to be. Usually this is done through reference
|
||||
frames.
|
||||
|
||||
<b>Reference Frame:</b><br />
|
||||
A reference frame is a way to specify what an <i>item</i> is supposed to mean in
|
||||
a specific context. It can either be an <i>element</i>, a <i>symbol</i> or a
|
||||
<i>token</i>. For more information about reference frames see
|
||||
<code>MPReferenceFrame</code>.
|
||||
|
||||
<b>Children:</b><br />
|
||||
Children are sub-elements of functions. The term <i>children</i> normally refers
|
||||
to any kind of elements in the context of the expression tree.
|
||||
|
||||
This terminology is consistent within the MathKit Expression System. Because
|
||||
symbols are the smalles possible unit of measurement elements and tokens both
|
||||
consist of one or more symbols. Similarly elements consist of one or more
|
||||
tokens. You can convert between different reference frames using one the
|
||||
following methods:
|
||||
<pre>
|
||||
@textblock
|
||||
- convertIndexFromReferenceFrame:toReferenceFrame:
|
||||
- convertIndexFromReferenceFrame:toReferenceFrame:offset:
|
||||
@/textblock
|
||||
</pre>
|
||||
|
||||
<h2>Evaluating Expressions</h2>
|
||||
A <code>MPExpression</code> instance can not evaluate itself. There are however
|
||||
the <code>-parse:</code> and
|
||||
<code>-parseExpectingVariableDefinition:errors:</code> methods. These parse and
|
||||
thereby convert a <code>MPExpression</code> instance into a
|
||||
<code>MPParsedExpression</code> instance that can be evaluated. For more
|
||||
information on evaluation see the <code>MPParsedExpression</code> and
|
||||
<code>MPTerm</code> class as well as the previously mentioned methods.
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
@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
|
||||
contains the invalid element in its <code>userInfo</code>
|
||||
dictionary. You can query it using the
|
||||
<code>MPIllegalElementExceptionElementKey</code> key.
|
||||
*/
|
||||
FOUNDATION_EXPORT NSString *const MPIllegalElementException;
|
||||
|
||||
|
||||
/*!
|
||||
@const MPIllegalElementExceptionElementKey
|
||||
@brief Predefined key for an invalid element that caused a
|
||||
<code>MPIllegalElementException</code> to be raised.
|
||||
|
||||
@discussion The invalid element can be of any type. Numbers and structs are
|
||||
wrapped in an <code>NSNumber</code> or <code>NSValue</code>
|
||||
instance respectively.
|
||||
*/
|
||||
FOUNDATION_EXPORT NSString *const MPIllegalElementExceptionElementKey;
|
||||
|
||||
|
||||
/*!
|
||||
@typedef MPReferenceFrame
|
||||
@brief A reference frame specifies the way an <i>item</i> is to be
|
||||
interpreted.
|
||||
|
||||
@constant MPElementReferenceFrame
|
||||
Specifies that items should be interpreted as elements.
|
||||
|
||||
@constant MPSymbolReferenceFrame
|
||||
Specifies that items should be interpreted as symbols.
|
||||
|
||||
@constant MPTokenReferenceFrame
|
||||
Specifies that items should be interpreted as tokens.
|
||||
*/
|
||||
typedef enum {
|
||||
MPElementReferenceFrame,
|
||||
MPSymbolReferenceFrame,
|
||||
MPTokenReferenceFrame
|
||||
} MPReferenceFrame;
|
||||
|
||||
|
||||
|
||||
@class MPExpression, MPFunction, MPRangePath, MPParsedExpression;
|
||||
@protocol MPExpressionElement, MPToken;
|
||||
|
||||
|
||||
/*!
|
||||
@class MPExpression
|
||||
@brief A <code>MPExpression</code> instance represents a mathematical
|
||||
expression.
|
||||
|
||||
@discussion Every expression consists of string elements (represented by the
|
||||
<code>NSString</code> class) and function elements (represented
|
||||
by the <code>MPFunction</code> class). Functions and expressions
|
||||
make up the expression tree.
|
||||
*/
|
||||
@interface MPExpression : NSObject <NSCopying, NSCoding>
|
||||
|
||||
|
||||
#pragma mark Creation Methods
|
||||
/*!
|
||||
@methodgroup Creation Methods
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
@method init
|
||||
@brief Initlializes a new expression.
|
||||
|
||||
@discussion This method is a convenience initializer to initialize an
|
||||
expression with <code>0</code> elements.
|
||||
|
||||
@return An empty expression.
|
||||
*/
|
||||
- (instancetype)init;
|
||||
|
||||
|
||||
/*!
|
||||
@method initWithElement:
|
||||
@brief Initializes a new expression with the specified
|
||||
<code>element</code>.
|
||||
|
||||
@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
|
||||
<code>element</code> will be copied.
|
||||
|
||||
@return An expression initialized with <code>element</code>.
|
||||
*/
|
||||
- (instancetype)initWithElement:(id<MPExpressionElement>)element;
|
||||
|
||||
|
||||
/*!
|
||||
@method initWithElements:
|
||||
@brief Initializes a new expression with the specified
|
||||
<code>elements</code>.
|
||||
|
||||
@discussion All elements must conform to the <code>MPExpressionElement</code>
|
||||
protocol. If one or more objects do not conform to that protocol
|
||||
a <code>MPIllegalElementException</code> is raised.
|
||||
|
||||
This method is the designated initializer for the
|
||||
<code>MPExpression</code> class.
|
||||
|
||||
@param elements
|
||||
The elements that should be added to the expression. Every
|
||||
element must conform to the <code>MPExpressionElement</code>
|
||||
protocol. Each element is copied and the copy is then added to
|
||||
the expression. The object in the <code>elements</code> array is
|
||||
not modified.
|
||||
|
||||
@return An expression containing <code>elements</code>.
|
||||
*/
|
||||
- (instancetype)initWithElements:(NSArray *)elements; /* designated initializer */
|
||||
|
||||
|
||||
#pragma mark Querying Expressions
|
||||
/*!
|
||||
@methodgroup Querying Expressions
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
@property parent
|
||||
@brief The receiver's parent.
|
||||
|
||||
@discussion The receiver's parent is the function in the expression tree that
|
||||
contains the receiver.
|
||||
@warning You should never set this property manually. If you are
|
||||
implementing a custom subclass of <code>MPFunction</code> use the
|
||||
<code>MPFunctionAccessorImplementation</code> macro.
|
||||
|
||||
@return The parent of the receiver or <code>nil</code> 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 contains the indexes (starting from the root
|
||||
expression of the receiver's expression tree) that lead to the
|
||||
receiver. The indexes are expressed in the element reference
|
||||
frame.
|
||||
|
||||
@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 specified
|
||||
<code>referenceFrame</code>.
|
||||
|
||||
@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 <code>referenceFrame</code>.
|
||||
*/
|
||||
- (NSUInteger)countItemsInReferenceFrame:(MPReferenceFrame)referenceFrame;
|
||||
|
||||
|
||||
/*!
|
||||
@method itemAtIndex:referenceFrame:
|
||||
@brief Returns the item at <code>anIndex</code>.
|
||||
|
||||
@discussion The item is not copied before it is returned. So be aware that
|
||||
if you mutate a <code>MPFunction</code> instance returned from
|
||||
this function the receiver's expression tree will be updated to
|
||||
reflect the change.
|
||||
|
||||
@param anIndex
|
||||
The index of the item. If the index is greater than the number of
|
||||
items for the respective reference frame a
|
||||
<code>NSRangeException</code> is raised.
|
||||
|
||||
@param referenceFrame
|
||||
The reference frame that should be used to identify the item at
|
||||
<code>anIndex</code>.
|
||||
|
||||
@return The item at <code>anIndex</code>.
|
||||
*/
|
||||
- (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
|
||||
<code>anIndex</code> identifies a position inside a string
|
||||
element the complete element is returned.
|
||||
|
||||
This method always returns elements. To query items in the
|
||||
specified reference frame use
|
||||
<code>-itemAtIndex:referenceFrame:</code>.
|
||||
|
||||
@param anIndex
|
||||
The index of the element.
|
||||
|
||||
@param referenceFrame
|
||||
The reference frame <code>anIndex</code> is specified in.
|
||||
|
||||
@return The element at <code>anIndex</code>.
|
||||
*/
|
||||
- (id<MPExpressionElement>)elementAtIndex:(NSUInteger)anIndex
|
||||
referenceFrame:(MPReferenceFrame)referenceFrame;
|
||||
|
||||
/*!
|
||||
@method indexOfElement:
|
||||
@brief Returns the index of <code>element</code> or
|
||||
<code>NSNotFound</code> if it was not found.
|
||||
|
||||
@param element
|
||||
The element to find.
|
||||
|
||||
@return The index of <code>element</code> 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 copied before they are
|
||||
returned.
|
||||
|
||||
If the <code>range</code> exceeds the receiver's bounds a
|
||||
<code>NSRangeException</code> is raised.
|
||||
|
||||
@param aRange
|
||||
The requested range within the receiver's bounds.
|
||||
|
||||
@param referenceFrame
|
||||
The referenceFrame <code>aRange</code> is expressed in.
|
||||
|
||||
@return An array containing all elements in the specified range. The type
|
||||
of the objects depends on the specified
|
||||
<code>referenceFrame</code>.
|
||||
*/
|
||||
- (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 update the receiver's expression tree to reflect the
|
||||
change.
|
||||
|
||||
@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 finds the elements at the respective indexes starting
|
||||
at the root expression from the receiver's expression tree.
|
||||
The returned object can be a <code>NSString</code>, a
|
||||
<code>MPFunction</code> or an <code>MPExpression</code> instance
|
||||
depending on the specified <code>indexPath</code>. If any of the
|
||||
indexes exceed the bounds of the respective receiver a
|
||||
<code>NSRangeException</code> 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 <code>indexPath</code>. The element is not
|
||||
copied before it is returned. Be aware of the fact that any
|
||||
mutations made to the returned object will update the receiver's
|
||||
expression tree to reflect the change.
|
||||
*/
|
||||
- (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 <code>-convertIndex:fromReferenceFrame:toReferenceFrame:offset:</code>
|
||||
instead.
|
||||
|
||||
@param anIndex
|
||||
The index to be converted.
|
||||
|
||||
@param fromReferenceFrame
|
||||
The reference frame <code>anIndex</code> is specified in.
|
||||
|
||||
@param toReferenceFrame
|
||||
The reference frame <code>anIndex</code> should be converted to.
|
||||
|
||||
@return An index specified in the <code>toReferenceFrame</code>. If
|
||||
<code>anIndex</code> identifies a location inside an item in the
|
||||
<code>toReferenceFrame</code> 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 <code>anIndex</code> identifies a location inside an item in
|
||||
the <code>toReferenceFrame</code> the index of the corresponding
|
||||
item is returned. In that case the <code>offset</code> parameter
|
||||
will be set to the number of symbols the offset goes into the
|
||||
item at the returned index.
|
||||
|
||||
@param anIndex
|
||||
The index to be converted.
|
||||
|
||||
@param fromReferenceFrame
|
||||
The reference frame <code>anIndex</code> is specified in.
|
||||
|
||||
@param toReferenceFrame
|
||||
The reference frame <code>anIndex</code> should be converted to.
|
||||
|
||||
@param offset
|
||||
This output parameter will be set to the number of symbols that
|
||||
are between the location identified by <code>anIndex</code> 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 <code>NULL</code>.
|
||||
|
||||
@return An index specified in the <code>toReferenceFrame</code>
|
||||
corresponding to <code>anIndex</code>.
|
||||
*/
|
||||
- (NSUInteger)convertIndex:(NSUInteger)anIndex
|
||||
fromReferenceFrame:(MPReferenceFrame)fromReferenceFrame
|
||||
toReferenceFrame:(MPReferenceFrame)toReferenceFrame
|
||||
offset:(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
|
||||
<code>-convertIndex:fromReferenceFrame:toReferenceFrame:</code>.
|
||||
It ensures that the returned range definitely includes all items
|
||||
that were specified by <code>aRange</code>.
|
||||
|
||||
The possibility that the returned range may
|
||||
include more symbols than <code>aRange</code> is ignored. If you
|
||||
need that information use
|
||||
<code>-convertRange:fromReferenceFrame:toReferenceFrame:leadingOffset:trailingOffset:</code>.
|
||||
|
||||
@param aRange
|
||||
The range to be converted.
|
||||
|
||||
@param fromReferenceFrame
|
||||
The reference frame <code>aRange</code> is specified in.
|
||||
|
||||
@param toReferenceFrame
|
||||
The reference frame <code>aRange</code> is to be converted to.
|
||||
|
||||
@return A range in the <code>toReferenceFrame</code> that includes the
|
||||
the items identified by <code>aRange</code>.
|
||||
*/
|
||||
- (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
|
||||
<code>-convertIndex:fromReferenceFrame:toReferenceFrame:</code>.
|
||||
It ensures that the returned range definitely includes all items
|
||||
that were specified by <code>aRange</code>.
|
||||
|
||||
@param aRange
|
||||
The range to be converted.
|
||||
|
||||
@param fromReferenceFrame
|
||||
The reference frame <code>aRange</code> is specified in.
|
||||
|
||||
@param toReferenceFrame
|
||||
The reference frame <code>aRange</code> is to be converted to.
|
||||
|
||||
@param leadingOffset
|
||||
The offset of the location of the returned range in respect to
|
||||
the location of <code>aRange</code>.
|
||||
|
||||
@param trailingOffset
|
||||
The offset of the last index in the range in respect to the last
|
||||
index of <code>aRange</code>.
|
||||
|
||||
@return A range in the <code>toReferenceFrame</code> that includes the the items
|
||||
specified by <code>aRange</code>.
|
||||
*/
|
||||
- (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 <code>elements</code> array.
|
||||
|
||||
@discussion This is the most primitive mutation method of
|
||||
<code>MPExpression</code>. Every other mutating method must
|
||||
ultimately 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
|
||||
<code>-changedElementsInIndexedRangePath:replacementLength:</code>
|
||||
to itself. For more information see the documentation on that
|
||||
method.
|
||||
|
||||
@param aRange
|
||||
The range of symbols (including functions) to replace.
|
||||
|
||||
@param referenceFrame
|
||||
The reference frame <code>aRange</code> is specified in.
|
||||
|
||||
@param elements
|
||||
The elements that should replace the symbols specified by
|
||||
<code>range</code>.
|
||||
*/
|
||||
- (void)replaceItemsInRange:(NSRange)aRange
|
||||
referenceFrame:(MPReferenceFrame)referenceFrame
|
||||
withElements:(NSArray *)elements;
|
||||
|
||||
|
||||
/*!
|
||||
@method changedElementsInRangePath:replacementLength:
|
||||
@brief This is a notification message that is sent from the receiver to
|
||||
itself after it has been mutated.
|
||||
|
||||
@discussion This method does nothing more than notify it's parent that it has
|
||||
been mutated at the respective range path. If you want to get
|
||||
notified about changes in an expression you should override this
|
||||
method instead of
|
||||
<code>-replaceSymbolsInRange:withElements:</code> because this
|
||||
method gives you information about the elements that changed
|
||||
during the mutation.
|
||||
|
||||
@param rangePath
|
||||
The range path at which the receiver was changed starting at the
|
||||
receiver. The range addressed by <code>rangePath</code> is
|
||||
expressed in the element reference frame.
|
||||
|
||||
@param replacementLength
|
||||
The number of elements replacing the elements specified by
|
||||
<code>rangePath</code> (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's expression tree.
|
||||
|
||||
@param from
|
||||
The index from which to start constructing the subexpression.
|
||||
|
||||
@param referenceFrame
|
||||
The reference frame <code>from</code> 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 to the specified item.
|
||||
|
||||
@discussion The items from the receiver are copied. Mutations to the returned
|
||||
expression will not change the receiver's expression tree.
|
||||
|
||||
@param to
|
||||
The index of the first element not to include in the newly
|
||||
constructed subexpression.
|
||||
|
||||
@param referenceFrame
|
||||
The reference frame <code>to</code> 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's expression tree.
|
||||
|
||||
@param aRange
|
||||
Specifies the items to be included in the newly created
|
||||
subexpression.
|
||||
|
||||
@param referenceFrame
|
||||
The reference frame <code>aRange</code> is specified in.
|
||||
|
||||
@return An expression containing the items in <code>aRange</code>.
|
||||
*/
|
||||
- (MPExpression *)subexpressionWithRange:(NSRange)aRange
|
||||
referenceFrame:(MPReferenceFrame)referenceFrame;
|
||||
|
||||
|
||||
#pragma mark Evaluating Expressions
|
||||
/*!
|
||||
@methodgroup Evaluating Expressions
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
@method parse:
|
||||
@brief Parses the receiver.
|
||||
|
||||
@discussion This is a convenience method that calls
|
||||
<code>-parseExpectingVariable:errors:</code> with <code>NO</code>
|
||||
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 <code>NSError</code> instances. This parameter is never
|
||||
set to an empty array. Pass <code>NULL</code> if you are not
|
||||
interested in any errors that might occur.
|
||||
|
||||
@return A <code>MPParsedExpression</code> instance that represents the
|
||||
receiver and can be evaluated or <code>nil</code> if an error
|
||||
occurs. In that case the <code>errors</code> parameter is set to
|
||||
an array containing at least one <code>NSError</code> instance.
|
||||
*/
|
||||
- (MPParsedExpression *)parse:(NSArray *__autoreleasing *)errors;
|
||||
|
||||
|
||||
/*!
|
||||
@method parseExpectingVariable:errors:
|
||||
@brief Parses the receiver.
|
||||
|
||||
@param flag
|
||||
If <code>YES</code> 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
|
||||
<code>NO</code> 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 <code>NSError</code> instances. This parameter is never
|
||||
set to an empty array. Pass <code>NULL</code> if you are not
|
||||
interested in any errors that might occur.
|
||||
|
||||
@return A <code>MPParsedExpression</code> instance that represents the
|
||||
receiver and can be evaluated or <code>nil</code> if an error
|
||||
occurs. In that case the <code>errors</code> parameter is set to
|
||||
an array containing at least one <code>NSError</code> instance.
|
||||
*/
|
||||
- (MPParsedExpression *)parseExpectingVariable:(BOOL)flag
|
||||
errors:(NSArray *__autoreleasing *)errors;
|
||||
|
||||
@end
|
||||
|
||||
|
||||
|
||||
/*!
|
||||
@category MPExpression (MPExpressionConvenience)
|
||||
@brief This category defines convenience methods for the
|
||||
<code>MPExpression</code> class.
|
||||
|
||||
@discussion All convenience methods are completely defined in terms of other
|
||||
methods of the <code>MPExpression</code> 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 <code>anIndex</code>.
|
||||
*/
|
||||
- (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 <code>anIndex</code>.
|
||||
*/
|
||||
- (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 <code>anIndex</code>.
|
||||
*/
|
||||
- (id<MPToken>)tokenAtIndex:(NSUInteger)anIndex;
|
||||
|
||||
|
||||
#pragma mark Mutating Expressions
|
||||
/*!
|
||||
@methodgroup Mutating Expressions
|
||||
*/
|
||||
|
||||
|
||||
/*!
|
||||
@method appendElement:
|
||||
@brief Appends <code>anElement</code> to the receiver.
|
||||
|
||||
@param anElement
|
||||
The element to append to the receiver.
|
||||
*/
|
||||
- (void)appendElement:(id<MPExpressionElement>)anElement;
|
||||
|
||||
|
||||
/*!
|
||||
@method appendElements:
|
||||
@brief Appends the objects from <code>elements</code> to the receiver.
|
||||
|
||||
@discussion All objects in the <code>elements</code> array must conform to
|
||||
the <code>MPExpressionElement</code> protocol. If at least one
|
||||
element does not conform to that protocol a
|
||||
<code>MPIllegalElementException</code> is raised.
|
||||
|
||||
@param elements
|
||||
The elements to append to the receiver.
|
||||
*/
|
||||
- (void)appendElements:(NSArray *)elements;
|
||||
|
||||
|
||||
/*!
|
||||
@method insertElement:atIndex:referenceFrame:
|
||||
@brief Inserts <code>anElement</code> at the specified index.
|
||||
|
||||
@param anElement
|
||||
The element to be inserted.
|
||||
|
||||
@param index
|
||||
The index where to insert <code>anElement</code>.
|
||||
|
||||
@param referenceFrame
|
||||
The reference frame <code>index</code> is specified in.
|
||||
*/
|
||||
- (void)insertElement:(id<MPExpressionElement>)anElement
|
||||
atIndex:(NSUInteger)index
|
||||
referenceFrame:(MPReferenceFrame)referenceFrame;
|
||||
|
||||
|
||||
/*!
|
||||
@method insertElements:atIndex:referenceFrame:
|
||||
@brief Inserts <code>elements</code> at the specified index.
|
||||
|
||||
@discussion All objects in the <code>elements</code> array must conform to
|
||||
the <code>MPExpressionElement</code> protocol. If at least one
|
||||
element does not conform to that protocol a
|
||||
<code>MPIllegalElementException</code> is raised.
|
||||
|
||||
@param elements
|
||||
The elements to be inserted.
|
||||
|
||||
@param index
|
||||
The index where to insert <code>elements</code>.
|
||||
|
||||
@param referenceFrame
|
||||
The reference frame <code>index</code> is specified in.
|
||||
*/
|
||||
- (void)insertElements:(NSArray *)elements
|
||||
atIndex:(NSUInteger)index
|
||||
referenceFrame:(MPReferenceFrame)referenceFrame;
|
||||
|
||||
|
||||
/*!
|
||||
@method deleteElementsInRange:
|
||||
@brief Removes the elements identified by <code>range</code> from the
|
||||
receiver.
|
||||
|
||||
@discussion If <code>range</code> exceeds the receiver's bounds a
|
||||
<code>NSRangeException</code> is raised.
|
||||
|
||||
@param range
|
||||
The range of items to remove from the receiver.
|
||||
|
||||
@param referenceFrame
|
||||
The reference frame <code>range</code> is specified in.
|
||||
*/
|
||||
- (void)deleteElementsInRange:(NSRange)range
|
||||
referenceFrame:(MPReferenceFrame)referenceFrame;
|
||||
|
||||
@end
|
||||
Reference in New Issue
Block a user