home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 221.lha / doc / float.doc < prev    next >
Text File  |  1996-02-15  |  9KB  |  185 lines
  1.         Support for Floating Point in Draco V 1.2
  2.  
  3.  
  4. I. The Format Used
  5.  
  6.     Draco V 1.2 supports the Amiga's IEEE double precision floating point
  7.     package as the type 'float'. The support is quite complete, and
  8.     probably offers a few features not available with any other Amiga
  9.     programming system. Each such floating point value occupies 8 bytes of
  10.     storage, and contains roughly 16 decimal digits of accuracy. The range
  11.     of values supported is approximately 10E-300 to 10E+300. The Amiga
  12.     software floating point library does not appear to fully support the
  13.     IEEE format in the areas of unnormalized numbers, NaN's and infinities.
  14.     The Draco compiler and run-time system support these elements to the
  15.     extent that they are able. On a system with a math chip (MC68881 or
  16.     MC68882) installed and configured, support for these features should be
  17.     available. I have no idea what you would have to do to setup the chip
  18.     to recognize and signal NaN's, but it is likely that you will have to
  19.     do some inline code (e.g. Draco's 'code' construct) to enable the
  20.     desired behavior.
  21.  
  22.  
  23. II. Compiler Support
  24.  
  25.     The compiler recognizes and translates floating point numbers in source
  26.     programs. These can be in E-format (e.g. 0.618e-103), F-format (e.g.
  27.     -278.349) or in a special format for special values. In particular, a
  28.     floating point constant must have exactly one decimal point. For E
  29.     format, the '+' sign for the exponent is optional, and the exponent can
  30.     be any number of decimal digits. The special forms '0fNaN' and '0fInf'
  31.     are recognized to generate IEEE NaN's and infinities. Negative values
  32.     can be generated using the unary '-' operator with these constants.
  33.     Floating point constants can be given explicitly in hexadecimal, using
  34.     the form '0fxYYYYYYYYYYYYYYYY'. There must be exactly 16 hexadecimal
  35.     digits given in this form. In the special forms, case is not
  36.     significant.
  37.  
  38.     Compile-time evaluation of floating point expressions is supported for
  39.     the following operators: unary '+', unary '-', unary '|', binary '+',
  40.     binary '-', binary '*' and binary '/'. Also available are the
  41.     constructs 'fix' and 'flt', which convert from float to long and from
  42.     long to float, respectively. The syntax of this is the keyword followed
  43.     by the argument in parentheses. All of these are done by calling the
  44.     appropriate routine in the Amiga's IEEE floating point library. Note
  45.     that at both compile time and at run time, the library routines are
  46.     called for the unary '-' and unary '|' operations, even though these
  47.     can be done by simply flipping or clearing a bit. On a system with a
  48.     math chip, these operations can cause exceptions, so should be given to
  49.     the chip to execute.
  50.  
  51.     When compiling a source program that contains a floating point constant
  52.     in E or F format, or which does compile-time floating point evaluation,
  53.     the compiler needs to open 'mathieeedoubbas.library', which should be
  54.     located in your 'libs:' directory. The compiler and run-time libraries
  55.     have been tested using the version of this library that comes with V1.3
  56.     of the Amiga operating system, but they should also work with earlier
  57.     versions of the library.
  58.  
  59.  
  60. III. Run-Time Support
  61.  
  62.     All of the operations mentioned above for compile time are available at
  63.     run-time for floating point values. In addition, Draco include file
  64.     'float.g' defines some handy values and declares the library routines
  65.     'sin', 'cos', 'tan', 'atan', 'asin', 'acos', 'sinh', 'cosh', 'tanh',
  66.     'exp', 'log', 'log10', 'sqrt' and 'pow', all of which are available in
  67.     AmigaDOS V1.3's 'mathieeedoubtrans.library' library, which should also
  68.     be located in your 'libs:' directory. Note that the compiler itself
  69.     does not use this library, but that the standard floating point startup
  70.     code attempts to open the trancendental library along with the standard
  71.     math library.
  72.  
  73.     Run-time input and output of floating point values is fully supported.
  74.     On input, any of the formats accepted by the compiler is acceptable,
  75.     and the leading '0f' is optional on the special forms. New syntax has
  76.     been added to the compiler's 'write' and 'writeln' formatting options
  77.     to support floating point output. There are essentially 3 output
  78.     formats that can be used. They are 'f', for F-format, 'e' for E-format,
  79.     and 'g' for F-format if the number fits nicely, else E-format. Each
  80.     form can take two integral expressions as size and digits specifiers,
  81.     with both defaulting to 0.
  82.  
  83.     The exact rules for output are as follows: (in all cases, if an
  84.     explicit length is given, and the formatted value does not fit in that
  85.     length, then that number of '*'s are printed)
  86.  
  87.     if the high order 12 bits (excluding the high, sign, bit) are all
  88.     ones, then the value is considered to be special. If the remainder
  89.     of the bits other than the sign bit are all 0, then the number is
  90.     assumed to be an infinity, and either '+Inf' or '-Inf' will be
  91.     printed. All other special values are printed as '+NaN' or '-NaN'.
  92.  
  93.     otherwise:
  94.  
  95.         if 'g' format was specified and the decimal exponent is less
  96.         than -5 or greater than +10, then use 'e' format instead.
  97.  
  98.         'e' format:
  99.  
  100.         if neither the length nor digits were specified, then all
  101.         trailing zeros will be trimmed, producing an output as
  102.         short as possible. If the number of digits is specified,
  103.         then that number of digits is used, regardless of the
  104.         length given. If the length is given, but no digits value
  105.         is given, then length - 8 digits will be printed. (8
  106.         characters are needed for -0.E-ddd). If the length was
  107.         given as a negative value, then its positive form is used
  108.         and an explicit '+' is used on the front of positive
  109.         numbers, else a space is used. When both the length and the
  110.         desired number of digits are given, any extra space needed
  111.         is padded on the left with spaces.
  112.  
  113.         e.g.     value        format     result
  114.               1.0        e        " 0.1e+001"
  115.              1.e30        e        " 0.1e+031"
  116.              23.45        e:6     "******"
  117.              23.45        e:15    " 0.2345000e+002"
  118.              23.45        e:-15:4    "   +0.2345e+002"
  119.                -87654.        e:12    "-0.8765e+005"
  120.  
  121.         'f' format:
  122.  
  123.         the rules for producing an F-format value are quite
  124.         complicated. The essence is a desire to always have the
  125.         decimal points line up for any values with the same format.
  126.         A negative length will cause padding on the left with '0's
  127.         instead of with spaces. A negative digit count will cause
  128.         padding on the right with '0's instead of spaces. A leading
  129.         '+' sign is never printed, nor is space left for one. Zeros
  130.         for both values (or neither given) will cause no padding,
  131.         and the value is rounded to a default of 5 digits. Note
  132.         that if only one length/digits specification is given, then
  133.         it is the digits specification, and the resulting length
  134.         will depend on the value printed. The most control over the
  135.         output format occurs when both values are specified, and it
  136.         is this form that is normally used for tabular output.
  137.  
  138.         e.g.    value        format     result
  139.              1.0        f        "1.0"
  140.              1.e20        f        "99999999999999970000.0"
  141.              23.45        f        "23.45"
  142.              23.45        f:6     "23.45   "
  143.              23.45        f:-6:2    "023.45"
  144.              23.45        f:6:-3    "23.450"
  145.              23.45        f:-10:-5    "0023.45000"
  146.              .00000001        f        "0.00000001"
  147.              .00000001        f:10    "0.00000001  "
  148.              .00000001        f:-15:-10    "0000.0000000100"
  149.              .00000001        f:0:-10    "0.0000000100"
  150.              .00000001        f:0:-8    "0.00000001"
  151.              .00000001        f:0:-7    "0.00000001"
  152.              .00000001        f:0:7    "0.00000001"
  153.           123.12345678        f:0:8    "123.12345678"
  154.           123.12345678        f:0:4    "123.1235"
  155.           123.12345678        f:10:4    "  123.1235"
  156.          -123.12345678        f:10:4    " -123.1235"
  157.          -123.12345678        f        "-123.12"
  158.          -123.12345678        f:10:0    "     -123."
  159.          -123.12345678        f:0:10    "-123.12345678"
  160.              0fNaN        f        +NaN
  161.             -0fInf        f        -Inf
  162.  
  163.         Note that because of the way the compiler generates code
  164.         for F-format output, 'f' is equivalent to 'f:0', which is
  165.         equivalent to 'f:0:0'. If the format that you want is a
  166.         minimum length one (normally, length = 0), but with no
  167.         digits after the decimal point, then the following is
  168.         suggested:
  169.  
  170.             write(fix(floatValue), '.');
  171.  
  172.  
  173. IV. The Complex Number Package
  174.  
  175.     A complex number operator-type package is included with this
  176.     distribution. There are four files of interest. 'drlib/complex.lib' is
  177.     the library file which implements the package. It is compiled from the
  178.     source in 'src/complex.d' (the resulting 'complex.r' file is simply
  179.     copied to 'drlib:' as 'complex.lib'). 'complex.g' is the include file
  180.     in 'drinc:' which defines the package to its users, and
  181.     'src/complexTest.d' is a simple test program that demonstrates how to
  182.     use the package.
  183.  
  184.     My thanks to Don Reble for the complex trancendental functions.
  185.