codello/mathpad
Archived
1
Fork 0
Code Releases 1 Activity

Added Documentation

Browse Source
This commit is contained in:
Kim Wittenburg
2014-11-10 21:45:50 +01:00
parent f4f924bd71
commit 10f0e73ad3
32 changed files with 1847 additions and 318 deletions
Download Patch File Download Diff File Expand all files Collapse all files

597
MathPad/MPExpression.h
View File

@@ -6,11 +6,65 @@
// 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;
FOUNDATION_EXPORT NSString *const MPMathKitErrorDomain;
FOUNDATION_EXPORT NSString *const MPExpressionPathErrorKey;
/*!
@const MPMathKitErrorDomain
@brief Predefined error domain for errors from the MathKit framework.
@discussion Errors in MathKit can occur during parsing of expressions or
during evaluation of expressions. These two can be distinguished
by the error code. Parsing errors have lower error codes.
Evaluation errors (math errors) have error codes from @c 100 upwards.
*/
FOUNDATION_EXPORT NSString *const MPMathKitErrorDomain;
// TODO: Deal with this:
// FOUNDATION_EXPORT NSString *const MPPathToExpressionKey;
// FOUNDATION_EXPORT NSString *const MPRangeKey;
/*!
@function MPParseError
@brief Creates an @c NSError object in the @c MPMathKitErrorDomain.
@discussion The created error is filled with the passed data if present.
@param errorCode
The error code of the created error.
@param errorDescription
The localized description of the created error. May be @c nil.
@param underlyingError
The underlying error of the created error. May be @c nil.
@return An @c NSError object initialized with the given data.
*/
NS_INLINE NSError * MPParseError(NSInteger errorCode,
NSString *errorDescription,
NSError *underlyingError) {
@@ -27,12 +81,41 @@ NS_INLINE NSError * MPParseError(NSInteger errorCode,
return error;
}
/*!
@typedef MPReferenceFrame
@brief A reference frame describes what an @em item is.
@discussion An item may be an element, a symbol or a token. A symbol is the
smallest possible size for an item. An element as well as a token
consist 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 (as they are for example typed in by
the user) 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 must conform to the @c MPToken protocol.
*/
typedef NS_ENUM(NSUInteger, MPReferenceFrame) {
MPElementReferenceFrame,
MPSymbolReferenceFrame,
MPTokenReferenceFrame
};
@class MPExpression, MPFunction, MPRangePath, MPExpressionTree, MPExpressionEvaluator;
@protocol MPExpressionElement, MPToken;
@@ -42,45 +125,28 @@ typedef NS_ENUM(NSUInteger, MPReferenceFrame) {
expression.
@discussion Every expression consists of string elements (represented by the
@c NSString class) and functions (represented by the @c
MPFunction class) elements which both can be contained within an
expression. Functions in turn can have expressions as elements
(also called 'children' in this context). Both expressions and
functions are mutable.
@c NSString class) and function elements (represented by the @c
MPFunction class). Functions likewise can have expressions as
elements (also called @em children in this context). Both
expressions and functions are mutable. Through this organization
expression are organized in a tree-like structure called the
'expression tree'.
Through this organization expression are organized in a tree-like
structure (called the 'expression tree') allowing easy and
logical access to each element.
@note There is also the @c MPExpressionTree class. That class provides
an alternative representation of an expression. The 'expression
tree' does not refer to that class.
To query the contents of an expressions there are two options:
You can query on a per-element basis (that is string elements and
function elements as described before). This is called the @em
index reference frame (or @em indexed reference frame). You also
can query an expression on a per-symbol basis. This is called the
@em location reference frame (or @c located reference frame).
Using the located reference frame is useful if you are dealing
with user actions since the user does not necessarily see a
visual separation between different elements but only sees the
symbols that are drawn on the screen. You can convert between the
two reference frames using the following methods:
@code
- (NSUInteger)indexOfElementAtSymbolLocation:offset: // Converts from the located to the indexed reference frame
- (NSUInteger)locationOfElementAtIndex: // Converts from the indexed to the located reference frame
@endcode
In the indexed reference frame both functions and strings have a
dimension of 1. In the located reference frame the length of a
string is determined by sending it a @c -length message. In that
frame functions still have a length of 1.
An expression can evaluate itself giving you either a
result or possibly an error if the expression was not constructed
correctly.
correctly or could not be evaluated.
*/
@interface MPExpression : NSObject <NSCopying, NSCoding>
#pragma mark Creation Methods
/*!
@methodgroup Creation Methods
*/
/*!
@@ -128,12 +194,15 @@ typedef NS_ENUM(NSUInteger, MPReferenceFrame) {
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 the elements from @c elements.
@return An expression containing @c elements.
*/
- (instancetype)initWithElements:(NSArray *)elements; /* designated initializer */
#pragma mark Querying Expressions
/*!
@methodgroup Querying Expressions
*/
/*!
@@ -142,8 +211,9 @@ typedef NS_ENUM(NSUInteger, MPReferenceFrame) {
@discussion Expressions are organized in a tree-like structure. Through this
property an expression's containing function can be accessed.
@warning You should not set this property manually unless you are
implementing a subclass of @c MPFunction.
@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.
@@ -170,7 +240,7 @@ typedef NS_ENUM(NSUInteger, MPReferenceFrame) {
@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 indexed reference frame. If any of the indexes
expressed in the element reference frame. If any of the indexes
exceed the respective receiver's bounds a @c NSRangeException is
raised.
@@ -180,41 +250,62 @@ typedef NS_ENUM(NSUInteger, MPReferenceFrame) {
/*!
@method numberOfElements
@brief Returns the number of elements in the receiver.
@method countItemsInReferenceFrame:
@brief Returns the number of items in the receiver in the respective
reference frame.
@discussion The number of elements may vary from the number of elements that
were added to the receiver (using either @c -initWithElements: or
one of the several mutation methods). The number of elements is
expressed in the indexed reference frame. (The respective method
for the located reference frame is @c -length).
@param referenceFrame
The reference frame that should be used to count the items.
@return The current number of elements in the receiver.
@return The current number of items in the receiver counted in the given
reference frame.
*/
- (NSUInteger)countItemsInReferenceFrame:(MPReferenceFrame)referenceFrame;
/*!
@method elementAtIndex:
@brief Returns the element at @c anIndex.
@method itemAtIndex:referenceFrame:
@brief Returns the item at @c anIndex.
@discussion The element is not copied before it is returned. So be aware that
@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.
@note This method can also be called using indexed subscript
getter syntax.
@param anIndex
The index of the element expressed in the indexed reference
frame. If the index is greater than or equal to the number of
elements in the receiver an @c NSRangeException is raised.
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.
@return The element at @c anIndex.
@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;
@@ -226,45 +317,48 @@ typedef NS_ENUM(NSUInteger, MPReferenceFrame) {
@param element
The element to find.
@return The index of @c element expressed in the indexed reference frame.
@return The index of @c element expressed in the element reference frame.
*/
- (NSUInteger)indexOfElement:(id<MPExpressionElement>)element;
/*!
@method elementsInIndexedRange:
@brief Returns an array of the elements that are located in the
specified range. The range is specified in the indexed reference
frame.
@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 element will be reflected in the receiver.
returned objects will be reflected in the receiver.
If the @c range exceeds the receiver's bounds an @c
NSRangeException is raised.
@param range
The requested range within the receiver's bounds expressed in the
indexed reference frame.
@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)range
- (NSArray *)itemsInRange:(NSRange)aRange
referenceFrame:(MPReferenceFrame)referenceFrame;
/*!
@method elements
@brief Returns an array of all elements in the receiver.
@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.
returned so be aware that mutations to any of the returned
objects will be reflected in the receiver.
@return An array of all elements from the receiver.
@return An array of all items in the receiver.
*/
- (NSArray *)allItemsInReferenceFrame:(MPReferenceFrame)referenceFrame;
@@ -285,7 +379,7 @@ typedef NS_ENUM(NSUInteger, MPReferenceFrame) {
@param indexPath
The index path the required object is located at. The indexes are
expressed in the indexed reference frame.
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
@@ -293,19 +387,127 @@ typedef NS_ENUM(NSUInteger, MPReferenceFrame) {
*/
- (id)elementAtIndexPath:(NSIndexPath *)indexPath;
- (NSUInteger)convertIndex:(NSUInteger)index
/*!
@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;
- (NSUInteger)convertIndex:(NSUInteger)index
/*!
@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:(NSUInteger *)offset;
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
@@ -314,17 +516,19 @@ typedef NS_ENUM(NSUInteger, MPReferenceFrame) {
#pragma mark Mutating Expressions
/*!
@methodgroup Mutating Expressions
*/
/*!
@method replaceSymbolsInRange:withElements:
@method replaceItemsInRange:referenceFrame:withElements:
@brief Replaces the elements in the given 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
@@ -333,35 +537,98 @@ typedef NS_ENUM(NSUInteger, MPReferenceFrame) {
itself. For more information see the documentation on that
method.
@param range
The @c range of symbols (including functions) to replace
specified in the located reference frame.
@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)range
- (void)replaceItemsInRange:(NSRange)aRange
referenceFrame:(MPReferenceFrame)referenceFrame
withElements:(NSArray *)elements;
/*!
@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 given index to the
end.
*/
- (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
given index.
*/
- (MPExpression *)subexpressionToIndex:(NSUInteger)to
referenceFrame:(MPReferenceFrame)referenceFrame;
- (MPExpression *)subexpressionWithRange:(NSRange)range
/*!
@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 evaluateWitError:
@brief Evaluates the receiving expression.
@brief Evaluates the receiver.
@discussion This is a convenience method for evaluating an expression. If you
want more control over the evaluation process use the @c
evaluator property of the receiver.
want more control over the evaluation process use @c -parse
instead.
@param error
If the receiver (or any of its elements) contains a syntax error
@@ -371,18 +638,36 @@ typedef NS_ENUM(NSUInteger, MPReferenceFrame) {
@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.
appropriate value. If @c NaN is returned it means there was a
math error. In most cases the error parameter contains an
appropriate description of the problem.
*/
- (NSDecimalNumber *)evaluateWithError:(NSError *__autoreleasing *)error;
/*!
@method parse
@brief Parses the receiver.
@discussion This method returns a valid object even if the expression
contains syntax errors. Send the returned object a @c -validate:
message to check for syntax errors before you evaluate it. For
more information on evaluation see the documentation of @c
MPExpressionTree.
@return A @c MPExpressionTree object that can evaluate the receiver.
*/
- (MPExpressionTree *)parse;
#pragma mark Notifications
// All notification methods should create a new rangePath with the receiver's index added to the beginning of the path and then ascend the message to it's parent
/*!
@methodgroup Notifications
*/
/*!
@method didChangeElementsInIndexedRangePath:replacementLength:
@method didChangeElementsInRangePath:replacementLength:
@brief Called after the receiver has been mutated.
@discussion This method does nothing more than notify it's parent that it has
@@ -395,77 +680,165 @@ typedef NS_ENUM(NSUInteger, MPReferenceFrame) {
@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
indexed reference frame.
element reference frame.
@param replacementLength
The number of elements replacing the elements specified by @c
rangePath.
rangePath (also specified in the element reference frame).
*/
- (void)didChangeElementsInRangePath:(MPRangePath *)rangePath
replacementLength:(NSUInteger)replacementLength;
#pragma mark Basic NSObject Methods
// TODO: Check this
// - (BOOL)isEqualToExpression:(MPExpression *)anExpression;
@end
@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;
- (id<MPExpressionElement>)elementAtIndex:(NSUInteger)index;
- (id<MPExpressionElement>)symbolAtIndex:(NSUInteger)index;
- (id<MPToken>)tokenAtIndex:(NSUInteger)index;
/*!
@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.
@method appendElement:
@brief Appends @c anElement to the receiver.
@param anElement
The element to append 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.
@method appendElements:
@brief Appends the objects from @c elements to the receiver.
@param elements
The elements to append 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.
@method deleteElementsInRange:
@brief Removes the elements specified by @c range from the receiver.
@discussion The range is specified in the length reference frame.
@param range
The range of items to remove from the receiver.
If @c range exceeds the receiver's bounds a @c NSRangeException
is raised.
@param range
The range to remove from the receiver.
@param referenceFrame
The reference frame @c range is specified in.
*/
- (void)deleteElementsInRange:(NSRange)range
referenceFrame:(MPReferenceFrame)referenceFrame;