ginac/ex.h

   1 /** @file ex.h
   2  *
   3  *  Interface to GiNaC's light-weight expression handles. */
   4
   5 /*
   6  *  GiNaC Copyright (C) 1999-2003 Johannes Gutenberg University Mainz, Germany
   7  *
   8  *  This program is free software; you can redistribute it and/or modify
   9  *  it under the terms of the GNU General Public License as published by
  10  *  the Free Software Foundation; either version 2 of the License, or
  11  *  (at your option) any later version.
  12  *
  13  *  This program is distributed in the hope that it will be useful,
  14  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16  *  GNU General Public License for more details.
  17  *
  18  *  You should have received a copy of the GNU General Public License
  19  *  along with this program; if not, write to the Free Software
  20  *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  21  */
  22
  23 #ifndef __GINAC_EX_H__
  24 #define __GINAC_EX_H__
  25
  26 #include <iosfwd>
  27 #include <functional>
  28
  29 #include "basic.h"
  30 #include "ptr.h"
  31
  32 namespace GiNaC {
  33
  34
  35 /** Helper class to initialize the library.  There must be one static object
  36  *  of this class in every object file that makes use of our flyweights in
  37  *  order to guarantee proper initialization.  Hence we put it into this
  38  *  file which is included by every relevant file anyways.  This is modeled
  39  *  after section 27.4.2.1.6 of the C++ standard, where cout and friends are
  40  *  set up.
  41  *
  42  *  @see utils.cpp */
  43 class library_init {
  44 public:
  45         library_init();
  46         ~library_init();
  47 private:
  48         static int count;
  49 };
  50 /** For construction of flyweights, etc. */
  51 static library_init library_initializer;
  52
  53
  54 class scalar_products;
  55
  56
  57 /** Lightweight wrapper for GiNaC's symbolic objects.  Basically all it does is
  58  *  to hold a pointer to the other objects, manage the reference counting and
  59  *  provide methods for manipulation of these objects.  (Some people call such
  60  *  a thing a proxy class.) */
  61 class ex
  62 {
  63         friend class archive_node;
  64         friend bool are_ex_trivially_equal(const ex &, const ex &);
  65         template<class T> friend const T &ex_to(const ex &);
  66         template<class T> friend bool is_a(const ex &);
  67         template<class T> friend bool is_exactly_a(const ex &);
  68
  69         // default constructor, copy constructor and assignment operator
  70 public:
  71         ex();
  72 #ifdef OBSCURE_CINT_HACK
  73         ex(const ex & other);
  74         ex & operator=(const ex & other);
  75 #endif
  76
  77         // other constructors
  78 public:
  79         ex(const basic & other);
  80         ex(int i);
  81         ex(unsigned int i);
  82         ex(long i);
  83         ex(unsigned long i);
  84         ex(double const d);
  85
  86         /** Construct ex from string and a list of symbols. The input grammar is
  87          *  similar to the GiNaC output format. All symbols and indices to be used
  88          *  in the expression must be specified in a lst in the second argument.
  89          *  Undefined symbols and other parser errors will throw an exception. */
  90         ex(const std::string &s, const ex &l);
  91
  92         // non-virtual functions in this class
  93 public:
  94         /** Efficiently swap the contents of two expressions. */
  95         void swap(ex & other)
  96         {
  97                 GINAC_ASSERT(bp->flags & status_flags::dynallocated);
  98                 GINAC_ASSERT(other.bp->flags & status_flags::dynallocated);
  99                 bp.swap(other.bp);
 100         }
 101
 102         // evaluation
 103         ex eval(int level = 0) const { return bp->eval(level); }
 104         ex evalf(int level = 0) const { return bp->evalf(level); }
 105         ex evalm() const { return bp->evalm(); }
 106         ex eval_ncmul(const exvector & v) const { return bp->eval_ncmul(v); }
 107
 108         // printing
 109         void print(const print_context & c, unsigned level = 0) const;
 110         void dbgprint() const;
 111         void dbgprinttree() const;
 112
 113         // info
 114         bool info(unsigned inf) const { return bp->info(inf); }
 115
 116         // operand access
 117         size_t nops() const { return bp->nops(); }
 118         ex op(size_t i) const { return bp->op(i); }
 119         ex operator[](const ex & index) const { return (*bp)[index]; }
 120         ex operator[](size_t i) const { return (*bp)[i]; }
 121         ex & let_op(size_t i);
 122         ex & operator[](const ex & index);
 123         ex & operator[](size_t i);
 124         ex lhs() const;
 125         ex rhs() const;
 126
 127         // pattern matching
 128         bool has(const ex & pattern) const { return bp->has(pattern); }
 129         bool find(const ex & pattern, lst & found) const;
 130         bool match(const ex & pattern) const;
 131         bool match(const ex & pattern, lst & repl_lst) const { return bp->match(pattern, repl_lst); }
 132
 133         // substitutions
 134         ex subs(const exmap & m, unsigned options = 0) const;
 135         ex subs(const lst & ls, const lst & lr, unsigned options = 0) const;
 136         ex subs(const ex & e, unsigned options = 0) const;
 137
 138         // function mapping
 139         ex map(map_function & f) const { return bp->map(f); }
 140         ex map(ex (*f)(const ex & e)) const;
 141
 142         // visitors and tree traversal
 143         void accept(visitor & v) const { bp->accept(v); }
 144         void traverse_preorder(visitor & v) const;
 145         void traverse_postorder(visitor & v) const;
 146         void traverse(visitor & v) const { traverse_preorder(v); }
 147
 148         // degree/coeff
 149         int degree(const ex & s) const { return bp->degree(s); }
 150         int ldegree(const ex & s) const { return bp->ldegree(s); }
 151         ex coeff(const ex & s, int n = 1) const { return bp->coeff(s, n); }
 152         ex lcoeff(const ex & s) const { return coeff(s, degree(s)); }
 153         ex tcoeff(const ex & s) const { return coeff(s, ldegree(s)); }
 154
 155         // expand/collect
 156         ex expand(unsigned options=0) const;
 157         ex collect(const ex & s, bool distributed = false) const { return bp->collect(s, distributed); }
 158
 159         // differentiation and series expansion
 160         ex diff(const symbol & s, unsigned nth = 1) const;
 161         ex series(const ex & r, int order, unsigned options = 0) const;
 162
 163         // rational functions
 164         ex normal(int level = 0) const;
 165         ex to_rational(lst &repl_lst) const;
 166         ex to_polynomial(lst &repl_lst) const;
 167         ex numer() const;
 168         ex denom() const;
 169         ex numer_denom() const;
 170
 171         // polynomial algorithms
 172         ex unit(const symbol &x) const;
 173         ex content(const symbol &x) const;
 174         numeric integer_content() const;
 175         ex primpart(const symbol &x) const;
 176         ex primpart(const symbol &x, const ex &cont) const;
 177         ex smod(const numeric &xi) const { return bp->smod(xi); }
 178         numeric max_coefficient() const;
 179
 180         // indexed objects
 181         exvector get_free_indices() const { return bp->get_free_indices(); }
 182         ex simplify_indexed() const;
 183         ex simplify_indexed(const scalar_products & sp) const;
 184
 185         // comparison
 186         int compare(const ex & other) const;
 187         bool is_equal(const ex & other) const;
 188         bool is_zero() const { extern const ex _ex0; return is_equal(_ex0); }
 189
 190         // symmetry
 191         ex symmetrize() const;
 192         ex symmetrize(const lst & l) const;
 193         ex antisymmetrize() const;
 194         ex antisymmetrize(const lst & l) const;
 195         ex symmetrize_cyclic() const;
 196         ex symmetrize_cyclic(const lst & l) const;
 197
 198         // noncommutativity
 199         unsigned return_type() const { return bp->return_type(); }
 200         unsigned return_type_tinfo() const { return bp->return_type_tinfo(); }
 201
 202         unsigned gethash() const { return bp->gethash(); }
 203
 204 private:
 205         static ptr<basic> construct_from_basic(const basic & other);
 206         static basic & construct_from_int(int i);
 207         static basic & construct_from_uint(unsigned int i);
 208         static basic & construct_from_long(long i);
 209         static basic & construct_from_ulong(unsigned long i);
 210         static basic & construct_from_double(double d);
 211         static ptr<basic> construct_from_string_and_lst(const std::string &s, const ex &l);
 212         void makewriteable();
 213
 214 #ifdef OBSCURE_CINT_HACK
 215 public:
 216         static bool last_created_or_assigned_bp_can_be_converted_to_ex()
 217         {
 218                 if (last_created_or_assigned_bp==0) return false;
 219                 if ((last_created_or_assigned_bp->flags &
 220                          status_flags::dynallocated)==0) return false;
 221                 if ((last_created_or_assigned_bp->flags &
 222                          status_flags::evaluated)==0) return false;
 223                 return true;
 224         }
 225 protected:
 226         void update_last_created_or_assigned_bp()
 227         {
 228                 last_created_or_assigned_bp = bp;
 229                 last_created_or_assigned_exp = (long)(void *)(this);
 230         }
 231 #endif // def OBSCURE_CINT_HACK
 232
 233 // member variables
 234
 235 private:
 236         ptr<basic> bp;      ///< pointer to basic object managed by this
 237
 238 #ifdef OBSCURE_CINT_HACK
 239 public:
 240         static ptr<basic> last_created_or_assigned_bp;
 241         static basic * dummy_bp;
 242         static long last_created_or_assigned_exp;
 243 #endif // def OBSCURE_CINT_HACK
 244 };
 245
 246
 247 // performance-critical inlined method implementations
 248
 249 // This needs to be a basic* because we don't know that numeric is derived
 250 // from basic and we need a basic& for the ex default constructor
 251 extern const basic *_num0_bp;
 252
 253 inline
 254 ex::ex() : bp(*const_cast<basic *>(_num0_bp))
 255 {
 256         GINAC_ASSERT(bp->flags & status_flags::dynallocated);
 257 #ifdef OBSCURE_CINT_HACK
 258         update_last_created_or_assigned_bp();
 259 #endif // def OBSCURE_CINT_HACK
 260 }
 261
 262 #ifdef OBSCURE_CINT_HACK
 263 inline
 264 ex::ex(const ex & other) : bp(other.bp)
 265 {
 266         GINAC_ASSERT((bp->flags) & status_flags::dynallocated);
 267         update_last_created_or_assigned_bp();
 268 }
 269
 270 inline
 271 ex & ex::operator=(const ex & other)
 272 {
 273         GINAC_ASSERT(bp->flags & status_flags::dynallocated);
 274         GINAC_ASSERT(other.bp->flags & status_flags::dynallocated);
 275         bp = other.bp;
 276         update_last_created_or_assigned_bp();
 277         return *this;
 278 }
 279 #endif // def OBSCURE_CINT_HACK
 280
 281 inline
 282 ex::ex(const basic & other) : bp(construct_from_basic(other))
 283 {
 284         GINAC_ASSERT(bp->flags & status_flags::dynallocated);
 285 #ifdef OBSCURE_CINT_HACK
 286         update_last_created_or_assigned_bp();
 287 #endif // def OBSCURE_CINT_HACK
 288 }
 289
 290 inline
 291 ex::ex(int i) : bp(construct_from_int(i))
 292 {
 293         GINAC_ASSERT(bp->flags & status_flags::dynallocated);
 294 #ifdef OBSCURE_CINT_HACK
 295         update_last_created_or_assigned_bp();
 296 #endif // def OBSCURE_CINT_HACK
 297 }
 298
 299 inline
 300 ex::ex(unsigned int i) : bp(construct_from_uint(i))
 301 {
 302         GINAC_ASSERT(bp->flags & status_flags::dynallocated);
 303 #ifdef OBSCURE_CINT_HACK
 304         update_last_created_or_assigned_bp();
 305 #endif // def OBSCURE_CINT_HACK
 306 }
 307
 308 inline
 309 ex::ex(long i) : bp(construct_from_long(i))
 310 {
 311         GINAC_ASSERT(bp->flags & status_flags::dynallocated);
 312 #ifdef OBSCURE_CINT_HACK
 313         update_last_created_or_assigned_bp();
 314 #endif // def OBSCURE_CINT_HACK
 315 }
 316
 317 inline
 318 ex::ex(unsigned long i) : bp(construct_from_ulong(i))
 319 {
 320         GINAC_ASSERT(bp->flags & status_flags::dynallocated);
 321 #ifdef OBSCURE_CINT_HACK
 322         update_last_created_or_assigned_bp();
 323 #endif // def OBSCURE_CINT_HACK
 324 }
 325
 326 inline
 327 ex::ex(double const d) : bp(construct_from_double(d))
 328 {
 329         GINAC_ASSERT(bp->flags & status_flags::dynallocated);
 330 #ifdef OBSCURE_CINT_HACK
 331         update_last_created_or_assigned_bp();
 332 #endif // def OBSCURE_CINT_HACK
 333 }
 334
 335 inline
 336 ex::ex(const std::string &s, const ex &l) : bp(construct_from_string_and_lst(s, l))
 337 {
 338         GINAC_ASSERT(bp->flags & status_flags::dynallocated);
 339 #ifdef OBSCURE_CINT_HACK
 340         update_last_created_or_assigned_bp();
 341 #endif // def OBSCURE_CINT_HACK
 342 }
 343
 344 inline
 345 int ex::compare(const ex & other) const
 346 {
 347         if (bp == other.bp)  // trivial case: both expressions point to same basic
 348                 return 0;
 349         return bp->compare(*other.bp);
 350 }
 351
 352 inline
 353 bool ex::is_equal(const ex & other) const
 354 {
 355         if (bp == other.bp)  // trivial case: both expressions point to same basic
 356                 return true;
 357         return bp->is_equal(*other.bp);
 358 }
 359
 360
 361 // utility functions
 362
 363 /** Compare two objects of class quickly without doing a deep tree traversal.
 364  *  @return "true" if they are equal
 365  *          "false" if equality cannot be established quickly (e1 and e2 may
 366  *          still be equal, in this case. */
 367 inline bool are_ex_trivially_equal(const ex &e1, const ex &e2)
 368 {
 369         return e1.bp == e2.bp;
 370 }
 371
 372 // wrapper functions around member functions
 373 inline size_t nops(const ex & thisex)
 374 { return thisex.nops(); }
 375
 376 inline ex expand(const ex & thisex, unsigned options = 0)
 377 { return thisex.expand(options); }
 378
 379 inline bool has(const ex & thisex, const ex & pattern)
 380 { return thisex.has(pattern); }
 381
 382 inline bool find(const ex & thisex, const ex & pattern, lst & found)
 383 { return thisex.find(pattern, found); }
 384
 385 inline int degree(const ex & thisex, const ex & s)
 386 { return thisex.degree(s); }
 387
 388 inline int ldegree(const ex & thisex, const ex & s)
 389 { return thisex.ldegree(s); }
 390
 391 inline ex coeff(const ex & thisex, const ex & s, int n=1)
 392 { return thisex.coeff(s, n); }
 393
 394 inline ex numer(const ex & thisex)
 395 { return thisex.numer(); }
 396
 397 inline ex denom(const ex & thisex)
 398 { return thisex.denom(); }
 399
 400 inline ex numer_denom(const ex & thisex)
 401 { return thisex.numer_denom(); }
 402
 403 inline ex normal(const ex & thisex, int level=0)
 404 { return thisex.normal(level); }
 405
 406 inline ex to_rational(const ex & thisex, lst & repl_lst)
 407 { return thisex.to_rational(repl_lst); }
 408
 409 inline ex to_polynomial(const ex & thisex, lst & repl_lst)
 410 { return thisex.to_polynomial(repl_lst); }
 411
 412 inline ex collect(const ex & thisex, const ex & s, bool distributed = false)
 413 { return thisex.collect(s, distributed); }
 414
 415 inline ex eval(const ex & thisex, int level = 0)
 416 { return thisex.eval(level); }
 417
 418 inline ex evalf(const ex & thisex, int level = 0)
 419 { return thisex.evalf(level); }
 420
 421 inline ex evalm(const ex & thisex)
 422 { return thisex.evalm(); }
 423
 424 inline ex diff(const ex & thisex, const symbol & s, unsigned nth = 1)
 425 { return thisex.diff(s, nth); }
 426
 427 inline ex series(const ex & thisex, const ex & r, int order, unsigned options = 0)
 428 { return thisex.series(r, order, options); }
 429
 430 inline bool match(const ex & thisex, const ex & pattern, lst & repl_lst)
 431 { return thisex.match(pattern, repl_lst); }
 432
 433 inline ex simplify_indexed(const ex & thisex)
 434 { return thisex.simplify_indexed(); }
 435
 436 inline ex simplify_indexed(const ex & thisex, const scalar_products & sp)
 437 { return thisex.simplify_indexed(sp); }
 438
 439 inline ex symmetrize(const ex & thisex)
 440 { return thisex.symmetrize(); }
 441
 442 inline ex symmetrize(const ex & thisex, const lst & l)
 443 { return thisex.symmetrize(l); }
 444
 445 inline ex antisymmetrize(const ex & thisex)
 446 { return thisex.antisymmetrize(); }
 447
 448 inline ex antisymmetrize(const ex & thisex, const lst & l)
 449 { return thisex.antisymmetrize(l); }
 450
 451 inline ex symmetrize_cyclic(const ex & thisex)
 452 { return thisex.symmetrize_cyclic(); }
 453
 454 inline ex symmetrize_cyclic(const ex & thisex, const lst & l)
 455 { return thisex.symmetrize_cyclic(l); }
 456
 457 inline ex op(const ex & thisex, size_t i)
 458 { return thisex.op(i); }
 459
 460 inline ex lhs(const ex & thisex)
 461 { return thisex.lhs(); }
 462
 463 inline ex rhs(const ex & thisex)
 464 { return thisex.rhs(); }
 465
 466 inline bool is_zero(const ex & thisex)
 467 { return thisex.is_zero(); }
 468
 469 inline void swap(ex & e1, ex & e2)
 470 { e1.swap(e2); }
 471
 472
 473 // This makes STL algorithms use the more efficient swap operation for ex objects
 474 inline void iter_swap(std::vector<ex>::iterator i1, std::vector<ex>::iterator i2)
 475 { i1->swap(*i2); }
 476
 477
 478 /* Function objects for STL sort() etc. */
 479 struct ex_is_less : public std::binary_function<ex, ex, bool> {
 480         bool operator() (const ex &lh, const ex &rh) const { return lh.compare(rh) < 0; }
 481 };
 482
 483 struct ex_is_equal : public std::binary_function<ex, ex, bool> {
 484         bool operator() (const ex &lh, const ex &rh) const { return lh.is_equal(rh); }
 485 };
 486
 487 struct op0_is_equal : public std::binary_function<ex, ex, bool> {
 488         bool operator() (const ex &lh, const ex &rh) const { return lh.op(0).is_equal(rh.op(0)); }
 489 };
 490
 491 struct ex_swap : public std::binary_function<ex, ex, void> {
 492         void operator() (ex &lh, ex &rh) const { lh.swap(rh); }
 493 };
 494
 495 inline ex ex::subs(const exmap & m, unsigned options) const
 496 {
 497         return bp->subs(m, options);
 498 }
 499
 500 inline ex subs(const ex & thisex, const exmap & m, unsigned options = 0)
 501 { return thisex.subs(m, options); }
 502
 503 inline ex subs(const ex & thisex, const lst & ls, const lst & lr, unsigned options = 0)
 504 { return thisex.subs(ls, lr, options); }
 505
 506 inline ex subs(const ex & thisex, const ex & e, unsigned options = 0)
 507 { return thisex.subs(e, options); }
 508
 509
 510 /* Convert function pointer to function object suitable for map(). */
 511 class pointer_to_map_function : public map_function {
 512 protected:
 513         ex (*ptr)(const ex &);
 514 public:
 515         explicit pointer_to_map_function(ex x(const ex &)) : ptr(x) {}
 516         ex operator()(const ex & e) { return ptr(e); }
 517 };
 518
 519 template<class T1>
 520 class pointer_to_map_function_1arg : public map_function {
 521 protected:
 522         ex (*ptr)(const ex &, T1);
 523         T1 arg1;
 524 public:
 525         explicit pointer_to_map_function_1arg(ex x(const ex &, T1), T1 a1) : ptr(x), arg1(a1) {}
 526         ex operator()(const ex & e) { return ptr(e, arg1); }
 527 };
 528
 529 template<class T1, class T2>
 530 class pointer_to_map_function_2args : public map_function {
 531 protected:
 532         ex (*ptr)(const ex &, T1, T2);
 533         T1 arg1;
 534         T2 arg2;
 535 public:
 536         explicit pointer_to_map_function_2args(ex x(const ex &, T1, T2), T1 a1, T2 a2) : ptr(x), arg1(a1), arg2(a2) {}
 537         ex operator()(const ex & e) { return ptr(e, arg1, arg2); }
 538 };
 539
 540 template<class T1, class T2, class T3>
 541 class pointer_to_map_function_3args : public map_function {
 542 protected:
 543         ex (*ptr)(const ex &, T1, T2, T3);
 544         T1 arg1;
 545         T2 arg2;
 546         T3 arg3;
 547 public:
 548         explicit pointer_to_map_function_3args(ex x(const ex &, T1, T2, T3), T1 a1, T2 a2, T3 a3) : ptr(x), arg1(a1), arg2(a2), arg3(a3) {}
 549         ex operator()(const ex & e) { return ptr(e, arg1, arg2, arg3); }
 550 };
 551
 552 inline ex ex::map(ex f(const ex &)) const
 553 {
 554         pointer_to_map_function fcn(f);
 555         return bp->map(fcn);
 556 }
 557
 558 // convenience type checker template functions
 559
 560 /** Check if ex is a handle to a T, including base classes. */
 561 template <class T>
 562 inline bool is_a(const ex &obj)
 563 {
 564         return is_a<T>(*obj.bp);
 565 }
 566
 567 /** Check if ex is a handle to a T, not including base classes. */
 568 template <class T>
 569 inline bool is_exactly_a(const ex &obj)
 570 {
 571         return is_exactly_a<T>(*obj.bp);
 572 }
 573
 574 /** Return a reference to the basic-derived class T object embedded in an
 575  *  expression.  This is fast but unsafe: the result is undefined if the
 576  *  expression does not contain a T object at its top level.  Hence, you
 577  *  should generally check the type of e first.
 578  *
 579  *  @param e expression
 580  *  @return reference to object of class T
 581  *  @see is_exactly_a<class T>() */
 582 template <class T>
 583 inline const T &ex_to(const ex &e)
 584 {
 585         GINAC_ASSERT(is_a<T>(e));
 586         return static_cast<const T &>(*e.bp);
 587 }
 588
 589 } // namespace GiNaC
 590
 591 #endif // ndef __GINAC_EX_H__