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 is distributed under the University of Illinois Open Source
   6 // 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     It also reads decimal floating point numbers and correctly rounds
  64     according to the specified rounding mode.
  65
  66     Conversion to decimal text is not currently implemented.
  67
  68     Non-zero finite numbers are represented internally as a sign bit,
  69     a 16-bit signed exponent, and the significand as an array of
  70     integer parts.  After normalization of a number of precision P the
  71     exponent is within the range of the format, and if the number is
  72     not denormal the P-th bit of the significand is set as an explicit
  73     integer bit.  For denormals the most significant bit is shifted
  74     right so that the exponent is maintained at the format's minimum,
  75     so that the smallest denormal has just the least significant bit
  76     of the significand set.  The sign of zeroes and infinities is
  77     significant; the exponent and significand of such numbers is not
  78     stored, but has a known implicit (deterministic) value: 0 for the
  79     significands, 0 for zero exponent, all 1 bits for infinity
  80     exponent.  For NaNs the sign and significand are deterministic,
  81     although not really meaningful, and preserved in non-conversion
  82     operations.  The exponent is implicitly all 1 bits.
  83
  84     TODO
  85     ====
  86
  87     Some features that may or may not be worth adding:
  88
  89     Binary to decimal conversion (hard).
  90
  91     Optional ability to detect underflow tininess before rounding.
  92
  93     New formats: x87 in single and double precision mode (IEEE apart
  94     from extended exponent range) (hard).
  95
  96     New operations: sqrt, IEEE remainder, C90 fmod, nextafter,
  97     nexttoward.
  98 */
  99
 100 #ifndef LLVM_FLOAT_H
 101 #define LLVM_FLOAT_H
 102
 103 // APInt contains static functions implementing bignum arithmetic.
 104 #include "llvm/ADT/APInt.h"
 105
 106 namespace llvm {
 107
 108   /* Exponents are stored as signed numbers.  */
 109   typedef signed short exponent_t;
 110
 111   struct fltSemantics;
 112   class StringRef;
 113
 114   /* When bits of a floating point number are truncated, this enum is
 115      used to indicate what fraction of the LSB those bits represented.
 116      It essentially combines the roles of guard and sticky bits.  */
 117   enum lostFraction {           // Example of truncated bits:
 118     lfExactlyZero,              // 000000
 119     lfLessThanHalf,             // 0xxxxx  x's not all zero
 120     lfExactlyHalf,              // 100000
 121     lfMoreThanHalf              // 1xxxxx  x's not all zero
 122   };
 123
 124   class APFloat {
 125   public:
 126
 127     /* We support the following floating point semantics.  */
 128     static const fltSemantics IEEEsingle;
 129     static const fltSemantics IEEEdouble;
 130     static const fltSemantics IEEEquad;
 131     static const fltSemantics PPCDoubleDouble;
 132     static const fltSemantics x87DoubleExtended;
 133     /* And this pseudo, used to construct APFloats that cannot
 134        conflict with anything real. */
 135     static const fltSemantics Bogus;
 136
 137     static unsigned int semanticsPrecision(const fltSemantics &);
 138
 139     /* Floating point numbers have a four-state comparison relation.  */
 140     enum cmpResult {
 141       cmpLessThan,
 142       cmpEqual,
 143       cmpGreaterThan,
 144       cmpUnordered
 145     };
 146
 147     /* IEEE-754R gives five rounding modes.  */
 148     enum roundingMode {
 149       rmNearestTiesToEven,
 150       rmTowardPositive,
 151       rmTowardNegative,
 152       rmTowardZero,
 153       rmNearestTiesToAway
 154     };
 155
 156     // Operation status.  opUnderflow or opOverflow are always returned
 157     // or-ed with opInexact.
 158     enum opStatus {
 159       opOK          = 0x00,
 160       opInvalidOp   = 0x01,
 161       opDivByZero   = 0x02,
 162       opOverflow    = 0x04,
 163       opUnderflow   = 0x08,
 164       opInexact     = 0x10
 165     };
 166
 167     // Category of internally-represented number.
 168     enum fltCategory {
 169       fcInfinity,
 170       fcNaN,
 171       fcNormal,
 172       fcZero
 173     };
 174
 175     // Constructors.
 176     APFloat(const fltSemantics &); // Default construct to 0.0
 177     APFloat(const fltSemantics &, const StringRef &);
 178     APFloat(const fltSemantics &, integerPart);
 179     APFloat(const fltSemantics &, fltCategory, bool negative, unsigned type=0);
 180     explicit APFloat(double d);
 181     explicit APFloat(float f);
 182     explicit APFloat(const APInt &, bool isIEEE = false);
 183     APFloat(const APFloat &);
 184     ~APFloat();
 185
 186     // Convenience "constructors"
 187     static APFloat getZero(const fltSemantics &Sem, bool Negative = false) {
 188       return APFloat(Sem, fcZero, Negative);
 189     }
 190     static APFloat getInf(const fltSemantics &Sem, bool Negative = false) {
 191       return APFloat(Sem, fcInfinity, Negative);
 192     }
 193     /// getNaN - Factory for QNaN values.
 194     ///
 195     /// \param Negative - True iff the NaN generated should be negative.
 196     /// \param type - The unspecified fill bits for creating the NaN, 0 by
 197     /// default.  The value is truncated as necessary.
 198     static APFloat getNaN(const fltSemantics &Sem, bool Negative = false,
 199                           unsigned type = 0) {
 200       return APFloat(Sem, fcNaN, Negative, type);
 201     }
 202
 203     /// Profile - Used to insert APFloat objects, or objects that contain
 204     ///  APFloat objects, into FoldingSets.
 205     void Profile(FoldingSetNodeID& NID) const;
 206
 207     /// @brief Used by the Bitcode serializer to emit APInts to Bitcode.
 208     void Emit(Serializer& S) const;
 209
 210     /// @brief Used by the Bitcode deserializer to deserialize APInts.
 211     static APFloat ReadVal(Deserializer& D);
 212
 213     /* Arithmetic.  */
 214     opStatus add(const APFloat &, roundingMode);
 215     opStatus subtract(const APFloat &, roundingMode);
 216     opStatus multiply(const APFloat &, roundingMode);
 217     opStatus divide(const APFloat &, roundingMode);
 218     /* IEEE remainder. */
 219     opStatus remainder(const APFloat &);
 220     /* C fmod, or llvm frem. */
 221     opStatus mod(const APFloat &, roundingMode);
 222     opStatus fusedMultiplyAdd(const APFloat &, const APFloat &, roundingMode);
 223
 224     /* Sign operations.  */
 225     void changeSign();
 226     void clearSign();
 227     void copySign(const APFloat &);
 228
 229     /* Conversions.  */
 230     opStatus convert(const fltSemantics &, roundingMode, bool *);
 231     opStatus convertToInteger(integerPart *, unsigned int, bool,
 232                               roundingMode, bool *) const;
 233     opStatus convertFromAPInt(const APInt &,
 234                               bool, roundingMode);
 235     opStatus convertFromSignExtendedInteger(const integerPart *, unsigned int,
 236                                             bool, roundingMode);
 237     opStatus convertFromZeroExtendedInteger(const integerPart *, unsigned int,
 238                                             bool, roundingMode);
 239     opStatus convertFromString(const StringRef&, roundingMode);
 240     APInt bitcastToAPInt() const;
 241     double convertToDouble() const;
 242     float convertToFloat() const;
 243
 244     /* The definition of equality is not straightforward for floating point,
 245        so we won't use operator==.  Use one of the following, or write
 246        whatever it is you really mean. */
 247     // bool operator==(const APFloat &) const;     // DO NOT IMPLEMENT
 248
 249     /* IEEE comparison with another floating point number (NaNs
 250        compare unordered, 0==-0). */
 251     cmpResult compare(const APFloat &) const;
 252
 253     /* Bitwise comparison for equality (QNaNs compare equal, 0!=-0). */
 254     bool bitwiseIsEqual(const APFloat &) const;
 255
 256     /* Write out a hexadecimal representation of the floating point
 257        value to DST, which must be of sufficient size, in the C99 form
 258        [-]0xh.hhhhp[+-]d.  Return the number of characters written,
 259        excluding the terminating NUL.  */
 260     unsigned int convertToHexString(char *dst, unsigned int hexDigits,
 261                                     bool upperCase, roundingMode) const;
 262
 263     /* Simple queries.  */
 264     fltCategory getCategory() const { return category; }
 265     const fltSemantics &getSemantics() const { return *semantics; }
 266     bool isZero() const { return category == fcZero; }
 267     bool isNonZero() const { return category != fcZero; }
 268     bool isNaN() const { return category == fcNaN; }
 269     bool isInfinity() const { return category == fcInfinity; }
 270     bool isNegative() const { return sign; }
 271     bool isPosZero() const { return isZero() && !isNegative(); }
 272     bool isNegZero() const { return isZero() && isNegative(); }
 273
 274     APFloat& operator=(const APFloat &);
 275
 276     /* Return an arbitrary integer value usable for hashing. */
 277     uint32_t getHashValue() const;
 278
 279   private:
 280
 281     /* Trivial queries.  */
 282     integerPart *significandParts();
 283     const integerPart *significandParts() const;
 284     unsigned int partCount() const;
 285
 286     /* Significand operations.  */
 287     integerPart addSignificand(const APFloat &);
 288     integerPart subtractSignificand(const APFloat &, integerPart);
 289     lostFraction addOrSubtractSignificand(const APFloat &, bool subtract);
 290     lostFraction multiplySignificand(const APFloat &, const APFloat *);
 291     lostFraction divideSignificand(const APFloat &);
 292     void incrementSignificand();
 293     void initialize(const fltSemantics *);
 294     void shiftSignificandLeft(unsigned int);
 295     lostFraction shiftSignificandRight(unsigned int);
 296     unsigned int significandLSB() const;
 297     unsigned int significandMSB() const;
 298     void zeroSignificand();
 299
 300     /* Arithmetic on special values.  */
 301     opStatus addOrSubtractSpecials(const APFloat &, bool subtract);
 302     opStatus divideSpecials(const APFloat &);
 303     opStatus multiplySpecials(const APFloat &);
 304     opStatus modSpecials(const APFloat &);
 305
 306     /* Miscellany.  */
 307     void makeNaN(unsigned = 0);
 308     opStatus normalize(roundingMode, lostFraction);
 309     opStatus addOrSubtract(const APFloat &, roundingMode, bool subtract);
 310     cmpResult compareAbsoluteValue(const APFloat &) const;
 311     opStatus handleOverflow(roundingMode);
 312     bool roundAwayFromZero(roundingMode, lostFraction, unsigned int) const;
 313     opStatus convertToSignExtendedInteger(integerPart *, unsigned int, bool,
 314                                           roundingMode, bool *) const;
 315     opStatus convertFromUnsignedParts(const integerPart *, unsigned int,
 316                                       roundingMode);
 317     opStatus convertFromHexadecimalString(const StringRef&, roundingMode);
 318     opStatus convertFromDecimalString (const StringRef&, roundingMode);
 319     char *convertNormalToHexString(char *, unsigned int, bool,
 320                                    roundingMode) const;
 321     opStatus roundSignificandWithExponent(const integerPart *, unsigned int,
 322                                           int, roundingMode);
 323
 324     APInt convertFloatAPFloatToAPInt() const;
 325     APInt convertDoubleAPFloatToAPInt() const;
 326     APInt convertQuadrupleAPFloatToAPInt() const;
 327     APInt convertF80LongDoubleAPFloatToAPInt() const;
 328     APInt convertPPCDoubleDoubleAPFloatToAPInt() const;
 329     void initFromAPInt(const APInt& api, bool isIEEE = false);
 330     void initFromFloatAPInt(const APInt& api);
 331     void initFromDoubleAPInt(const APInt& api);
 332     void initFromQuadrupleAPInt(const APInt &api);
 333     void initFromF80LongDoubleAPInt(const APInt& api);
 334     void initFromPPCDoubleDoubleAPInt(const APInt& api);
 335
 336     void assign(const APFloat &);
 337     void copySignificand(const APFloat &);
 338     void freeSignificand();
 339
 340     /* What kind of semantics does this value obey?  */
 341     const fltSemantics *semantics;
 342
 343     /* Significand - the fraction with an explicit integer bit.  Must be
 344        at least one bit wider than the target precision.  */
 345     union Significand
 346     {
 347       integerPart part;
 348       integerPart *parts;
 349     } significand;
 350
 351     /* The exponent - a signed number.  */
 352     exponent_t exponent;
 353
 354     /* What kind of floating point number this is.  */
 355     /* Only 2 bits are required, but VisualStudio incorrectly sign extends
 356        it.  Using the extra bit keeps it from failing under VisualStudio */
 357     fltCategory category: 3;
 358
 359     /* The sign bit of this number.  */
 360     unsigned int sign: 1;
 361
 362     /* For PPCDoubleDouble, we have a second exponent and sign (the second
 363        significand is appended to the first one, although it would be wrong to
 364        regard these as a single number for arithmetic purposes).  These fields
 365        are not meaningful for any other type. */
 366     exponent_t exponent2 : 11;
 367     unsigned int sign2: 1;
 368   };
 369 } /* namespace llvm */
 370
 371 #endif /* LLVM_FLOAT_H */