% Copyright 2007 by Mark Wibrow
%
% This file may be distributed and/or modified
%
% 1. under the LaTeX Project Public License and/or
% 2. under the GNU Free Documentation License.
%
% See the file doc/generic/pgf/licenses/LICENSE for more details.


\section[Reimplementing the Computations of the Mathematical Engine]
  {Reimplementing the Computations of the\\ Mathematical Engine}

\label{pgfmath-reimplement}

Perhaps you are not satisfied with the Maclaurin series for
$e^x$. Perhaps you have a fantastically more accurate
and efficient way of calculating the sine or cosine of angles. Perhaps
 you would like the library to interface with a package such as |fp| 
 for fixed-point arithmetic (but you may find that exclusively
 using |fp| can cause a significant increase in compile time for
 documents involving many hundreds of calculations).
In these cases you will want to replace the current implementations of
the computations done by the mathematical engine by your own code. 

The mathematical engine was designed with such a replacement in
mind. For this reason, the operations and functions like |\pgfmathadd|
are implemented in the following manner: 

\begin{itemize}
\item |\pgfmath|\meta{function name} 

  This macro is the ``public'' interface for the function
  \meta{function name}. All arguments passed to this macro are 
  evaluated using |\pgfmathparse| and then passed on to the following
  function:
  
\item |\pgfmath|\meta{function name}|@|
  
  This macro is the ``non-public'' implementation of the functions 
  algorithm (but note that, for speed, the parser calls this macro 
  rather than the ``public'' one). Arguments passed to this macro 
  are expected to be numbers \emph{without units}. This is the macro 
  which should be rewritten with your prize-winning new algorithm.

  Note, furthermore, that if the function takes more than one
  argument, the second argument should not involve the dimensions
  |\pgfmath@x| nor |\pgfmath@xa| nor |\pgf@x| nor |\pgf@xa| since
  these may be set to the value of the first argument when the
  second argument is parsed.
\end{itemize}

The effect of |\pgfmath|\meta{function name}|@| should be to set the
macro |\pgfmathresult| to the correct value (namely to the result of
the computation without units). Furthermore, the function should have
no other side effects, that is, it should not change any global
values. One way to achieve this is to use the following code:

\begin{codeexample}[code only]
\def\pgfmath...@#1#2...{%
   \begingroup%
      ... code for algorithm ...
      \pgfmath@returnone\pgfmath@x%
   \endgroup%
}
\end{codeexample}


The macro |\pgfmath@returnone|\meta{code} must be directly followed by an
|\endgroup| and will save result of the algorithm, by defining
|\pgfmathresult| as the  expansion of \meta{code} \emph{without units}
outside the group. The \meta{code} should expand to a dimension
register or to a dimension. By performing the algorithm within a
\TeX{} group, \pgfname{} registers such as |\pgf@x|, |\pgf@y| and 
|\c@pgf@counta|, |\c@pgfcountb|, and so forth, can be used at will.

\pgfname{} uses the last known definition of a function within the
prevailing scope, so it is possible for a function to be redefined 
or |\let| to an alternative definition locally.
You should also remember that any |.sty| or |.tex| file contatining any
re-implementions should be loaded \emph{after} \pgfname-Math.