TComplexParser           
		  by Marianne H. Goeltl-Schuberth

TComplexParser is a non-visual DELPHI component for evaluating complex mathematical 
functions. 
The function term is a user given string like 'sin(z)*i'. The function term can be
changed during runtime.
TComplexParser can evaluate about 30 complex predefined functions and operations.
The user can define constants and variable names himself.

Contents:
  1. Features 
  2. Information 
  3. Installation
  4. Properties, Methods, Events
  5. The Object TComplex
  6. Recommended Use 
  7. Sample program
  8. List of operations and functions



1. Features 

	- Algebraic syntax, not case sensitive
	- Parentheses ()
	- Complex floating point numbers (TComplex)
	- Userdefined variablenames (default: z, z1, z2)
	- Implemented mathematical constants
	- Userdefined constants 
	- About 30 predetined complex functions and operations in TComplexParser
	- Userfunctions: YOUR own code is evaluated
	- Easy to use: see 7. Sample program 



2. Information

TComplexParser V3.0 is Shareware. 
You may test it for a period of 30 days.
It may be copied and distributed unmodified (complete ZIP-file, no single files).

If you use it in your non-commercial applications you must register it by 
sending 30 USD or 30 DM (cash or Euro cheque / traveller's check) to the author.

If you want to use TComplexParser for commercial purposes please contact me.

Registered users of one of the former versions get a discount.
You will obtain the registration code, that switches off the automatic initial info 
screen.
The registration code must not be passed on.

If you are not a registered user the infoscreen will appear each time an instance of 
TComplexParser is created. Furthermore you can only run one instance per application. 
Unregistered use is limited to 30 days.


My address is:
			Marianne H. Goeltl-Schuberth	
			Egerlandstr. 18	
			D-91083 Baiersdorf	
			Germany

         eMail:		schuberth@t-online.de  
	 URL:		http://home.t-online.de/home/schuberth/
			(you can find the LATEST released version there)

When ordering your personal registration code please confirm that you read this file and 
agree to the license conditions. Quote the desired version. Don't forget your eMail or 
postal address. I would like to know where you obtained these components from.          

If you find any bug, please don't hesitate to inform me. Details (functions, arguments, ...)
would be helpful.
Any suggestions, questions, and comments are welcome.


----------------------------------
THE LEGAL DISCLAIMER
----------------------------------
THE INFORMATION AND CODE PROVIDED HEREUNDER (COLLECTIVELY REFERRED TO AS "SOFTWARE") IS 
PROVIDED AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT 
LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. 
IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DAMAGES WHATSOEVER INCLUDING DIRECT, 
INDIRECT, INCIDENTAL, CONSEQUENTIAL, LOSS OF BUSINESS PROFITS OR SPECIAL DAMAGES, EVEN IF
THE AUTHOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. 



3. Installation 

The file CPLPRS3.ZIP (for Delphi 3), CPLPRS2.ZIP (for Delphi 2)  include the following files:

		CDEMO.DPR			providing a simple demo application
		CDEMO1.DFM			for TComplexParser (complex calculator)
		CDEMO1.PAS			

		CPLPRS3.DPK			source package	(only in CPLPRS3.ZIP)
		CPLPARS.DCU			containing the component 
		CPLPARS.DCR                     	  TComplexparser
		CPLPARS1.DCU
		CPLPARS1.DFM
		CPLPARS2.DCU
		CPLPARS2.DFM
		CPLPARS3.DCU
		CPLPARS4.DCU

		CPLPRS*.TXT 			short ASCII formatted Info, where * stands
						for the respective Delphi version
		FILE_ID.DIZ			dto.
		README.TXT			this file
  		NATCONST.DAT	        	selection of physical constants
		
For installing the components you need the files
					CPLPRS3.DPK  (only Delphi 3)
					CPLPARS.DCR
					CPLPARS.DCU
					CPLPARS1.DCU
					CPLPARS2.DCU
					CPLPARS3.DCU
					CPLPARS4.DCU
					CPLPARS1.DFM
					CPLPARS2.DFM.

Attention: If you have already installed a former version of TComplexParser you must remove
	   the respective DCU-files from your library and path first.

For Installation under Delphi 3:

- Choose from the menu File | Open
- Select the filter "Delphi Source Package (*.dpk)"
- Select CPLPRS3.DPK and click on Open
- Click on Install: The package is compiled first and then installed
- Confirm the information that a new component has been installed by clicking on OK
- You find now on the palette, page MHGS: 	TComplexParser
- Close CPLPRS3.DPK.
  Make sure that the path to the library contains the directory with the DCUs.

For Installation under Delphi 2:

- Delphi 2: Choose from the menu Component | Install
- Choose Add
- Choose Browse
- Select the file format *.DCU
- Select CPLPARS.DCU
- Choose OK and wait while the compiler adds the new component to your library 
- You find now on the palette, page MHGS: 	TComplexParser




4. Properties, Methods, Events

Input Properties

TComplexParser.Term : string			(only runtime)
	Term is a (huge) string (e.g. 'sin(x)') defining the given function. Spaces are 
	ignored. Lower or upper cases are not distinguished. Arguments of functions must 
	be in brackets. Multiple arguments in functions must be separated by semicola.

TComplexParser.VarValues[name]: TComplex	(only runtime)
	The variable values are stored in the array VarValues. The name is the variable name like
	it must have been declared in VarNames. Defaults are z, z1 and z2.

TComplexParser.VarNames: TStringlist
	You can define variable names in this stringlist. Default are z, z1 and z2.
	Each variable name must stand in a separat line.
	You may make comments in the same lines, after a '#'-sign (e.g. 'x	#that is x');

TComplexParser.Constants : TStringlist
	You can define an arbitrary number of constants in Constants 
	using the notation e.g. 'A1=1.5e-3' (cf. examples in NATCONST.DAT). 
	TComplexParser understands only numbers that are either real (e.g. 2.3e-2) or imaginary
	(e.g. -5.6i)
	The constant identifiers must be unique. Otherwise the first one in the list is 
	taken. 
	Reserved abbreviations for identifier are e, pi, C and i (or j). 
	The sequence of the definition of the constants doesn't	matter. You may even add 
	your own comments in separat lines.

	
Naming Conventions for Variables and Constants
The first character must be alphabetical. The remaining characters may be alphabetic or
numerical. Special symbols are not supported (except underscore). Identifiers must be unique.


TComplexParser.UserFct : function(TComplex):TComplex	(only runtime)	
	UserFct allows you to call a function whose code you wrote yourself. Your function
	must be declared as FUNCTION functionname(z:TComplex):TComplex. Then you can assign
	COMPLEXPARSER.USERFCT:=functionname.
	Your function is accessed if you call 'USERFCT(z)' in the Term. 

TComplexParser.About
	indicate whether the infoscreen is shown. 


TComplexParser.Data : pointer
	You may add an arbitrary object or pointer to TComplexParser. This is for your own use only. 
	It doesn't interact with TComplexParser itself. 


Output Properties:

TComplexParser.Result : TComplex	(only runtime)
	When you read the Result, the Term is evaluated and the function value returned.

TComplexParser.ErrorCode : byte 	(only runtime)
	If an error occurs the ErrorCode is set according to the following list:

	0	everything is OK
	1	wrong parentheses / semicola
	2	Syntax error / invalid term
	3	unknown identifier
	4	recursive function or constant
	5	wrong number of operands
	6	term is not analyzed
	7	function is not defined for argument(s)
	8	NaN: evaluation aborted
	9	declarations not assigned

	You should check ErrorCode after assigning the term and after reading the result.


TComplexParser.Errormessage : string 
	The Errormessage gives you verbal information on the errors that occured.
	With a resource editor (e.g. Borland Resource Workshop) you can change the text of
	the errormessages in your executable program (only Delphi 3). 

TComplexParser.Version: string
	indicates the used version.


Methods

TComplexParser.Showinfo
	If you want to see the infoscreen call ShowInfo.
	The minimum display time is 3 seconds. ShowInfo is AUTOMATICALLY executed when
	creating an instance of TComplexParser if you are not registered.



Events

TComplexParser.OnError
	The most common errors (syntax error, division by zero, ...) will raise the event OnError.
	



5. The Object TComplex

A mathematical complex number z consists of real part and imaginary part. You may write:
z=Re(z)+i*Im(z). Real and imaginary parts are real numbers each. "i" is the imaginary unit
with i=sqrt(-1).
The complex conjugate ~z=Re-i*Im.
The type TComplex used for TComplexParser is an object with the following properties and 
methodes:
	Re: extended			real part
	Im: extended			imaginary part
	Abs: extended			absolute |z|>=0
	Arg: extended			argument (phase), -pi< Arg <= pi
	Create(x,y: extended)		constructs an instance of TComplex with Re=x, Im=y
	CreatePolar(r,phi: extended)	constructs an instance of TComplex with Abs=r, Arg=phi
	Assign(z: TComplex): TComplex	assigns z to the instance
	Put(x,y: extended)		sets the real part to x and the imaginary part to y
	PutPolar(r,phi: extended)	sets the absolute to r and the phase to phi
	AsString: string		converts Re and Im into a string.

Arg yields a value between -pi and +pi. It takes the signs of Re and Im into account.

For transforming polar coordinates Abs and Arg to cartesian coordinates Re and Im use the
following formula:

	Re=Abs*cos(Arg),		Im=Abs*sin(Arg).

The inversion of this transformation is:

	Abs=sqrt(Re^2+Im^2),		Arg=arctan2(Im,Re) 


Many complex functions are ambiguous because of the periodicity of Arg. TComplexParser 
always yields only ONE result (main part).

For further calculation rules of complex numbers consult the respective mathematical 
literature.
Various applications for calculating with complex numbers are found in science and 
engineering (e.g. conformal transformations, gain and phase of alternating currents, 
solving of some differential equations, ...).


IMPORTANT:
If you want to work with TComplex explicitly you must include CPLPARS3 to your uses-clause.
 
Some people prefer "j" as abbreviation for the imaginary unit. If you included CPLPARS3
you can change the global variable IMAGLETTER:='j'. IMAGLETTER is used by TComplex.AsString
for output and TComplexParser.Term for input. Default for IMAGLETTER is "i".

Defining TComplexParser.Term you can write a complex number (e.g. 1-0.5*i) in one of the
following ways (if IMAGLETTER='i', i.e. unchanged):
	1-i0.5		1-0.5i		-0.5i+1		-i0.5+1
or something like  sqrt(5)/2*exp(-i*arctan(0.5)) or ...... 



7. Recommended Use

For working with TComplexParser you should perform the following steps.
Necessary steps are indicated by consecutive numbers. Letters mark optional steps that may
be omitted if you don't want to use the respective features.

(*1*)	You need an instance of TComplexParser.
	Choose it from the palette, page MHGS, or create it at runtime.
	
		Optional: (at design time or runtime)
		(*Aa*)	-Change VarNames  
		(*Ab*)	-Change Constants 

(*2*)	Set TComplexParser.Term to the desired function term (only runtime)
		
		Optional: (only runtime)
		(*B*)	-Check TComplexParser.ErrorCode or ErrorMessage

(*3*)	Set all required variable values (only runtime)

		Optional: (only runtime)
		(*C*)	-Set the user function

(*4*)	Read TComplexParser.Result (only runtime)

		Optional: (only runtime)
		(*B*)	-Check TComplexParser.ErrorCode or ErrorMessage




7. Sample Program:

The following procedure shows the general use of TComplexParser.

A simple calculator program for complex numbers may contain the following code (cf. cdemo.dpr).
Clicking on a button will induce the program to read the function term and real and imaginary
part of the variable value from the respective edit fields, evaluate these, and write the result
as the caption of a label. 

procedure TForm1.BitBtn1Click(Sender: TObject);
begin
   with ComplexParser1 do begin
   {(*1*) and (*Aa*) were performed at design time}
     Term:=edit1.text;    (*2*)
     try
       z.re:=strtofloat(edit2.text);
       z.im:=strtofloat(edit3.text);
     except
       on EConvertError do begin
         label4.caption:='Unvalid complex number';
         exit; end;
     end;
     VarValues['z'].Assign(z);   (*3*)
      label4.caption:='The result is '+Result.AsString;  (*4*)
      if ErrorCode<>0 then label4.caption:=ErrorMessage; (*B*)
   end;
end;




8. List of Operations and Functions

The separator between multiple arguments in functions is the semicolon (;). 
This character was choosen because the comma (,) is used as decimal separator 
in some countries.
Some Operators require their arguments in parentheses.
The second column specifies the availability for TFunctionParser / TDBParser(f) or 
TComplexParser (c). 

Adding:			fc	x + y   	adds x and y
Subtracting:		fc	x - y   	subtract y from x
Multiplying:		fc	x * y		multiplies x and y
			f 	fac(n)		factorial of n, n!	
Dividing:		fc	x / y		divides x through y
			f	(n) div (m)	integer division
			fc	rez(x) 		reciprocal value of x
			f	(n) mod (m)	integer modulo
			f	modulo(x;y)	rest of division x/y
Powers:			f	x ^ y		x to the power of y
			fc	sqr(x) 		square of x
			fc	exp(x) 		exponential of x
Roots:			fc	sqrt(x)		squareroot of x
			f	cbrt(x) 	cubic root of x
			f 	root(n;x)	n-th root of x
Logarithms:		fc	ln(x)		log. with base e of x
			f	lg(x)		log. with base 10 of x
			f	lb(x)		log. with base 2 of x
			f 	log(b;x)	common log. with base b of x
Trigonometric Functions:fc	sin(x)		sine of x
			fc	cos(x)		cosine of x
			fc	tan(x)		tangent of x
			fc	cot(x)		cotangent of x
Arc Functions:		fc	arcsin(x)	arc sine of x
			fc	arccos(x)	arc cosine of x
			fc	arctan(x)	arc tangent of x
			f 	atan2(y;x)	arc tangent of y/x
			fc	arccot(x)	arc cotangent of x
Hyperbolic Functions:	fc	sinh(x)		hyperbolic sine of x
			fc	cosh(x)		hyperbolic cosine of x
			fc	tanh(x)		hyperbolic tangent of x
			fc	coth(x)		hyperbolic cotangent of x
Area Functions:		fc	arsinh(x)	inverse hyperbolic sine of x
			fc	arcosh(x)	inverse hyperboloc cosine of x
			fc	artanh(x)	inverse hyperbolic tangent of x
			fc	arcoth(x)	inverse hyperbolic cotangent of x
Statistical Function:	f	gauss(x)	normal distribution of x
			f	erf(x)		error function of x
			f	inverf(x)	inverse of error function of x
			f	(n) over (k)	binomial coefficient n over k
			f 	bino(n;k)	binomial coefficient n over k
			f 	poisson(mu;n)	poisson distribution of n with average mu
			f	poicum(mu;n)	cumulated poison distribution up to n (ave. mu)
Random Numbers:		f	rnd(x)		random number in [0,x[ 
			f 	rand(x;y)	random number in [x,y[
			f	poirand(mu)	Poisson distributed random numbers (ave. mu) 
Bessel Functions:	f	J0(x)		0th order of x
			f	J1(x)		1st order of x
			f	J2(x)		2nd order of x
			f	J3(x)		3rd order of x
			f	J4(x)		4th order of x
			f	J5(x)		5th order of x
			f 	J(n;x)		n-th order of x
Integral Functions:	f	Si(x)		sine integral of x 
			f	Ci(x)		cosine integral of x
			f	Ei(x)		exponential integral of x
			f	li(x)		logarithm integral of x
Gammafunction:		f	gamma(x)	gamma function of x
Stepfunctions:		f	theta(x)	=1 if x>0, else =0
			f	sgn(x)		signum function of x
			f	int(x)	        integer part of x
			f	round(x)	x rounded to next integer value
			f	ceil(x)		x rounded to higher integer value
			f	floor(x)	x rounded to lower integer value
Absolute Values:	f	abs(x)		absolute |x|
			f 	cabs(x;y)	absolute |x+iy|
Miscellaneous:		f	frac(x)		non-integer part of x
			f 	max(x;y)	maximum value of x and y
			f 	min(x;y)	minimum value of x and y	
			f	odd(n)		=1 if n is odd, =0 if n is even
Bitwise and Logical	f	(a) and (b)	bitwise logic AND
	Functions:	f	(a) or (b)	bitwise logic OR
			f	(a) xor (b)	bitwise logic XOR
			f	bnot(a)		bitwise NOT
			f	not(a)		logical NOT
			f	(a) shl (b)	shifts a b bitpositions to the left
			f	a << b		dto.
			f	(a) shr (b)	shifts a b bitpositions to the right	
			f	a >> b		dto.
Relational Operators:	f	x = y		=1 if x is equal to y, else =0
			f	x <> y		=1 if x is not equal to y, else =0
			f	x <= y		=1 if x is less or equal to y, else =0
			f	x < y		=1 if x is less than y, else =0
			f	x >= y		=1 if x is greater or equal to y, else =0
			f	x > y		=1 if x is greater than y, else =0
Properties of complex	c	abs(z)		absolute |z|
	numbers:	c	arg(z)		argument (phase) of z
			c	re(z)		real part of z
			c	im(z)		imaginary part of z
			c	CC(z)		complex conjugate of z
			c	~z		complex conjugate of z
IF- Function:		f	if(c;x;y)	if condition c=1 then x, else if c=0 then y
User Function:		fc	userfct(x)	user implemented function
Mathematical Constants:	fc	pi		circumference/diameter of circle
			fc	e		base of natural logarithms
			fc	C		Euler's constant
			f	TRUE		logical value 1.0
			f	FALSE		logical value 0.0
                        c	i		imaginary unit, sqrt(-1)        
			f	NaN		not a number (aborts evaluation)


	Marianne H. Goeltl-Schuberth                                 