codello/mathpad
Archived
1
Fork 0
Code Releases 1 Activity

Added/Corrected Documentation

Browse Source
This commit is contained in:
Kim Wittenburg
2014-11-25 23:59:28 +01:00
parent 5bac2f0bbe
commit 4bc2fdead1
66 changed files with 380 additions and 710 deletions
Download Patch File Download Diff File Expand all files Collapse all files

122
MathPad/MPExpression.h
View File

@@ -33,12 +33,22 @@ FOUNDATION_EXPORT NSString *const MPIllegalElementExceptionElementKey;
/*!
@typedef MPReferenceFrame
@brief A reference frame describes what an @em item is.
@brief A reference frame describes what an @em item in an expression 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.
@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
@@ -46,8 +56,8 @@ FOUNDATION_EXPORT NSString *const MPIllegalElementExceptionElementKey;
@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.
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
@@ -55,7 +65,7 @@ FOUNDATION_EXPORT NSString *const MPIllegalElementExceptionElementKey;
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.
All tokens conform to the @c MPToken protocol.
*/
typedef NS_ENUM(NSUInteger, MPReferenceFrame) {
MPElementReferenceFrame,
@@ -68,6 +78,7 @@ typedef NS_ENUM(NSUInteger, MPReferenceFrame) {
@class MPExpression, MPFunction, MPRangePath, MPParsedExpression;
@protocol MPExpressionElement, MPToken;
/*!
@class MPExpression
@brief An @c MPExpression object is the base object for any mathematical
@@ -76,15 +87,11 @@ typedef NS_ENUM(NSUInteger, MPReferenceFrame) {
@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 @em children in this context). Both
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'.
@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.
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.
@@ -128,7 +135,8 @@ typedef NS_ENUM(NSUInteger, MPReferenceFrame) {
/*!
@method initWithElements:
@brief Initializes a newly created expression with the given elements.
@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
@@ -206,8 +214,8 @@ typedef NS_ENUM(NSUInteger, MPReferenceFrame) {
@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 given
reference frame.
@return The current number of items in the receiver counted in the
specified reference frame.
*/
- (NSUInteger)countItemsInReferenceFrame:(MPReferenceFrame)referenceFrame;
@@ -472,8 +480,8 @@ typedef NS_ENUM(NSUInteger, MPReferenceFrame) {
/*!
@method replaceItemsInRange:referenceFrame:withElements:
@brief Replaces the elements in the given range with the contents of the
@c elements array.
@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.
@@ -515,8 +523,8 @@ typedef NS_ENUM(NSUInteger, MPReferenceFrame) {
@param referenceFrame
The reference frame @c from is specified in.
@return An expression containing the items from the given index to the
end.
@return An expression containing the items from the specified index to
the end of the receiver.
*/
- (MPExpression *)subexpressionFromIndex:(NSUInteger)from
referenceFrame:(MPReferenceFrame)referenceFrame;
@@ -537,8 +545,8 @@ typedef NS_ENUM(NSUInteger, MPReferenceFrame) {
@param referenceFrame
The reference frame @c to is specified in.
@return An expression containing the items from the first item to the
given index.
@return An expression containing the items from the first item to the one
at the specified index.
*/
- (MPExpression *)subexpressionToIndex:(NSUInteger)to
referenceFrame:(MPReferenceFrame)referenceFrame;
@@ -572,7 +580,7 @@ typedef NS_ENUM(NSUInteger, MPReferenceFrame) {
/*!
@method evaluateWitError:
@method evaluateWitErrors:
@brief Evaluates the receiver.
@discussion This is a convenience method for evaluating an expression. If you
@@ -580,34 +588,66 @@ typedef NS_ENUM(NSUInteger, MPReferenceFrame) {
instead.
@param errors
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.
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. 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.
appropriate value.
*/
- (NSDecimalNumber *)evaluateWithErrors:(NSArray *__autoreleasing *)errors;
/*!
@method parse
@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.
@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 MPExpressionTree object that can evaluate the receiver.
@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;
@@ -645,6 +685,14 @@ typedef NS_ENUM(NSUInteger, MPReferenceFrame) {
/*!
@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