Implemented Evaluation

MathPad/MPExpression.h

@@ -9,7 +9,7 @@
 @import Foundation;
 #import "NSString+MPExpressionElement.h"
 
-@class MPExpression, MPFunction, MPRangePath, MPExpressionEvaluator;
+@class MPExpression, MPFunction, MPRangePath, MPExpressionEvaluator, MPParseError;
 @protocol MPExpressionElement;
 
 /*!
@@ -242,6 +242,26 @@
 - (NSUInteger)indexOfElementAtSymbolLocation:(NSUInteger)location offset:(out NSUInteger *)offset;
 
 
+/*!
+    @method     locationOfElementAtIndex:
+    @brief      Calculates the location of the element at @c index.
+ 
+    @discussion @c index is an element index. Use this method to convert an
+                element index into the length reference frame.
+ 
+                If the index exceeds the receiver's number of elements a @c
+                NSRangeException will be raised.
+ 
+    @param      index
+                The index of the element that is to be converted into the length
+                reference frame.
+ 
+    @return     The number of symbols (in the length reference frame) before the
+                element at @c index.
+ */
+- (NSUInteger)locationOfElementAtIndex:(NSUInteger)index;
+
+
 /*!
     @method     replaceSymbolsInRange:withElements:
     @brief      Replaces the elements in the given range with the contents of the
@@ -271,28 +291,53 @@
 
 
 /*!
- @method     elements
- @brief      Returns an array of all elements in the receiver.
+    @method     elements
+    @brief      Returns an array of all elements in the receiver.
  
- @discussion The elements in the returned array are not copied before they are
- returned.
+    @discussion The elements in the returned array are not copied before they are
+                returned.
  
- @return     An array of all elements from the receiver.
+    @return     An array of all elements from the receiver.
  */
 - (NSArray *)elements;
 
 
 #pragma mark Evaluating Expressions
 
-- (double)evaluateExpression:(NSError *__autoreleasing *)error;
+
+/*!
+    @method     evaluateWitError:
+    @brief      Evaluates the receiving expression.
+ 
+    @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.
+ 
+    @param      errror
+                If the receiver (or any of its elements) contains a syntax error
+                or can not be evaluated this parameter is set to an appropriate
+                value. 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 *)evaluateWithError:(MPParseError *__autoreleasing *)error;
 
 
-// TODO: Private?
+/*!
+    @property   evaluator
+    @brief      Returns an object that can evaluate the receiver.
+ 
+    @discussion To just evaluate an expression it is recommended to send it an
+                @c evaluateWithError: message. You can however use this property
+                instead if you need more control over the evaluation process.
+ */
 @property (readonly, nonatomic, strong) MPExpressionEvaluator *evaluator;
 
 #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
-// TODO: More notifications
 
 /*!
     @method     didChangeElementsInRangePath:replacementLength: