home *** CD-ROM | disk | FTP | other *** search
/ Power-Programmierung / CD1.mdf / magazine / pas_nl / shcmplx / shcmplx.doc next >
Text File  |  1991-03-08  |  13KB  |  597 lines
  1.  
  2.  
  3.  
  4.                                      ShCmplx
  5.  
  6.             A Complex Arithmetic Unit for Turbo Pascal 5.0 and above.
  7.  
  8.                                        by
  9.  
  10.                        W. G. Madison and Associates, Ltd.
  11.                                8425 Greenbelt Road
  12.                                   P.O. Box 898
  13.                                Greenbelt, MD 20770
  14.                                   (301)552-7234
  15.                                   CIS 73240,342
  16.  
  17.                        Copyright 1991 Madison & Associates
  18.                                All Rights Reserved
  19.  
  20.           This unit and the associated .DOC and TEST*.*  files  may be
  21.           freely copied  and distributed, provided only that no fee is
  22.           charged for the package beyond a nominal copying charge, and
  23.           provided that the package is distributed IN  UNALTERED FORM.
  24.           The sole  exception to this latter restriction is that bona-
  25.           fide clubs and user groups may append text  material  to the
  26.           documentation  file, provided that any material appended  is
  27.           clearly identified  as to its source, its beginning, and its
  28.           end.
  29.  
  30.  
  31.      INTRODUCTION
  32.           ShCmplx is a complex arithmetic unit for Turbo Pascal, version 5
  33.      or higher. It provides for the basic binary arithmetic functions
  34.      (addition, subtraction, multiplication, division), plus the raising of
  35.      a complex number to a real power. Conversion functions are provided to
  36.      convert between a complex number represented in Cartesian form and one
  37.      represented in polar form. Finally, provision is made to convert a
  38.      complex number in Cartesian form to a string; or a complex in polar
  39.      form to a string expressing the angle either in degrees or in radians.
  40.  
  41.           All of the described functionality is available as a suite of
  42.      Pascal functions. All except the string conversion routines are also
  43.      available as Pascal procedures.
  44.  
  45.           "HEY, WAIT A MINUTE!" say you, sagely. "Complex numbers are
  46.      composed of two real numbers. Thus, a complex smells like it is
  47.      inherently a record structure. And Pascal functions can only return
  48.      simple data types - no structured types."
  49.  
  50.           "You get a gold star on your forehead," say I. "But we're gonna
  51.      make use of the fact that Pascal functions can also return pointer
  52.      values."
  53.  
  54.           What this means in practice is that type complex, in this
  55.      package, is not defined as
  56.  
  57.  
  58.  
  59.                type
  60.                  Complex = record
  61.                              Re,
  62.                              Im : ComplexElement;
  63.                              end;
  64.  
  65.      but, rather, as
  66.  
  67.                type
  68.                  ComplexBaseType = record
  69.                                      Re,
  70.                                      Im  : ComplexElement;
  71.                                      end;
  72.                  Complex         = ^ComplexBaseType;
  73.  
  74.  
  75.           Thus, if we had an expression which we wished to evaluate - for
  76.      example:
  77.  
  78.                                 A = A + B + C + D
  79.  
  80.      this is able to be evaluated (where CAddF is the function name for
  81.      complex addition) as:
  82.  
  83.                      A^ := CAddF(CAddF(A, B), CAddF(C, D))^;
  84.  
  85.      which is the equivalent of (with the pointers de-referenced)
  86.  
  87.                             A := ((A + B) + (C + D));
  88.      or
  89.                      A^ := CAddF(A, CAddF(B, CAddF(C, D)))^;
  90.  
  91.      which is the equivalent of (again, with the pointers de-referenced)
  92.  
  93.                             A := (A + (B + (C + D)));
  94.  
  95.      and the result of this calculation can be displayed using either
  96.  
  97.                            WriteLn(Cmp2Str(A, 8, 4));
  98.      or
  99.             WriteLn(Cmp2Str(CAddF(CAddF(A, B), CAddF(C, D)), 8, 4));
  100.  
  101.      where the "8, 4" in each case carry the same significance as the
  102.      parameters used in printing real quantities; specifically, the total
  103.      field width and number of places to the right of the decimal point (in
  104.      this case, for each numeric component).
  105.  
  106.           Note that
  107.  
  108.                                 A := CAddF(B, C);
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.                                      - 2 -
  116.  
  117.  
  118.  
  119.      is normally not what you would want. This would assign the returned
  120.      pointer value to the pointer variable 'A', rather than assigning the
  121.      complex value pointed to by the returned pointer to the element
  122.      pointed to by 'A', which you would get by writing
  123.  
  124.                                A^ := CAddF(B, C)^;
  125.  
  126.           This type of error is, unfortunately, not detectable by the
  127.      Pascal run-time system. Also, I can't detect it (even at my diabolical
  128.      cleverest.) So you need to be careful that you don't do it to
  129.      yourself.
  130.  
  131.           A test program (TESTCMPX) is included with the distribution set,
  132.      in both source and executable form. Study it for ideas and specifics
  133.      of how to use the various functions.
  134.  
  135.  
  136.        {===========================================================}
  137.  
  138.  
  139.      TYPES AND CONSTANTS
  140.  
  141.      type
  142.        ComplexElement  = extended;
  143.        ComplexBaseType = record
  144.                            Re,
  145.                            Im  : ComplexElement;
  146.                            end;
  147.        Complex         = ^ComplexBaseType;
  148.  
  149.  
  150.  
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.                                      - 3 -
  176.  
  177.  
  178.  
  179.      PROCEDURE AND FUNCTION CALLS
  180.           In the following, where EXAMPLES are not shown, they may be found
  181.      in the file TestCmpx.PAS.
  182.      _____________________________________
  183.  
  184.      C2P
  185.  
  186.      Declarations:
  187.      procedure C2P(A : Complex; var Result : Complex);
  188.      function C2PF(A : Complex) : Complex;
  189.  
  190.      Purpose:
  191.           Transforms a complex in Cartesian form into polar form.
  192.  
  193.      Examples:
  194.           CpPwrR(C2PF(MyCmpx), 3.0, MyCmpxCubedPolar);
  195.  
  196.      Comments:
  197.           The magnitude will be stored in Result^.Re and the angle
  198.      (expressed in radians) in Result^.Im
  199.  
  200.      See Also:
  201.           P2C
  202.  
  203.      _____________________________________
  204.  
  205.      CABS
  206.  
  207.      Declarations:
  208.      procedure CAbs(A  : Complex; var Result : ComplexElement);
  209.      function CAbsF(A  : Complex)  : ComplexElement;
  210.  
  211.      Purpose:
  212.           Returns the absolute value of a complex number.
  213.  
  214.      Examples:
  215.           ∙∙∙
  216.           MyCmpx^.Re := 3.0;
  217.           MyCmpx^.Im := 4.0;
  218.           ∙∙∙
  219.           WriteLn(CAbs(MyCmpx):4:1);    {will display 5.0}
  220.  
  221.      Comments:
  222.  
  223.      See Also:
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.                                      - 4 -
  236.  
  237.  
  238.  
  239.      _____________________________________
  240.  
  241.      CADD
  242.  
  243.      Declarations:
  244.      procedure CAdd(A, B : Complex; var Result : Complex);
  245.      function CAddF(A, B : Complex) : Complex;
  246.  
  247.      Purpose:
  248.           Returns the sum of two complex numbers A + B.
  249.  
  250.      Examples:
  251.  
  252.      Comments:
  253.  
  254.      See Also:
  255.           CSub      CMul      CDiv
  256.  
  257.      _____________________________________
  258.  
  259.      CCONJ
  260.  
  261.      Declarations:
  262.      procedure CConj(A : Complex; var Result : Complex);
  263.      function CConjF(A : Complex) : Complex;
  264.  
  265.      Purpose:
  266.           Returns the complex conjugate of a complex number.
  267.  
  268.      Examples:
  269.  
  270.      Comments:
  271.           Recall that if a complex number A = R + Ii, then the complex
  272.      conjugate of A is R - Ii.
  273.  
  274.      See Also:
  275.  
  276.  
  277.  
  278.  
  279.  
  280.  
  281.  
  282.  
  283.  
  284.  
  285.  
  286.  
  287.  
  288.  
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.                                      - 5 -
  296.  
  297.  
  298.  
  299.      _____________________________________
  300.  
  301.      CDIV
  302.  
  303.      Declarations:
  304.      procedure CDiv(A, B : Complex; var Result : Complex);
  305.      function CDivF(A, B : Complex) : Complex;
  306.  
  307.      Purpose:
  308.           Returns the quotient of two complex numbers A / B.
  309.  
  310.      Examples:
  311.  
  312.      Comments:
  313.           CAbsF(B) must be > 0.0. If CAbsF(B) <= 0.0, CmplxError will
  314.      return -1.
  315.  
  316.      See Also:
  317.           CAdd      CMul      CSub
  318.  
  319.      _____________________________________
  320.  
  321.      CMP2STR
  322.  
  323.      Declarations:
  324.      function Cmp2Str(A : Complex; Width, Places : byte) : string;
  325.  
  326.      Purpose:
  327.           Converts a complex value to a string of the form (Re + Im i).
  328.  
  329.      Examples:
  330.  
  331.      Comments:
  332.           The Width and Places arguments have the same significance that
  333.      they do in the system procedure STR, and are applied individually to
  334.      both the REAL and IMAGINARY parts.
  335.  
  336.      See Also:
  337.           CmpP2Str       CmpP2StrD
  338.  
  339.  
  340.  
  341.  
  342.  
  343.  
  344.  
  345.  
  346.  
  347.  
  348.  
  349.  
  350.  
  351.  
  352.  
  353.  
  354.  
  355.                                      - 6 -
  356.  
  357.  
  358.  
  359.      _____________________________________
  360.  
  361.      CMPLXERROR
  362.  
  363.      Declarations:
  364.      function CmplxError  : integer;
  365.  
  366.      Purpose:
  367.           Returns execution error conditions for the package.
  368.  
  369.      Examples:
  370.  
  371.      Comments:
  372.           Return = 0     OK
  373.                    -1    Attempt to divide by zero (CDiv)
  374.                    -2    Real part of complex is zero (CpPwrR)
  375.  
  376.      See Also:
  377.  
  378.      _____________________________________
  379.  
  380.      CMPP2STR
  381.  
  382.      Declarations:
  383.      function CmpP2Str(A : Complex; Width, Places : byte) : string;
  384.  
  385.      Purpose:
  386.           Converts a complex in polar form to a string with the angle
  387.      expressed in radians.
  388.  
  389.      Examples:
  390.  
  391.      Comments:
  392.           The Width and Places arguments have the same significance that
  393.      they do in the system procedure STR, and are applied individually to
  394.      both the MAGNITUDE and ANGLE parts.
  395.  
  396.      See Also:
  397.           Cmp2Str        CmpP2StrD
  398.  
  399.  
  400.  
  401.  
  402.  
  403.  
  404.  
  405.  
  406.  
  407.  
  408.  
  409.  
  410.  
  411.  
  412.  
  413.  
  414.  
  415.                                      - 7 -
  416.  
  417.  
  418.  
  419.      _____________________________________
  420.  
  421.      CMPP2STRD
  422.  
  423.      Declarations:
  424.      function CmpP2StrD(A : Complex; Width, Places : byte) : string;
  425.  
  426.      Purpose:
  427.           Converts a complex in polar form to a string with the angle in
  428.      degrees.
  429.  
  430.      Examples:
  431.  
  432.      Comments:
  433.           The Width and Places arguments have the same significance that
  434.      they do in the system procedure STR, and are applied individually to
  435.      both the MAGNITUDE and ANGLE parts.
  436.  
  437.      See Also:
  438.           Cmp2Str        CmpP2Str
  439.  
  440.      _____________________________________
  441.  
  442.      CMUL
  443.  
  444.      Declarations:
  445.      procedure CMul(A, B : Complex; var Result : Complex);
  446.      function CMulF(A, B : Complex) : Complex;
  447.  
  448.      Purpose:
  449.           Returns the product of two complex numbers A * B.
  450.  
  451.      Example:
  452.  
  453.      Comments:
  454.  
  455.      See Also:
  456.           CAdd      CDiv      CSub      RxC
  457.  
  458.  
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469.  
  470.  
  471.  
  472.  
  473.  
  474.  
  475.                                      - 8 -
  476.  
  477.  
  478.  
  479.      _____________________________________
  480.  
  481.      CPPWRR
  482.  
  483.      Declarations:
  484.      procedure CpPwrR(A : Complex; R : ComplexElement;
  485.                                              var Result : Complex);
  486.      function CpPwrRF(A : Complex; R : ComplexElement) : Complex;
  487.  
  488.      Purpose:
  489.           Raises a complex (in polar form) to a real power.
  490.  
  491.      Examples:
  492.  
  493.      Comments:
  494.           If A^.Re = 0, CmplxError will return -2 and Result will be 0 + 0i
  495.  
  496.      See Also:
  497.  
  498.      _____________________________________
  499.  
  500.      CSUB
  501.  
  502.      Declarations:
  503.      procedure CSub(A, B : Complex; var Result : Complex);
  504.      function CSubF(A, B : Complex) : Complex;
  505.  
  506.      Purpose:
  507.           Returns the difference between two complex numbers A - B.
  508.  
  509.      Examples:
  510.  
  511.      Comments:
  512.  
  513.      See Also:
  514.           CAdd      CDiv      CMul
  515.  
  516.  
  517.  
  518.  
  519.  
  520.  
  521.  
  522.  
  523.  
  524.  
  525.  
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532.  
  533.  
  534.  
  535.                                      - 9 -
  536.  
  537.  
  538.  
  539.      _____________________________________
  540.  
  541.      P2C
  542.  
  543.      Declarations:
  544.      procedure P2C(A : Complex; var Result : Complex);
  545.      function P2CF(A : Complex) : Complex;
  546.  
  547.      Purpose:
  548.           Transforms a complex in polar form into Cartesian form. The
  549.      magnitude is stored in A^.Re and the angle (expressed in radians) in
  550.      A^.Im.
  551.  
  552.      Examples:
  553.  
  554.      Comments:
  555.  
  556.      See Also:
  557.           C2P
  558.  
  559.      _____________________________________
  560.  
  561.      RXC
  562.  
  563.      Declarations:
  564.      procedure RxC(A : ComplexElement; B : Complex;
  565.                                              var Result : Complex);
  566.      function RxCF(A : ComplexElement; B : Complex) : Complex;
  567.  
  568.      Purpose:
  569.           Returns the complex product of a real and a complex.
  570.  
  571.      Examples:
  572.  
  573.      Comments:
  574.           This is simply a special case of CMul, in which the imaginary
  575.      part of one of the factors is zero. It occurrs with sufficient
  576.      frequency, however, to warrent separate treatment.
  577.  
  578.      See Also:
  579.           CMul
  580.      _____________________________________
  581.  
  582.  
  583.  
  584.  
  585.  
  586.  
  587.  
  588.  
  589.  
  590.  
  591.  
  592.  
  593.  
  594.  
  595.                                      - 10 -
  596.  
  597.