kspread Library API Documentation

formula.h

00001 /* This file is part of the KDE project
00002    Copyright (C) 2003,2004 Ariya Hidayat <ariya@kde.org>
00003 
00004    This library is free software; you can redistribute it and/or
00005    modify it under the terms of the GNU Library General Public
00006    License as published by the Free Software Foundation; either
00007    version 2 of the License.
00008 
00009    This library is distributed in the hope that it will be useful,
00010    but WITHOUT ANY WARRANTY; without even the implied warranty of
00011    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00012    Library General Public License for more details.
00013 
00014    You should have received a copy of the GNU Library General Public License
00015    along with this library; see the file COPYING.LIB.  If not, write to
00016    the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
00017    Boston, MA 02111-1307, USA.
00018 */
00019 
00020 #ifndef KSPREAD_FORMULA
00021 #define KSPREAD_FORMULA
00022 
00023 #include <qstring.h>
00024 #include <qvaluevector.h>
00025 
00026 #include "kspread_cell.h"
00027 #include "kspread_value.h"
00028 
00029 class KLocale;
00030 class KSpreadCell;
00031 
00032 namespace KSpread
00033 {
00034 
00035 class Token
00036 {
00037   public:
00038     typedef enum
00039     {
00040       Unknown,
00041       Boolean,     // True, False (also i18n-ized)
00042       Integer,     // 14, 3, 1977
00043       Float,       // 3.141592, 1e10, 5.9e-7
00044       String,      // "KOffice", "The quick brown fox..."
00045       Operator,    // +, *, /, -
00046       Cell,        // $A$1, F4, Sheet2!B5, 'Sales Forecast'!Sum
00047       Range,       // C1:C100
00048       Identifier   // function name or named area
00049     } Type;
00050 
00051     typedef enum
00052     {
00053       InvalidOp = 0,
00054       Plus,           //  + (addition)
00055       Minus,          //  - (substraction, negation)
00056       Asterisk,       //  * (multiplication)
00057       Slash,          //  / (division)
00058       Caret,          //  ^ (power)
00059       LeftPar,        //  (
00060       RightPar,       //  )
00061       Comma,          //  ,
00062       Semicolon,      //  ; (argument separator)
00063       Ampersand,      //  & (string concat)
00064       Equal,          //  =
00065       NotEqual,       //  <>
00066       Less,           //  <
00067       Greater,        //  >
00068       LessEqual,      //  <=
00069       GreaterEqual,   //  >=
00070       Percent         //  %
00071     } Op;
00072 
00076     Token( Type type = Unknown, const QString& text = QString::null, int pos = -1 );
00077     
00078     static const Token null;
00079 
00080     Token( const Token& );
00081     Token& operator=( const Token& );
00082     
00086     Type type() const { return m_type; }
00087 
00095     QString text() const { return m_text; }
00096     
00097     int pos() const { return m_pos; };
00098 
00102     bool isBoolean() const { return m_type == Boolean; }
00103 
00107     bool isInteger() const { return m_type == Integer; }
00108 
00112     bool isFloat() const { return m_type == Float; }
00113 
00117     bool isNumber() const { return (m_type == Integer) || (m_type == Float); }
00118 
00122     bool isString() const { return m_type == String; }
00123 
00127     bool isOperator() const { return m_type == Operator; }
00128 
00132     bool isCell() const { return m_type == Cell; }
00133 
00137     bool isRange() const { return m_type == Range; }
00138 
00142     bool isIdentifier() const { return m_type == Identifier; }
00143     
00148     bool asBoolean() const;
00149 
00154     int asInteger() const;
00155 
00160     double asFloat() const;
00161 
00171     QString asString() const;
00172 
00177     Op asOperator() const;
00178     
00191     QString sheetName() const;
00192 
00197     QString description() const;
00198     
00199   protected:
00200 
00201     Type m_type;
00202     QString m_text;
00203     int m_pos;
00204 
00205 };
00206 
00207 /*
00208  * Class Tokens represents array of tokens.
00209  *
00210  */
00211 class Tokens: public QValueVector<Token>
00212 {
00213 public:
00214   Tokens(): QValueVector<Token>(), m_valid(true) {};
00215   bool valid() const { return m_valid; }
00216   void setValid( bool v ){ m_valid = v; }
00217 protected:
00218   bool m_valid;
00219 };
00220 
00221 
00222 /*
00223  * Class Formula encapsulates a formula for a cell.
00224  *
00225  * A Formula is a equations which perform calculations on values in the cells 
00226  * and sheets. Every formula must start with an equal sign (=). 
00227  *
00228  *
00229  */
00230 
00231 class Formula
00232 {
00233   public:
00234   
00235     /*
00236      * Creates a formula. It must be owned by a cell.
00237      */
00238     Formula( KSpreadCell *cell );
00239     
00240     /*
00241      * Creates a formula that is not owned by any cell.
00242      * This might be useful in some cases.
00243      */
00244     Formula();
00245     
00246     /*
00247      * Destroys the formula.
00248      */
00249     ~Formula();
00250     
00251     /*
00252      * Returns the cell which owns this formula.
00253      */
00254     KSpreadCell* cell();
00255     
00256     /*
00257      * Sets the expression for this formula.
00258      */    
00259     void setExpression( const QString& expr );
00260     
00261     /*
00262      * Gets the expression of this formula.
00263      */    
00264     QString expression() const;    
00265     
00266     /*
00267      * Clears everything, makes as like a newly constructed formula.
00268      */    
00269     void clear();
00270         
00271     /*
00272      * Returns true if the specified expression is valid, i.e. it contains 
00273      * no parsing error.
00274      * Empty formula (i.e. without expression) is always invalid.
00275      */    
00276     bool isValid() const;
00277         
00278     /*
00279      * Returns list of tokens associated with this formula. This has nothing to 
00280      * with the formula evaluation but might be useful, e.g. for syntax 
00281      * highlight or similar features.
00282      * If the formula contains error, the returned tokens is invalid.
00283      */    
00284     Tokens tokens() const;
00285     
00286     /*
00287      * Evaluates the formula and returns the result.
00288      */    
00289     KSpreadValue eval() const;
00290     
00291     /*
00292      * Given an expression, this static function separates it into tokens.
00293      * If the expression contains error (e.g. unknown operator, string no terminated)
00294      * this function returns tokens which is not valid.
00295      */     
00296     static Tokens scan( const QString& expr, KLocale* locale = 0 );
00297 
00298     QString dump() const;
00299 
00300   protected:
00301   
00302     void compile( const Tokens& tokens ) const;        
00303     
00304   private:
00305     class Private;
00306     Private *d;
00307     // no copy or assign
00308     Formula( const Formula& );
00309     Formula& operator=( const Formula& );
00310 };
00311 
00315 QTextStream& operator<<( QTextStream& ts, Formula formula );
00316 
00317 
00318 } // namespace KSpread
00319 
00320 
00321 
00322 #endif // KSPREAD_FORMULA
00323 
KDE Logo
This file is part of the documentation for kspread Library Version 1.4.2.
Documentation copyright © 1996-2004 the KDE developers.
Generated on Mon Feb 13 09:42:44 2006 by doxygen 1.4.2 written by Dimitri van Heesch, © 1997-2003