













                               3micalc 0m1mversion 20m.1m1 



                     0mA complex-number expression language 

                         (C) 1991,1992 Martin W.Scott 
                             All Rights Reserved.  



                                  User Guide 









































     icalc                         User Guide                         icalc


     1mIntroduction 

          0m3micalc  0mis  a  terminal-based  calculator;  the  1mi 0mstands for
          1mimaginary0m, denoting the fact that the calculator works  with
          complex numbers.  There are many calculator programs for the
          Amiga, but  to  my knowledge, none with this ability.  3micalc
          0malso performs real (normal) calculations too,  and  you  can
          completely ignore the complex number facility if you wish.  

          Version 2.0 of icalc introduced major additions, effectively
          making 3micalc  0ma  C-like  programming language.  However, you
          can completely ignore these extensions if you shy away  from
          programming.    In   light   of   this,  the  more  advanced
          documentation is kept separate from the simple instructions,
          in  the  'Advanced  Guide',  which  covers  such  topics  as
          number-bases, programming constructs, arrays and scripts.  


     1mComplex Numbers 

          0mA  complex number is made up of two components: a real part,
          and an imaginary part.  The imaginary part is  just  a  real
          number  multiplied by the special number i, which is defined
          to be the square root of -1.  Thus, i*i = -1. This  may  all
          seem very artificial, but it's not; complex numbers exist as
          surely  as  real  numbers  do  (or  don't, depending on your
          mathematical philosophy).  However, real numbers  seem  more
          tangible  to  us,  since  we  use them (or approximations to
          them) in our everyday life.  It is not the purpose  of  this
          guide  to  teach you anything about complex numbers - if you
          don't know about them, you probably don't need  to,  but  if
          you  do  any  numerical  work,  you will probably still find
          3micalc 0museful, because real numbers are a subset  of  complex
          numbers,  and  can thus be manipulated by this program as in
          an ordinary calculator-type program.  Don't be put off  -  I
          hardly  ever  need  to use complex numbers - I just like the
          facility to be there for the odd  occasion  when  I  do  use
          them.  

          In what follows, examples are indented.  Things you type are
          preceded  by  a  '>'  prompt  sign, and output from 3micalc 0mis
          further indented.  


     1mExpressions 

          0m3micalc 0maccepts expressions in the  usual  form  for  computer
          expressions, i.e.    multiplication must be explicitly shown
          by '*', and function arguments enclosed within  parentheses.
          The  exception  to  this is the method of inputing imaginary
          parts of complex numbers.  If you want to enter the number 3
          + 4i, you can type either 

                  > 3+4i

          or 

                  > 3+4*i


     icalc                            -2-                       version 2.1


     icalc                         User Guide                         icalc



          but 3mnot 

                  0m> 3+i4        # this won't do...

          since this would give an ambiguous grammar - is  it  i*4  or
          the variable "i4"?  

          In   almost   all   circumstances,  the  algebraic  "4i"  is
          preferred, but there is one exception, exponentation "^". If
          you want 3*i^3, you must type 

                  > 3*i^3

          and not 

                  > 3i^3

          The former gives the correct result, -3i, whilst the  latter
          gives  -27i.  This  is  because  the  grammar sees "3i" as a
          number   in   its   own   right,   and   not   an   implicit
          multiplication.  

          NB:  Implicit  multiplication (leaving out '*' sign) is only
          recognised in the case of a numerical multiple of i.  

          See the  appendices  for  the  complete  list  of  commands,
          operators,   constants  and  builtin  functions  that  3micalc
          0msupports.  

          Expressions are separated by newlines  or  semi-colons  ';'.
          You may also split an expression over multiple lines using a
          backslash  '\'  to  indicate  continuation to the next input
          line.  Comments are introduced by '#', and the rest  of  the
          input line  is  ignored.   You may also place comments after
          backslashes.  


     1mSample Expressions 

          0mBelow are a few examples of what 3micalc 0mwill accept.  

                  > x=4     # an assignment statement

          assigns to variable x the value 4.  

                  > # and now, two statements separated by a semi-colon
                  > sqr(x); x*sqr(x);

          displays the values 16 and 64 (sqr(x)  returns  x*x).    The
          next  example  demonstrates  a  problem  inherent in machine
          calculations: 

                  > 2*sin(x)*cos(x) - sin(2*x)

          displays the value -2.22044604925e-16. The answer should  be
          0, and indeed is very close to that.  The inaccuracy results
          because  each  term has a value as close to the actual value


     icalc                            -3-                       version 2.1


     icalc                         User Guide                         icalc


          as the computer's internal  representation  of  numbers  can
          hold  (see the Advanced Guide for a small discussion of this
          particular case).  

          You can change  the  number  of  significant  figures  3micalc
          0mdisplays by the prec() function - see Appendix 4.  


     1mStarting icalc 

          0m3micalc 0mmay be started from either the CLI or Workbench.  Once
          started, 3micalc 0mwill process the file whose name is contained
          in  the  environment  variable  ICALCINIT, defaulting to the
          file "s:icalc.init" if no environment variable is  declared.
          This initialization file may be used to extend the functions
          available in  3micalc.    0mA  sample  file  is  given  in the S
          directory of this distribution.  If running  under  AmigaDOS
          1.3,  it  is  recommended  that you use NEWCON: or ConMan to
          provide editing  and  history  facilities.    For  users  of
          AmigaDOS  2.0,  the  normal CON: window has these facilities
          built-in, and you may also add a close gadget.  

       CLI Usage 

          The synopsis for icalc is 

                  icalc [file-list]

          where file-list is a list of input files.  3micalc  0mwill  read
          (process) the files in the list and exit.  If a file-list is
          specified, 3micalc 0mwill assume that you do not wish to use the
          program interactively.  If you do, you should specify one of
          the files as a dash "-"; this is taken to mean "use standard
          input".    If   no  file-list  is  given,  3micalc  0mstarts  an
          interactive session.  You can obviously redirect output to a
          file if you wish (and redirect input from a file,  but  this
          is generally  unnecessary).    For example, if you wanted to
          use definitions contained in a file  called  "stat.ic",  and
          then type some expressions in at the terminal, you would use 

                  icalc stat.ic -

          to start  the  program.  Because the program makes extensive
          use of recursion, I recommend you use a stack size of  about
          20K when running 3micalc.  

       0mWorkbench Usage 

          To  start  3micalc 0mfrom the Workbench, simply double-click its
          icon.   You  may  also  pass  arguments  (definition/command
          files)  to 3micalc 0min the usual Workbench manner (shift-select
          etc.).  3micalc 0mwill then  open  a  window  on  the  Workbench
          screen for  an  interactive  session.    You can specify the
          window to be opened by modifying the WINDOW tooltype  (click
          once on the 3micalc 0micon, and select "Info" from the Workbench
          menu).  By default, this is a CON: window.  (As noted above,
          AmigaDOS 1.3 users could alter this to a NEWCON: window).  



     icalc                            -4-                       version 2.1


     icalc                         User Guide                         icalc


          You  may  also  set  the default tool of a definition file's
          project icon to be 3micalc.  0mThen simply double  clicking  the
          project  icon  will  launch  3micalc  0mand  read the definition
          file.  Remember, however, to set the project icon's stack to
          20000, or you may get a stack overflow error.  

       Exiting icalc 

          To end an interactive session of 3micalc 0m(from either  CLI  or
          Workbench) use  the  command "quit" or "exit".  You can also
          type ^\ (press the control key and '\' simultaneously).   If
          running  under  AmigaDOS  2.0,  you  can  use  the  window's
          close-gadget.  


     1mVariables 

          0mVariables in 3micalc 0mcan be named arbitrarily, as long  as  no
          name  conflicts  with a pre-defined symbol name, such as sin
          or PI. The standard conventions apply: the  first  character
          must  be  a  letter  or  underscore, followed by a string of
          letters, digits and underscores.  Case IS significant.  

          Variables are introduced by using them;  If  a  variable  is
          used  before  it  has been initialized (i.e. has had a value
          assigned to it), 3micalc 0mwill warn the user and use the  value
          zero.  Assignments can appear anywhere in an expression, and
          are  in  fact  expressions  in  their  own  right (as in the
          programming language C).  So, you can do things like 

                  > apple = banana = apricot = 34

          to assign the value  34  to  all  these  variables.    Since
          assignments   are   expressions,   their   value  being  the
          assignment value, you can also do 

                  > apple = sqr(banana = 12)

          which assigns the value 12 to "banana", and 144 to  "apple".
          You can of course assign new values to existing variables.  


     1mConstants and ans 

          0m3micalc 0mcomes  with  several  predefined  constants, e.g.  PI,
          GAMMA etc, which by convention are all in upper-case.    You
          cannot assign a new value to a constant.  There is a special
          constant,  "ans",  which isn't really a constant at all, but
          is made so to prevent assignments to it.  "ans" contains the
          value of the previously  evaluated  expression,  and  so  is
          useful when splitting a calculation up into smaller chunks.  

                  > 1 + 2 + 3
                          6
                  > ans * 12
                          72

          You can  also  use  it for recursive formulas.  For example,


     icalc                            -5-                       version 2.1


     icalc                         User Guide                         icalc


          the logistic equation xnext = rx(1-x) for parameter r = 3.5,
          initial x = 0.4 could be iterated as follows: 

                  > r = 3.5; 0.4          # initialize r and ans
                          3.5
                          0.4
                  > r*ans*(1-ans)
                          0.84
                  > r*ans*(1-ans)
                          0.4704
                  > r*ans*(1-ans)
                          0.87193344
                  > r*ans*(1-ans)
                          0.39082930673

          and so on.  Of course, you needn't use "ans" here; you could
          just use assignments to "x", but it illustrates  the  point.
          Note   that   once   the   necessary   variables  have  been
          initialised, the same expression  is  evaluated  repeatedly.
          Thus,  if  you  are using a window with history capabilities
          you can save a lot of typing by pressing the up-arrow.  

          There are other ways to  perform  repeated  calculations  in
          3micalc.   0mYou  can use so-called Special functions (explained
          below), or the C-style looping constructs described  in  the
          'Advanced Guide'.  


     1mBuiltin Functions 

          0m3micalc  0mcomes  with  many builtin functions, for example sin,
          cos, sqrt, exp, ln etc.  There are  some  special  functions
          for complex  numbers  too,  namely  Im,  Re, arg, norm.  All
          functions take real or complex arguments, which can  be  any
          expression,  although  in  some  cases,  the complex part is
          discarded.  Consider 

                  > sin(12-3i)
                          -5.40203477452 - 8.45362341558 i
                  > asin(ans)
                          -0.56637061436 - 3 i
                  > sin(ans)
                          -5.40203477452 - 8.45362341558 i

          Here we see a property of inverse  trigonometric  functions,
          their  many-valuedness, due to their periodicity on the real
          line.   The  function  asin  returns  a  value  in  its  PVR
          (principal  value  range) as do all many-valued functions in
          3micalc.  0mSee the 'Advanced Guide' for  exact  definitions  of
          PVRs of the inverse trigonometric functions used in 3micalc.  

          0mOther  functions  owe their many-valuedness to the fact that
          the argument of a complex number is 2*PI-periodic. In  3micalc
          0mthe argument always falls in the range -PI < arg <= PI.  

          Another  thing  to  bear in mind if you're not using complex
          numbers is that expressions like 



     icalc                            -6-                       version 2.1


     icalc                         User Guide                         icalc


                  > ln(-1)

          return a value, 3.14159265359*i (PI*i) in this case.    (The
          natural  logarithm  onto  the real line is defined for range
          (0, +infinity)).  


     1mUser0m-1mdefined Functions 

          0mUser-defined  functions  give  3micalc  0mits  flexibility   and
          power.   Any  function  that  can  be  stated  as  a  normal
          expression (or list of expressions) may  easily  be  defined
          and used  like  a  builtin function.  In this document, only
          very simple function definitions are explained.    Functions
          more  akin  to  those in a computer program are described in
          the 'Advanced Guide'.  

          Functions are defined  using  the  'func'  keyword,  in  the
          following manner: 

                  func <name> ( <parameter-list> ) = <expr>

          so to define the function f(z) = sin(sqrt(z)), simply type 

                  > func f(z) = sin(sqrt(z))

          Note  that  z  is  3mlocal  0mto  the  function,  not  a  global
          variable.  Thus, if z has been defined as a variable  before
          defining f(z),  it  is  unaltered  when  you call f(z).  The
          standard initiation file 'icalc.init' contains  many  simple
          function  definitions,  and  you  may find it instructive to
          examine it.  

          Multi-parameter functions may also be defined.  For example,
          the volume of a right-circular cone is given by the formula 

                  volume = 1/3*PI*sqr(r)*h

          where r is the radius of the base, and h is  the  height  of
          the cone.  We can define a function to compute the volume as
          follows: 

                  > func conevol(r,h) = 1/3*PI*sqr(r)*h
                  > conevol(1,3)
                          3.14159265359

          It  is  also  possible  (though  of  limited use) to declare
          functions that   take   no   parameters.      Examples    of
          multi-parameter functions are given in the sample definition
          files.  

          NB: As with most programming languages, don't write circular
          definitions;  3micalc  0mdoes  not detect them, and will swiftly
          run out of stack space.  






     icalc                            -7-                       version 2.1


     icalc                         User Guide                         icalc


     1mSpecial Functions 

          0mCertain  builtin  functions  in  3micalc  0mare  called  3mspecial
          0mbecause of the way they use their arguments.  Normally, when
          you `call' a function, its arguments are first evaluated and
          then the   function  is  called.    With  special  functions
          however, the arguments are not evaluated;  this  means  that
          the  expressions  themselves (and not just their values) can
          be used by the function in a number of ways.  

          Special functions were introduced in version 1.1  of  3micalc.
          0mbut  since  version  2.0, they have become largely redundant
          (with one or two exceptions) due to the C-style  programming
          constructs added.    However,  for non-programmers or people
          who don't wish to use 3micalc 0mas a programming language,  they
          do  provide a means for performing several common operations
          which would otherwise prove difficult.  

          Some special functions take integers as  arguments;  if  you
          supply  an  expression with a non-integral value, this value
          will  be  stripped  of  its  imaginary  component,  and  the
          remaining  real  number  rounded  to  the  nearest  integer.
          Currently, the special functions are as follows.  

       Sum(var,upto,expr) 

          This command calculates finite sums.  The variable `var'  is
          the index  of summation, with an optional assignment.  While
          the value of the index is less than or equal to the value of
          the upto argument, the value of expr is added to an internal
          summation variable, which is initially zero.  Examples  will
          help to clarify usage.  

          To  evaluate  the  sum  of  the  first  100  natural numbers
          (naively) we could do 

                  > Sum(n=1,100,n)

          which gives the answer as  5050  (which  is  100/2*(100+1)).
          Note the  initial assignment of 1 to n.  If no initial value
          is specified, a value of zero is assumed (and  the  user  is
          notified of  this).  When a summation is complete, the index
          variable holds a value 1 greater than the value of upto.  We
          can also use Sum() to  provide  approximations  to  infinite
          sums.  

                  > Sum(n=1, 100, 1/sqr(n)) 
                          1.63498390018

          Using  the  fact  that n will now hold the value 101, we can
          continue the summation to 200 by the following: 

                  > ans + Sum(n, n+99, 1/sqr(n))
                          1.63994654601

          and continue to obtain closer answers by repeating the  last
          line, 



     icalc                            -8-                       version 2.1


     icalc                         User Guide                         icalc


                  > ans + Sum(n, n+99, 1/sqr(n))
                          1.6416062829

          which is getting there (the infinite series sums to PI^2/6 =
          1.64493406685).   One  last  example, to evaluate the sum of
          the all even numbers upto 100.  

                  > Sum(n=1, 50, 2*n)
                          2550


       Prod(var,upto,expr) 

          This command calculates finite products, in an analogous way
          to the Sum() special function.   Examples  will  demonstrate
          its use.  

                  > Prod(n=1, 10, n)

          calculates  10!, which is 3628800. We can also use Prod() to
          investigate  infinite  products,  although  care  should  be
          taken.  Consider Wallis's product for PI/2: 

                  PI   224466...
                  -- = ---------------
                  2    133557...

          Here  the  product  is 2/1 * 2/3 * 4/3 * 4/5 * ... and so we
          must  find  a  method  of  producing  the   numerators   and
          denominators from  an  index.  It is easiest to evaluate the
          product in  pairs  of  terms.    Thus,  for  each  term  our
          numerator  will  be  sqr(2*n),  and  our denominator will be
          (2*n-1)*(2*n+1) = sqr(2*n)-1.  Note that sqr(2*n) appears in
          both the  numerator  and  denominator.    We  can  therefore
          optimise  the  calculation  by using a temporary variable to
          hold this value.  We proceed as follows: 

                  > Prod(n=1, 100, (t = sqr(2*n))/(t-1))
                          1.56689374531
                  > ans * Prod(n, n+99, (t = sqr(2*n))/(t-1))
                          1.56883895048
                  > ans * Prod(n, n+99, (t = sqr(2*n))/(t-1))
                          1.56949005194


       every(var,upto,expr) and vevery(var,upto,expr) 

          These functions preform more general iterations  than  Sum()
          and Prod().    They  return the value of the last expression
          evaluated, ie.   expr  evaluated  when  var  =  upto.    The
          difference  between  every() and vevery() is that the latter
          produces verbose output - it prints the value of  the  index
          and the result of the expression for every iteration.  

          Example:   evaluate   sin(sin(...(sin(z))...))   with  sin()
          applied 10 times.  Here we'll take z to be 1-i.  

                  > last = 1-i; every(n=1, 10, last = sin(last))


     icalc                            -9-                       version 2.1


     icalc                         User Guide                         icalc


                          0.51856951608 - 0.01039404248 i

          Although every() and vevery() are useful in some situations,
          most iterations are more easily performed by using Sum() and
          Prod(). 

       multi(expr1, expr2, ... , exprN) 

          This special function still exists for upward compatability,
          but it is syntactically  equivalent  to  the  C-style  block
          introduced with version 2.0: 

                  { expr1 ; expr2 ; ... ; exprN; }

          (In  fact,  the semicolons can be omitted and new-lines used
          instead - see the 'Advanced Guide').  

          The value of a call to multi or a block expression  is  that
          of the  last  expression evaluated, namely exprN.  If output
          has not been switched off with the 'silent' command, use  of
          a block  will  print  the  result of it's last argument.  In
          order to print the results of other expressions, the builtin
          function print() is supplied.  print() takes  one  argument,
          prints  it  to  the  display,  and returns its argument as a
          result.  In this way, expressions can appear to return  more
          than one result.  

          An   example:  write  a  function  that  converts  Cartesian
          coordinates into polar form, returning the radius and  angle
          in  degrees,  and setting the variables r and theta to these
          values.  


                  > func rec2pol(x,y) = {
                  >      r=print(sqrt(x*x+y*y))
                  >      theta=DEG*arg(x+i*y)
                  > }

                  > rec2pol(3,4)
                          5
                          53.1301023542


          Note the use of  complex  argument  to  obtain  the  correct
          quadrant.  


     1mOther features 

          0m3micalc  0mnow  has  a  full  complement  of  common programming
          constructs (C-style) such as if-else, for-loops etc.    This
          necessitated  the  addition  of  relational  operators >=, >
          etc.  and logical operators &&, !  etc.  

          In  order  to  make  the  range   of   applications   wider,
          single-dimensional  arrays may also be used in a very simple
          manner.  



     icalc                            -10-                      version 2.1


     icalc                         User Guide                         icalc


          User-function arguments may be arrays, pointers to variables
          and  even  expressions  (in  the  sense  of  expressions  to
          'special'  functions)  although in this area, syntax differs
          considerably from the C programming language.  

          All these and other extensions are very  useful  facilities,
          but non-essential  for  simple  work.  They are described in
          detail in the 'Advanced Guide'.  


     1mCommands 

          0m3micalc 0mhas a few commands to make life easier.   One  or  two
          commands take a string as an argument.  Strings are enclosed
          in double-quotes,  e.g.   "hello", although you may drop the
          trailing quote if  you  wish.    It  should  be  noted  that
          commands   may   NOT   be  used  within  function  or  block
          declarations.  

       bye 
       quit 
       exit 
          not surprisingly, these commands terminate 3micalc.  

       0msilent 
          stops generation of any further output.  However, errors and
          warnings are  still   displayed.      It   is   useful   for
          initialization files containing lots of definitions.  

       verbose 
          restores generation of output.  

       help 
          reminds you what other commands are available.  

       vars 
          lists  all currently defined variables and their values, and
          allocated arrays.  

       consts 
          lists all predefined constants and their values.  

       builtins 
          lists all built-in functions  available,  including  special
          functions.  

       functions 
          lists  all  user-defined  functions,  with  their  parameter
          lists.  

       echo <string> 
          simply prints given string (like Shell echo command).  

       pwd 
          prints the current directory of 3micalc.  

       0mcd <new-directory> 
          changes current directory of 3micalc.  0mEg. cd "s:" 


     icalc                            -11-                      version 2.1


     icalc                         User Guide                         icalc



       exec <command-string> 
          executes command as if it had been typed  in  a  Shell.  Eg.
          exec "ed  s:icalc.init".    If  3micalc  0mis  started  from the
          Workbench,  output  from  exec'd  commands  will   only   be
          displayed  if you are using AmigaDos 2.0 or above (this is a
          compiler/OS bug).  

       read <file> 
          reads and evaluates contents of named file (in  same  manner
          as  if  passed  on  command-line  to 3micalc 0mor as a Workbench
          argument.  

       writevars <file> 
          dumps all variables defined in  current  session  (including
          arrays)  to  specified file, for subsequent restoration with
          the read  command  at   another   session.      At   present
          user-function  definitions  are  NOT  saved  (and  are never
          likely to  be  in  future  versions).    The  file   is   in
          human-readable form.  

          There  are  a  couple  of  other  commands  detailed  in the
          'Advanced Guide'.  


     1mBugs 

          0mOne major bug was fixed in release 1.1a - the sqrt() builtin
          was  not  returning  values   in   the   correct   quadrant.
          Consequently, the inverse trigonometric functions, which are
          defined using  sqrt(),  broke.  This has now been corrected.
          Thanks to Pierre Ardichvili for pointing this out.  (Version
          1.1a fixed this bug, but wasn't widely  distributed  because
          version 2.0 was (supposedly) imminent.) 

          From  version  2.1, new routines were written to replace the
          ones supplied with  the  SAS/C  compiler  (specifically  the
          scanf  and  printf  "%g"  routines)  thus  removing all bugs
          associated with these routines (such as  printing  "0."  and
          "-0." amongst  others).  Thanks to Eric Rankin for reporting
          the display bugs.  

          I hope that's all the major bugs ironed out, but  there  may
          be the odd little bug in there somewhere -- if you find any,
          PLEASE let me know and I'll try to fix them.  

          If  there's  something  you  hate about 3micalc 0mand would like
          changed, or something you'd love that's not in,  drop  me  a
          line (at the address below), or email me.  


     1mSource 

          0m3micalc  0mwas  written  in  C, and compiled with SAS/C (version
          5.10a). Berkeley Yacc was used to generate the parser.   The
          source  to version 2.1 of 3micalc 0mis available on request, for
          a small fee.  See the 'ReadMe.First'  document  for  further
          details.  


     icalc                            -12-                      version 2.1


     icalc                         User Guide                         icalc


     1mCredits 

          0mThanks  to  the  authors  of  Berkeley  Yacc (it makes these
          things so much easier to write and modify) and to SAS for  a
          (fairly) stable C compiler.  

          Thanks  also  to  Steve Koren for Sksh, and Mike Meyer et al
          for  Mg3;   together   they   make   a   great   development
          environment.  

          Jeremy  McDonald  provided  me with a routine for displaying
          numbers in any base (from 2 to 36) which has  been  used  as
          the  core  of the number-displaying routine used in 3micalc 0m--
          thanks Jeremy!  

          Many of the algorithms used in the sample script-files  that
          come with 3micalc 0mwere based on those in "Numerical Recipes in
          C", by  Press  et  al.   The book is very readable, and well
          worth obtaining if you  use  numerical  algorithms  in  your
          work.  

          This  was  my  first  yacc-based project, and I learnt a lot
          from "The Unix Programming Environment" by  Brian  Kernighan
          and Rob Pike. Their "hoc" taught me a lot about using Yacc.  

          Most  of  all, thanks to those people who have written to me
          regarding icalc, for their comments and contributions.  


     1mDistribution 

          0m3micalc 0mis freeware, copyrighted  software.    This  copyright
          applies to  all  files  in  the 3micalc 0mdistribution.  You are
          permitted to distribute it at only a nominal charge to cover
          costs.  All files should be included unmodified.   Under  no
          circumstances should 3micalc 0mbe sold for profit.  


     1mThe Bottom Line 

          0mAlthough 3micalc 0mis not shareware, contributions would be most
          welcome,  as  I'm a poor student, and have put a lot of work
          into this project.  But they're NOT required - bug  reports,
          praise, suggestions,  neat  programs  etc.  are welcome (and
          indeed encouraged) with or without contribution.  Thanks  to
          those kind people (small in number) who have written to me.  

          I can be contacted via snail mail at: 

                  Martin W. Scott,
                  23 Drum Brae North,
                  Edinburgh, EH4 8AT
                  United Kingdom.

          or you can email me; my address is mws@castle.ed.ac.uk 

          Thanks for  reading  this  far.  The appendices follow; some
          details in them will not have been covered in this document,


     icalc                            -13-                      version 2.1


     icalc                         User Guide                         icalc


          but are explained in the 'Advanced Guide'.  



























































     icalc                            -14-                      version 2.1


     icalc                         User Guide                         icalc


     1mAppendix 1 0m- 1mOperators 0m(1min increasing order of precedence0m) 


          =  +=  -=  *=  /=   assignment
          ?:                  ternary operator 
          ||                  logical or
          &&                  logical and
          ==  !=              equal, not equal
          >  >=  <  <=        greater-than etc.
          +  -                addition, subtraction
          *  /                multiplication, division
          -  !                unary minus, logical not
          ^                   exponentation
          '                   conjugate operator


     1mAppendix 2 0m- 1mConstants 


          0mABASE               index of first element for arrays
          DEG                 Number of degrees in one radian
          E                   exp(1)
          FALSE               0
          GAMMA               Euler's constant, 0.57721566...
          INFINITY            (almost) the largest real number possible 
          LOG10               ln(10)
          LOG2                ln(2)
          PHI                 Golden ratio 1.61803398...
          PI                  4*atan(1) (that's one definition)
          TRUE                1


     1mAppendix 3 0m- 1mKeywords 


          0mfunc                function declaration
          array               (external) array definition
          local               local variable definition
          return              return from function

          if-else             control-flow constructs
          while-do
          do-while                
          for                     
















     icalc                            -15-                      version 2.1


     icalc                         User Guide                         icalc


     1mAppendix 4 0m- 1mBuiltin functions 


          0mParameters are evaluated from left to write.
          Parameters shown:

                  z implies complex number expected,
                  x implies real number expected,
                  n implies integer expected.
                  a implies array identifier expected.

          Conversions will be made if required.

          Functions you think missing below may well be defined in one of
          the support scripts.


          1mSingle0m-1margument functions0m:        

          sin(z)              trigonometric functions
          cos(z)
          tan(z)

          asin(z)             inverse trigonometric functions
          acos(z)
          atan(z)

          sinh(z)             hyperbolic trigonometric functions
          cosh(z)
          tanh(z)

          exp(z)              exponential function
          ln(z)               natural logarithm
          sqr(z)              square
          sqrt(z)             square root

          conj(z)             conjugate (see also ' operator)
          abs(z)              absolute value (sqrt(norm(z))
          norm(z)             not really norm; if z=x+iy, norm(z) = x+y
          arg(z)              principal argument (in (-PI,PI])
          Re(z)               real part of complex number
          Im(z)               imaginary part of complex number

          ceil(x)             ceil of real part (eg. ceil(1.2) = 2)
          floor(x)            floor of real part (eg. floor(1.2) = 1)
          int(x)              return real part rounded to nearest integer
          sgn(x)              sign of real part (eg. sgn(-1.6) = -1)

          time(x)             system time in seconds, less its argument
          print(z)            prints and returns value of its argument
          prec(n)             adjust number of significant figures displayed
          sigzeros(n)         set # of leading zeros considered significant 
          error(n)            abort evaluation with error n
          outbase(n)          print numbers using base-n






     icalc                            -16-                      version 2.1


     icalc                         User Guide                         icalc


          1mArray functions0m:        

          display(a)          display contents of an array
          sizeof(a)           returns number of elements in array
          resize(a,n)         changes dimension of array to new size n
          arraybase(n)        change first index of arrays to n
                              (returns old base)


          1mSpecial functions0m:        

          Sum                 calculate a finite sum
          Prod                calculate a finite product
          every               perform a general iteration quietly
          vevery              perform a general iteration verbosely
          multi               evaluate many expressions (defunct)
          min                 returns minimum real part in parameters
          max                 returns maximum real part in parameters

          min and max take an arbitrary number of arguments.








































     icalc                            -17-                      version 2.1

