include/llvm/ADT/APFloat.h

   1 //== llvm/Support/APFloat.h - Arbitrary Precision Floating Point -*- C++ -*-==//
   2 //
   3 //                     The LLVM Compiler Infrastructure
   4 //
   5 // This file was developed by Neil Booth and is distributed under the
   6 // University of Illinois Open Source License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9 //
  10 // This file declares a class to represent arbitrary precision floating
  11 // point values and provide a variety of arithmetic operations on them.
  12 //
  13 //===----------------------------------------------------------------------===//
  14
  15 /*  A self-contained host- and target-independent arbitrary-precision
  16     floating-point software implementation.  It uses bignum integer
  17     arithmetic as provided by static functions in the APInt class.
  18     The library will work with bignum integers whose parts are any
  19     unsigned type at least 16 bits wide, but 64 bits is recommended.
  20
  21     Written for clarity rather than speed, in particular with a view
  22     to use in the front-end of a cross compiler so that target
  23     arithmetic can be correctly performed on the host.  Performance
  24     should nonetheless be reasonable, particularly for its intended
  25     use.  It may be useful as a base implementation for a run-time
  26     library during development of a faster target-specific one.
  27
  28     All 5 rounding modes in the IEEE-754R draft are handled correctly
  29     for all implemented operations.  Currently implemented operations
  30     are add, subtract, multiply, divide, fused-multiply-add,
  31     conversion-to-float, conversion-to-integer and
  32     conversion-from-integer.  New rounding modes (e.g. away from zero)
  33     can be added with three or four lines of code.
  34
  35     Four formats are built-in: IEEE single precision, double
  36     precision, quadruple precision, and x87 80-bit extended double
  37     (when operating with full extended precision).  Adding a new
  38     format that obeys IEEE semantics only requires adding two lines of
  39     code: a declaration and definition of the format.
  40
  41     All operations return the status of that operation as an exception
  42     bit-mask, so multiple operations can be done consecutively with
  43     their results or-ed together.  The returned status can be useful
  44     for compiler diagnostics; e.g., inexact, underflow and overflow
  45     can be easily diagnosed on constant folding, and compiler
  46     optimizers can determine what exceptions would be raised by
  47     folding operations and optimize, or perhaps not optimize,
  48     accordingly.
  49
  50     At present, underflow tininess is detected after rounding; it
  51     should be straight forward to add support for the before-rounding
  52     case too.
  53
  54     The library reads hexadecimal floating point numbers as per C99,
  55     and correctly rounds if necessary according to the specified
  56     rounding mode.  Syntax is required to have been validated by the
  57     caller.  It also converts floating point numbers to hexadecimal
  58     text as per the C99 %a and %A conversions.  The output precision
  59     (or alternatively the natural minimal precision) can be specified;
  60     if the requested precision is less than the natural precision the
  61     output is correctly rounded for the specified rounding mode.
  62
  63     Conversion to and from decimal text is not currently implemented.
  64
  65     Non-zero finite numbers are represented internally as a sign bit,
  66     a 16-bit signed exponent, and the significand as an array of
  67     integer parts.  After normalization of a number of precision P the
  68     exponent is within the range of the format, and if the number is
  69     not denormal the P-th bit of the significand is set as an explicit
  70     integer bit.  For denormals the most significant bit is shifted
  71     right so that the exponent is maintained at the format's minimum,
  72     so that the smallest denormal has just the least significant bit
  73     of the significand set.  The sign of zeroes and infinities is
  74     significant; the exponent and significand of such numbers is not
  75     stored, but has a known implicit (deterministic) value: 0 for the
  76     significands, 0 for zero exponent, all 1 bits for infinity
  77     exponent.  For NaNs the sign and significand are deterministic,
  78     although not really meaningful, and preserved in non-conversion
  79     operations.  The exponent is implicitly all 1 bits.
  80
  81     TODO
  82     ====
  83
  84     Some features that may or may not be worth adding:
  85
  86     Conversions to and from decimal strings (hard).
  87
  88     Optional ability to detect underflow tininess before rounding.
  89
  90     New formats: x87 in single and double precision mode (IEEE apart
  91     from extended exponent range) and IBM two-double extended
  92     precision (hard).
  93
  94     New operations: sqrt, IEEE remainder, C90 fmod, nextafter,
  95     nexttoward.
  96 */
  97
  98 #ifndef LLVM_FLOAT_H
  99 #define LLVM_FLOAT_H
 100
 101 // APInt contains static functions implementing bignum arithmetic.
 102 #include "llvm/ADT/APInt.h"
 103 #include "llvm/CodeGen/ValueTypes.h"
 104
 105 namespace llvm {
 106
 107   /* Exponents are stored as signed numbers.  */
 108   typedef signed short exponent_t;
 109
 110   struct fltSemantics;
 111
 112   /* When bits of a floating point number are truncated, this enum is
 113      used to indicate what fraction of the LSB those bits represented.
 114      It essentially combines the roles of guard and sticky bits.  */
 115   enum lostFraction {           // Example of truncated bits:
 116     lfExactlyZero,              // 000000
 117     lfLessThanHalf,             // 0xxxxx  x's not all zero
 118     lfExactlyHalf,              // 100000
 119     lfMoreThanHalf              // 1xxxxx  x's not all zero
 120   };
 121
 122   class APFloat {
 123   public:
 124
 125     /* We support the following floating point semantics.  */
 126     static const fltSemantics IEEEsingle;
 127     static const fltSemantics IEEEdouble;
 128     static const fltSemantics IEEEquad;
 129     static const fltSemantics PPCDoubleDouble;
 130     static const fltSemantics x87DoubleExtended;
 131     /* And this psuedo, used to construct APFloats that cannot
 132        conflict with anything real. */
 133     static const fltSemantics Bogus;
 134
 135     static unsigned int semanticsPrecision(const fltSemantics &);
 136
 137     /* Floating point numbers have a four-state comparison relation.  */
 138     enum cmpResult {
 139       cmpLessThan,
 140       cmpEqual,
 141       cmpGreaterThan,
 142       cmpUnordered
 143     };
 144
 145     /* IEEE-754R gives five rounding modes.  */
 146     enum roundingMode {
 147       rmNearestTiesToEven,
 148       rmTowardPositive,
 149       rmTowardNegative,
 150       rmTowardZero,
 151       rmNearestTiesToAway
 152     };
 153
 154     /* Operation status.  opUnderflow or opOverflow are always returned
 155        or-ed with opInexact.  */
 156     enum opStatus {
 157       opOK          = 0x00,
 158       opInvalidOp   = 0x01,
 159       opDivByZero   = 0x02,
 160       opOverflow    = 0x04,
 161       opUnderflow   = 0x08,
 162       opInexact     = 0x10
 163     };
 164
 165     /* Category of internally-represented number.  */
 166     enum fltCategory {
 167       fcInfinity,
 168       fcNaN,
 169       fcNormal,
 170       fcZero
 171     };
 172
 173     /* Constructors.  */
 174     APFloat(const fltSemantics &, const char *);
 175     APFloat(const fltSemantics &, integerPart);
 176     APFloat(const fltSemantics &, fltCategory, bool negative);
 177     explicit APFloat(double d);
 178     explicit APFloat(float f);
 179     explicit APFloat(const APInt &, bool isIEEE = false);
 180     APFloat(const APFloat &);
 181     ~APFloat();
 182
 183     /* Arithmetic.  */
 184     opStatus add(const APFloat &, roundingMode);
 185     opStatus subtract(const APFloat &, roundingMode);
 186     opStatus multiply(const APFloat &, roundingMode);
 187     opStatus divide(const APFloat &, roundingMode);
 188     opStatus mod(const APFloat &, roundingMode);
 189     void copySign(const APFloat &);
 190     opStatus fusedMultiplyAdd(const APFloat &, const APFloat &, roundingMode);
 191     void changeSign();    // neg
 192     void clearSign();     // abs
 193
 194     /* Conversions.  */
 195     opStatus convert(const fltSemantics &, roundingMode);
 196     opStatus convertToInteger(integerPart *, unsigned int, bool,
 197                               roundingMode) const;
 198     opStatus convertFromSignExtendedInteger(const integerPart *, unsigned int,
 199                                             bool, roundingMode);
 200     opStatus convertFromZeroExtendedInteger(const integerPart *, unsigned int,
 201                                             bool, roundingMode);
 202     opStatus convertFromString(const char *, roundingMode);
 203     APInt convertToAPInt() const;
 204     double convertToDouble() const;
 205     float convertToFloat() const;
 206
 207     /* The definition of equality is not straightforward for floating point,
 208        so we won't use operator==.  Use one of the following, or write
 209        whatever it is you really mean. */
 210     // bool operator==(const APFloat &) const;     // DO NOT IMPLEMENT
 211
 212     /* IEEE comparison with another floating point number (NaNs
 213        compare unordered, 0==-0). */
 214     cmpResult compare(const APFloat &) const;
 215
 216     /* Write out a hexadecimal representation of the floating point
 217        value to DST, which must be of sufficient size, in the C99 form
 218        [-]0xh.hhhhp[+-]d.  Return the number of characters written,
 219        excluding the terminating NUL.  */
 220     unsigned int convertToHexString(char *dst, unsigned int hexDigits,
 221                                     bool upperCase, roundingMode) const;
 222
 223     /* Bitwise comparison for equality (QNaNs compare equal, 0!=-0). */
 224     bool bitwiseIsEqual(const APFloat &) const;
 225
 226     /* Simple queries.  */
 227     fltCategory getCategory() const { return category; }
 228     const fltSemantics &getSemantics() const { return *semantics; }
 229     bool isZero() const { return category == fcZero; }
 230     bool isNonZero() const { return category != fcZero; }
 231     bool isNegative() const { return sign; }
 232     bool isPosZero() const { return isZero() && !isNegative(); }
 233     bool isNegZero() const { return isZero() && isNegative(); }
 234
 235     APFloat& operator=(const APFloat &);
 236
 237     /* Return an arbitrary integer value usable for hashing. */
 238     uint32_t getHashValue() const;
 239
 240   private:
 241
 242     /* Trivial queries.  */
 243     integerPart *significandParts();
 244     const integerPart *significandParts() const;
 245     unsigned int partCount() const;
 246
 247     /* Significand operations.  */
 248     integerPart addSignificand(const APFloat &);
 249     integerPart subtractSignificand(const APFloat &, integerPart);
 250     lostFraction addOrSubtractSignificand(const APFloat &, bool subtract);
 251     lostFraction multiplySignificand(const APFloat &, const APFloat *);
 252     lostFraction divideSignificand(const APFloat &);
 253     void incrementSignificand();
 254     void initialize(const fltSemantics *);
 255     void shiftSignificandLeft(unsigned int);
 256     lostFraction shiftSignificandRight(unsigned int);
 257     unsigned int significandLSB() const;
 258     unsigned int significandMSB() const;
 259     void zeroSignificand();
 260
 261     /* Arithmetic on special values.  */
 262     opStatus addOrSubtractSpecials(const APFloat &, bool subtract);
 263     opStatus divideSpecials(const APFloat &);
 264     opStatus multiplySpecials(const APFloat &);
 265
 266     /* Miscellany.  */
 267     opStatus normalize(roundingMode, lostFraction);
 268     opStatus addOrSubtract(const APFloat &, roundingMode, bool subtract);
 269     cmpResult compareAbsoluteValue(const APFloat &) const;
 270     opStatus handleOverflow(roundingMode);
 271     bool roundAwayFromZero(roundingMode, lostFraction, unsigned int) const;
 272     opStatus convertFromUnsignedParts(const integerPart *, unsigned int,
 273                                       roundingMode);
 274     opStatus convertFromHexadecimalString(const char *, roundingMode);
 275     char *convertNormalToHexString(char *, unsigned int, bool,
 276                                    roundingMode) const;
 277     APInt convertFloatAPFloatToAPInt() const;
 278     APInt convertDoubleAPFloatToAPInt() const;
 279     APInt convertF80LongDoubleAPFloatToAPInt() const;
 280     APInt convertPPCDoubleDoubleAPFloatToAPInt() const;
 281     void initFromAPInt(const APInt& api, bool isIEEE = false);
 282     void initFromFloatAPInt(const APInt& api);
 283     void initFromDoubleAPInt(const APInt& api);
 284     void initFromF80LongDoubleAPInt(const APInt& api);
 285     void initFromPPCDoubleDoubleAPInt(const APInt& api);
 286
 287     void assign(const APFloat &);
 288     void copySignificand(const APFloat &);
 289     void freeSignificand();
 290
 291     /* What kind of semantics does this value obey?  */
 292     const fltSemantics *semantics;
 293
 294     /* Significand - the fraction with an explicit integer bit.  Must be
 295        at least one bit wider than the target precision.  */
 296     union Significand
 297     {
 298       integerPart part;
 299       integerPart *parts;
 300     } significand;
 301
 302     /* The exponent - a signed number.  */
 303     exponent_t exponent;
 304
 305     /* What kind of floating point number this is.  */
 306     /* Only 2 bits are required, but VisualStudio incorrectly sign extends
 307        it.  Using the extra bit keeps it from failing under VisualStudio */
 308     fltCategory category: 3;
 309
 310     /* The sign bit of this number.  */
 311     unsigned int sign: 1;
 312
 313     /* For PPCDoubleDouble, we have a second exponent and sign (the second
 314        significand is appended to the first one, although it would be wrong to
 315        regard these as a single number for arithmetic purposes).  These fields
 316        are not meaningful for any other type. */
 317     exponent_t exponent2 : 11;
 318     unsigned int sign2: 1;
 319   };
 320 } /* namespace llvm */
 321
 322 #endif /* LLVM_FLOAT_H */