home *** CD-ROM | disk | FTP | other *** search
/ Programmer 7500 / MAX_PROGRAMMERS.iso / PASCAL / RMATH.ZIP / MATH.DOC < prev    next >
Encoding:
Text File  |  1990-12-01  |  21.3 KB  |  589 lines
  1. MATH -- a unit of elementary mathematical routines for Turbo
  2.         Pascal versions 4, 5, 5.5, and 6.
  3.  
  4.         Copyright 1990, by J. W. Rider
  5.  
  6. MATH.PAS provides a library of mathematical constants, type
  7. definitions, functions, and procedures for immediate use within
  8. contemporary Turbo Pascal programs (tested with versions 5.5 and
  9. 6). Routines are provided for the following categories:
  10.  
  11.         Numerical rounding and fractioning:
  12.                 ceil, floor, modf, remf, round2, sgn
  13.  
  14.         Binary operators:
  15.                 atan2, fmod, fdiv, frem, hypot, ipow, iroot,
  16.                 max, min, pow, powi, root, round2
  17.  
  18.         Conditional operators:
  19.                 iif
  20.  
  21.         Polynomial evaluation:
  22.                 poly
  23.  
  24.         Exponential and power-raising functions:
  25.                 exp, exp2, exp10, frexp, ipow, iroot, ldexp, pow,
  26.                 powi, pow10, root, sqrt
  27.  
  28.         Logarithmic functions:
  29.                 ln, log, log2, log10
  30.  
  31.         Circular trigonometric functions and inverses:
  32.                 acos, acosd, asin, asind, atan, atan2, atan2d,
  33.                 atand, cosd, sind, tan, tand
  34.  
  35.         Degree/radian conversions for circular trig:
  36.                 deg2dms, deg2rad, dms2deg, dms2rad, rad2deg,
  37.                 rad2dms
  38.  
  39.         Hyperbolic trigonometric functions and inverses:
  40.                 acosh, asinh, atanh, cosh, sinh, tanh
  41.  
  42.  
  43. Some caveats:
  44.  
  45.         MATH.PAS redefines the following SYSTEM unit functions:
  46.  
  47.                 exp, ln, pi, sqrt
  48.  
  49.         In order to improve performance, none of the MATH
  50. routines perform any range-checking for invalid values.
  51. Generally, this only means that the result returned will be
  52. equally invalid.  However, there are some special values that
  53. WILL result in run-time errors for some of the routines.  Calling
  54. the MATH routines with illegal or improper inputs is strictly at
  55. the programmer's risk.
  56.  
  57.         While many of the MATH.PAS routines have parallels in
  58. Turbo C, there are some exceptions where the behavior could be
  59. astonishingly different. This has to do with how "MOD" should be
  60. interpreted.  In Turbo C, (and, in Turbo Pascal, as well) "MOD"
  61. is considered to be what is left-over after integer division.  In
  62. MATH.PAS, "MOD" is considered to be a mathematical "modulus"
  63. function.  For what it is that is left over after division, the
  64. example of the Ada programming language is followed with the use
  65. of the term "REM" (for "remainder").  If you never try to use the
  66. related functions with negative arguments, you'll never have to
  67. worry about whether the difference is important.
  68.  
  69.  
  70. MATH.PAS constant definitions
  71.  
  72.         These are provided as a programmer convenience.  The
  73. routines in MATH.PAS use many, but not all, of them.  However,
  74. there is no particular need for the application program to refer
  75. to them at all.
  76.  
  77.         CBRT2      the cube root of 2
  78.         CBRT3      the cube root of 3
  79.  
  80.         D2R        the number of radians in one degree of arc
  81.  
  82.         E          base of natural logarithms
  83.         EULERC     Euler's constant
  84.  
  85.         LN2        natural logarithm of 2
  86.         LN3        natural logarithm of 3
  87.         LN10       natural logarithm of 10
  88.         LNPI       natural logarithm of PI
  89.         LOG2E      1/ln(2)
  90.         LOG10E     1/ln(10)
  91.  
  92.         M2R        the number of radians in one minute of arc
  93.  
  94.         PI         plain ol' round pi -- the ratio of the
  95.                 circumference of a circle to its diameter. (Note:
  96.                 this constant replaces the "pi" function of the
  97.                 SYSTEM unit.)
  98.  
  99.         PI_2       pi/2
  100.         PI_4       pi/4
  101.  
  102.         R1_E       1/e
  103.         R1_PI      1/pi
  104.         R1_SQRTPI  1/sqrt(pi)
  105.         R2_PI      2/pi
  106.         R2_SQRTPI  2/sqrt(pi)
  107.         R2D        number of degrees of arc in a radian
  108.  
  109.         S2R        the number of radians in one second of arc
  110.         SQRPI      this is a square, vice round, pi
  111.         SQRT_2     sqrt(1/2)
  112.         SQRT2      sqrt(2)
  113.         SQRT2PI    sqrt(2*pi)
  114.         SQRT3      sqrt(3)
  115.         SQRT5      sqrt(5)
  116.         SQRTPI     sqrt(pi) or gamma(1/2)
  117.         TWOPI      2*pi
  118.  
  119.  
  120. MATH.PAS type definitions
  121.  
  122.         Depending upon whether or not MATH.PAS is compiled to do
  123. floating point manipulations in hardware or software, the
  124. routines will return different values.
  125.  
  126.         float = either "real" or "double" depending upon the
  127.                 status of the N option.
  128.  
  129.         xfloat = either "real" or "extended" depending upon the
  130.                  status of the N option.
  131.  
  132.         The "float" type is expected to be the primary storage
  133. mechanism for application programs.  The "xfloat" type is
  134. provided to maximize precision in expressions.  There are only a
  135. few functions where it is important to know the difference.  They
  136. are:
  137.  
  138.         deg2dms -- returns "float" values through the DMS
  139.                    arguments
  140.  
  141.         modf    -- returns a "float" value through one of its
  142.                    arguments
  143.  
  144.         poly    -- expects the polynomial coefficients to be an
  145.                    array of "float"
  146.  
  147.         rad2dms -- returns "float" values through the DMS
  148.                    arguments
  149.  
  150.         remf    -- returns a "float" value through one of its
  151.                    arguments
  152.  
  153. (Because of Turbo Pascal's strong type-checking, you may run into
  154. an occasional problem where you've declared a "real" or "double"
  155. variable -- or you're redefined "float" in another unit -- and
  156. can't pass the variable to one of the above routines.  In those
  157. cases, you should be able to do variable type-casting --
  158. "math.float(x)" to bypass the type-checking.  This should be done
  159. with care.)
  160.  
  161. For programmer convenience, MATH.PAS defines a structured type
  162. called "floatray" which is the largest array that can hold
  163. elements of type "float" (as defined above).  There is normally
  164. no need to refer to "floatray" in application programs.
  165.  
  166.  
  167. MATH.PAS function and procedure definitions
  168.  
  169. name    (parameter list)                           type of result
  170. ----    ----------------                           --------------
  171. acos    (x: xfloat)                                     xfloat
  172.  
  173.         Return the principal value of the inverse circular cosine
  174.         of "x" for abs(x)<=1.  The returned value is in radians
  175.         and ranges between 0 and PI.  Related functions:
  176.         "acosd","asin", "atan", "system.cos".
  177.  
  178.  
  179. acosd   (x: xfloat)                                     xfloat
  180.  
  181.         Returns the principal value of the inverse circular
  182.         cosine of "x" for abs(x)<=1.  The returned value is in
  183.         decimal degrees and ranges between 0 and 180. Related
  184.         functions: "acos", "cosd".
  185.  
  186. acosh   (x: xfloat)                                     xfloat
  187.  
  188.         Returns the principal value of the inverse hyperbolic
  189.         cosine of "x" for x>=1.  The returned value is greater
  190.         than or equal to 0. Related functions: "asinh", "atanh",
  191.         "cosh".
  192.  
  193.  
  194. asin    (x: xfloat)                                     xfloat
  195.  
  196.         Returns the principal value of the inverse circular sine
  197.         of "x" for abs(x)<=1.  The returned value is in radians
  198.         and ranges between -PI/2 and +PI/2.  Related functions:
  199.         "acos", "asind", "atan", "system.sin".
  200.  
  201.  
  202. asind   (x: xfloat)                                     xfloat
  203.  
  204.         Returns the principal value of the inverse circular sine
  205.         of "x" for abs(x)<=1.  The returned value is in decimal
  206.         degrees and ranges between -90 and +90.  Related
  207.         functions: "asin", "sind".
  208.  
  209.  
  210. asinh   (x: xfloat)                                     xfloat
  211.  
  212.         Returns the inverse hyperbolic sine of "x".  Related
  213.         functions: "acosh", "atanh", "sinh".
  214.  
  215.  
  216. atan    (x: xfloat)                                     xfloat
  217.  
  218.         Returns the principal value of the inverse circular
  219.         tangent of "x".  The returned value is in radians and
  220.         ranges between -PI/2 and +PI/2.  Note: this is the same
  221.         as "arctan" in the SYSTEM unit.  This function is
  222.         provided for nomenclature consistency only. Related
  223.         functions: "acos", "asin", "atan2", "tan".
  224.  
  225.  
  226. atan2   (x, y: xfloat)                                  xfloat
  227.  
  228.         Returns the angle, in radians, between the x-axis and the
  229.         line segment connecting the origin and the coordinate
  230.         (x,y).  This is the angular component generated in
  231.         converting from cartesian coordinates (x,y) to polar.
  232.         The range of ATAN2 is bounded between -PI and +PI
  233.         radians.  Related functions: "atan", "hypot", "tan".
  234.  
  235.  
  236. atan2d  (x, y: xfloat)                                  xfloat
  237.  
  238.         Returns the angle, in decimal degrees, between the x-axis
  239.         and the line segment connecting the origin and the
  240.         coordinate (x,y).  This is the angular component
  241.         generated in converting from cartesian coordinates (x,y)
  242.         to polar. The range of ATAN2D is bounded between -180 and
  243.         +180 degrees.  Related functions: "atan2", "tand".
  244.  
  245.  
  246. atand   (x: xfloat)                                     xfloat
  247.  
  248.         Returns the principal value of the inverse circular
  249.         tangent of "x".  The returned value is in decimal
  250.         degrees, and ranges between -90 and +90. Related
  251.         functions: "system.arctan", "tand".
  252.  
  253.  
  254. atanh   (x: xfloat)                                     xfloat
  255.  
  256.         Returns the inverse hyperbolic tangent of "x" for
  257.         abs(x)<1.  Related functions: "acosh", "asinh", "tanh".
  258.  
  259.  
  260. ceil    (x: xfloat)                                     xfloat
  261.  
  262.         Returns the smallest integer value greater than or equal
  263.         to "x".  (Rounds up.)  Related functions: "floor" (rounds
  264.         down), "system.int" (rounds toward zero), "system.round"
  265.         (rounds to nearest integer), "round2" (rounds to
  266.         specified number of decimal places).
  267.  
  268.  
  269. cosd    (x: xfloat)                                     xfloat
  270.  
  271.         Returns the circular cosine of "x" degrees.  COSD ranges
  272.         between -1 and +1.  Related functions: "acosd",
  273.         "system.cos".
  274.  
  275.  
  276. cosh    (x: xfloat)                                     xfloat
  277.  
  278.         Returns the hyperbolic cosine of "x".  The returned value
  279.         is greater than or equal to 0.  Related functions:
  280.         "acosh", "sinh", "tanh".
  281.  
  282.  
  283. deg2dms (deg: xfloat; var d,m,s :float)                 ------
  284.  
  285.         Converts "deg" degrees into degree-minute-second
  286.         notation.  Related functions: "deg2rad", "dms2deg".
  287.  
  288.  
  289. deg2rad (x: xfloat)                                     xfloat
  290.  
  291.         Converts "x" degrees into radians.  Related functions:
  292.         "deg2dms", "rad2deg".
  293.  
  294.  
  295. dms2deg (d,m,s: xfloat)                                 xfloat
  296.  
  297.         Converts degrees-minute-seconds into decimals degrees.
  298.         Related functions: "deg2dms", "dms2rad".
  299.  
  300.  
  301. dms2rad (d,m,s: xfloat)                                 xfloat
  302.  
  303.         Converts degrees-minute-seconds into decimals radians.
  304.         Related functions: "rad2dms", "dms2deg".
  305.  
  306.  
  307. exp     (x: xfloat)                                     xfloat
  308.  
  309.         Returns the value of "e" (the base of the natural
  310.         logarithms) raised to the "x" power.  If x is
  311.         sufficiently negative, merely returns 0.  Otherwise, it
  312.         calls "system.exp".  Note: this function is provided as a
  313.         replacement for the "exp" of the SYSTEM unit which
  314.         overflows (!) when "x" is very negative.  Related
  315.         functions: "system.exp", "exp2", "exp10", "math.ln",
  316.         "pow", "root".
  317.  
  318.  
  319. exp2    (x: xfloat)                                     xfloat
  320.  
  321.         Returns the value of "2" raised to the "x" power.
  322.         Related functions: "math.exp", "exp10", "log2".
  323.  
  324.  
  325. exp10   (x: xfloat)                                     xfloat
  326.  
  327.         Returns the value of "10" raised to the "x" power.
  328.         Related functions: "math.exp", "exp2", "log10", "pow10".
  329.  
  330.  
  331. fdiv    (x, y: xfloat)                                  xfloat
  332.  
  333.         Returns the number of times that "y" divides evenly into
  334.         "x" (rounds toward 0) -- a floating point analogue of the
  335.         integer "DIV" operator.  Related functions: "fmod",
  336.         "frem", "remf".
  337.  
  338.  
  339. floor   (x: xfloat)                                     xfloat
  340.  
  341.         Returns the largest integer value less than or equal to
  342.         "x". (Rounds down.)  Related functions: "ceil" (rounds
  343.         up), "system.int" (rounds toward zero), "system.round"
  344.         (rounds toward nearest integer), "round2" (rounds to
  345.         specified number of decimal places).
  346.  
  347.  
  348. fmod    (x, y: xfloat)                                  xfloat
  349.  
  350.         Returns the modulus that results from evenly dividing "y"
  351.         into "x" (rounded down).  For constant "y", "fmod" is a
  352.         periodic function of "x".  (This is NOT the same as Turbo
  353.         C's "fmod" nor Turbo Pascal's MOD operator for integers!)
  354.         Related functions: "frem", "modf".
  355.  
  356.  
  357. frem    (x, y: xfloat)                                  xfloat
  358.  
  359.         Returns the remainder that results after evenly dividing
  360.         "y" into "x" (rounded toward 0).  For constant "y",
  361.         "frem" is an odd function of "x". A floating point
  362.         analogue of the integer MOD operator.) Related functions:
  363.         "fdiv", "fmod", "remf".
  364.  
  365.  
  366. frexp   (x: xfloat; var epart:longint)                  xfloat
  367.  
  368.         Divides "x" into two parts: a mantissa m and an exponent
  369.         e such that x=m*pow(2,e).  The exponent is returned in
  370.         "epart".  The mantissa is returned as the result of the
  371.         function.  (For normalized "x" values, 0.5<=abs(m)<1.)
  372.         Related function: "ldexp".
  373.  
  374.  
  375. hypot   (x, y: xfloat)                                  xfloat
  376.  
  377.         Returns the hypoteneuse of the right triangle with sides
  378.         "x" and "y".  This is the range component generated in
  379.         converting cartesian coordinates (x,y) to polar
  380.         coordinates.  Related functions: "atan2".
  381.  
  382.  
  383. iif     (p: boolean; t, f: xfloat)                      xfloat
  384.  
  385.         Returns "t" if "p" is true; otherwise returns "f".  Note:
  386.         this routine will force the unnecessary evaluation of
  387.         either "t" or "f" expressions without regard to which
  388.         value is returned.  It works more efficiently if "t" and
  389.         "f" are variables vice expressions.  This function is
  390.         used within several places in the source code where that
  391.         situation arises.
  392.  
  393.  
  394. ipow    (x, y: xfloat)                                  xfloat
  395.  
  396.         Returns the imaginary component of the complex value that
  397.         results when real "x" is raised the real "y" power. (Function
  398.         "pow" returns the real component.)  There may be an
  399.         infinite number of satisfactory values, and this function
  400.         only returns one.  Related functions: "iroot", "pow".
  401.  
  402.  
  403. iroot   (x, y: xfloat)                                  xfloat
  404.  
  405.         Returns the imaginary component of the complex value that
  406.         results when taking the real "y" root of the real "x"
  407.         value. (Function "root" returns the real component.)
  408.         There may be an infinite number of satisfactory values,
  409.         and this function only returns one. Related functions:
  410.         "ipow", "root".
  411.  
  412.  
  413. ldexp   (x: xfloat; epart: longint)                     xfloat
  414.  
  415.         Returns x*pow(2,epart).  Related function: "frexp".
  416.  
  417.  
  418. ln      (x: xfloat)                                     xfloat
  419.  
  420.         Returns the natural logarithm of "x".  If x<0, it returns
  421.         the real component of the complex logarithm value.  (The
  422.         imaginary component is "pi".)   Note: a simpler version
  423.         of "ln" exists in the SYSTEM unit.  Related functions:
  424.         "math.exp", "log", "log2", "log10".
  425.  
  426.  
  427. log     (x: xfloat)                                     xfloat
  428.  
  429.         Returns the natural logarithm of "x".  Related functions:
  430.         "math.ln", "log2", "log10".
  431.  
  432.  
  433. log2    (x: xfloat)                                     xfloat
  434.  
  435.         Returns the base two logarithm of "x". (Base two
  436.         logarithms are used extensively in information theory.)
  437.         Related functions:  "exp2", "math.ln", "log", "log10".
  438.  
  439.  
  440. log10   (x: xfloat)                                     xfloat
  441.  
  442.         Returns the common or base ten logarithm of "x".  Related
  443.         functions: "exp10", "math.ln", "log", "log2", "pow10".
  444.  
  445.  
  446. max     (x, y: xfloat)                                  xfloat
  447.  
  448.         Returns either "x" or "y", whichever is greater.  Related
  449.         functions: "min".
  450.  
  451.  
  452. min     (x, y: xfloat)                                  xfloat
  453.  
  454.         Returns either "x" or "y", whichever is less. Related
  455.         functions: "max".
  456.  
  457.  
  458. modf    (x: xfloat; var ipart: float)                   xfloat
  459.  
  460.         Divides the value of "x" into an integer part and a
  461.         fractional part.  The integer part (rounded down --
  462.         making it different from Turbo C's "modf" and Turbo
  463.         Pascal's integer MOD operator) is returned in "ipart".
  464.         The fractional part is return as the value of the
  465.         function. Related functions: "fmod", "remf".
  466.  
  467.  
  468. poly    (x: xfloat; degree: integer; var coeffs )       xfloat
  469.  
  470.         Returns the evaluation of the polynomial
  471.  
  472.                                      2                     degree
  473.     coeffs[0]+coeffs[1]*X+coeffs[2]*X +...+coeffs[degree]*X
  474.  
  475.         IMPORTANT! The untyped var "coeffs" is presumed to be an
  476.         array of "float", but the compiler does not enforce this
  477.         restriction.  Passing any other structure to "poly" will
  478.         generate inexplicable results.
  479.  
  480.  
  481. pow     (x, y: xfloat)                                  xfloat
  482.  
  483.         Returns "x" raised the "y" power.  Uses an exponential -
  484.         logarithm algorithm.  Related functions: "math.exp",
  485.         "ipow", "powi", "root", "system.sqr".
  486.  
  487.  
  488. pow10   (x: xfloat)                                     xfloat
  489.  
  490.         Returns ten raised to the "x" power.  Same thing as
  491.         "exp10".  This function is provided for certain
  492.         programmers who are accustomed to exponentiating "10"
  493.         with a function of this name.
  494.  
  495.  
  496. powi    (x: xfloat; n: integer)                         xfloat
  497.  
  498.         Returns "x" raised to the "n" power.  Uses a recursive
  499.         squaring - multiplication algorithm.  Related functions:
  500.         "pow", "system.sqr".
  501.  
  502.  
  503. rad2deg (x: xfloat)                                     xfloat
  504.  
  505.         Converts "x" radians into degrees.  Related functions:
  506.         "deg2rad".
  507.  
  508.  
  509. rad2dms (r:xfloat; var d,m,s: float)                    ------
  510.  
  511.         Converts "r" radians into degrees-minute-seconds. Related
  512.         functions: "dms2rad", "rad2deg".
  513.  
  514.  
  515. remf    (x: xfloat; var ipart: float)                   xfloat
  516.  
  517.         Divides the value of "x" into an integer part and a
  518.         fractional part.  The integer part (rounded toward 0) is
  519.         returned in "ipart".  The fractional part is return as
  520.         the value of the function.  Related functions: "fdiv",
  521.         "frem", "modf". For an example of use, see the source
  522.         code for the procedure "deg2dms".
  523.  
  524.  
  525. root    (x, y: xfloat)                                  xfloat
  526.  
  527.         Returns "x" raised to the "y" power.  If x<0, then the
  528.         real component of the complex power is returned.  Related
  529.         functions: "pow", "system.sqrt".
  530.  
  531.  
  532. round2  (x: xfloat; n: shortint)                        xfloat
  533.  
  534.         Returns "x", rounded to "n" decimal places to the right
  535.         of the decimal point.  If "n" is negative, rounding
  536.         occurs to the left of the decimal point.  NOTE!  Because
  537.         of the approximate nature of storing fractional
  538.         components in floating point representations, you should
  539.         be never assume that the result of "round2" is *exact*.
  540.         However, it should be very, very close.
  541.  
  542.  
  543. sgn     (x: xfloat)                                     xfloat
  544.  
  545.         Returns the "signum" of "x".  If x>0, then "+1" is
  546.         returned.  If x<0, "-1" is returned.  If x=0, then "0"
  547.         is returned.  Related functions: "system.abs".
  548.  
  549.  
  550. sind    (x: xfloat)                                     xfloat
  551.  
  552.         Returns the circular sine of "x" degrees.  SIND ranges
  553.         from -1 to +1.  Related functions: "asind", "system.sin".
  554.  
  555.  
  556. sinh    (x: xfloat)                                     xfloat
  557.  
  558.         Returns the hyperbolic sine of "x".  Related functions:
  559.         "asinh", "cosh", "tanh".
  560.  
  561.  
  562. sqrt    (x: xfloat)                                     xfloat
  563.  
  564.         Returns the square root of "x".  If x>=0, then
  565.         SYSTEM.SQRT is invoked.  For x<0, this function returns
  566.         the negative of system.sqrt(-x).  This makes "math.sqrt"
  567.         an odd function.  Also, note that "math.sqrt(-1) <>
  568.         root(-1,2)".  Instead, "math.sqrt(-1) = -iroot(-1,2)".
  569.         Related functions: "root", "system.sqr", "system.sqrt".
  570.  
  571.  
  572. tan     (x: xfloat)                                     xfloat
  573.  
  574.         Returns the circular tangent of "x".  The value of "x" is
  575.         assumed to be expressed in radians.  Related functions:
  576.         "system.sin", "system.cos", "system.arctan".
  577.  
  578.  
  579. tand    (x: xfloat)                                     xfloat
  580.  
  581.         Returns the circular tangent of "x" degrees. Related
  582.         functions: "atand", "tan".
  583.  
  584.  
  585. tanh    (x: xfloat)                                     xfloat
  586.  
  587.         Returns the hyperbolic tangent of "x".  TANH ranges from
  588.         -1 to 1.  Related functions:  "atanh", "cosh", "sinh".
  589.