Improve documentation.
[oota-llvm.git] / include / llvm / ADT / APInt.h
index 9d728d32b06643baf44f8fd35bd2ca1e4a5784b0..ca09ff68acffc9f2ecab7f192b5dc219384d678b 100644 (file)
@@ -59,7 +59,8 @@ namespace APIntOps {
 ///
 /// @brief Class for arbitrary precision integers.
 class APInt {
-  unsigned BitWidth;      ///< The number of bits in this APInt.
+public:
+  uint32_t BitWidth;      ///< The number of bits in this APInt.
 
   /// This union is used to store the integer value. When the
   /// integer bit-width <= 64, it uses VAL; 
@@ -71,13 +72,14 @@ class APInt {
 
   /// This enum is just used to hold a constant we needed for APInt.
   enum {
-    APINT_BITS_PER_WORD = sizeof(uint64_t) * 8
+    APINT_BITS_PER_WORD = sizeof(uint64_t) * 8,
+    APINT_WORD_SIZE = sizeof(uint64_t)
   };
 
   /// Here one word's bitwidth equals to that of uint64_t.
   /// @returns the number of words to hold the integer value of this APInt.
   /// @brief Get the number of words.
-  inline unsigned getNumWords() const {
+  inline uint32_t getNumWords() const {
     return (BitWidth + APINT_BITS_PER_WORD - 1) / APINT_BITS_PER_WORD;
   }
 
@@ -88,30 +90,25 @@ class APInt {
   }
 
   /// @returns the word position for the specified bit position.
-  static inline unsigned whichWord(unsigned bitPosition) { 
+  static inline uint32_t whichWord(uint32_t bitPosition) { 
     return bitPosition / APINT_BITS_PER_WORD; 
   }
 
-  /// @returns the byte position for the specified bit position.
-  static inline unsigned whichByte(unsigned bitPosition) { 
-    return (bitPosition % APINT_BITS_PER_WORD) / 8; 
-  }
-
   /// @returns the bit position in a word for the specified bit position 
   /// in APInt.
-  static inline unsigned whichBit(unsigned bitPosition) { 
+  static inline uint32_t whichBit(uint32_t bitPosition) { 
     return bitPosition % APINT_BITS_PER_WORD; 
   }
 
   /// @returns a uint64_t type integer with just bit position at
   /// "whichBit(bitPosition)" setting, others zero.
-  static inline uint64_t maskBit(unsigned bitPosition) { 
+  static inline uint64_t maskBit(uint32_t bitPosition) { 
     return (static_cast<uint64_t>(1)) << whichBit(bitPosition); 
   }
 
   /// This method is used internally to clear the to "N" bits that are not used
-  /// by the APInt. This is needed after a word is assigned a value to ensure 
-  /// that those bits are zero'd out.
+  /// by the APInt. This is needed after the most significant word is assigned 
+  /// a value to ensure that those bits are zero'd out.
   /// @brief Clear high order bits
   inline void clearUnusedBits() {
     if (isSingleWord())
@@ -122,35 +119,44 @@ class APInt {
   }
 
   /// @returns the corresponding word for the specified bit position.
-  inline uint64_t& getWord(unsigned bitPosition) { 
-    return isSingleWord() ? VAL : pVal[whichWord(bitPosition)]; 
-  }
-
-  /// @returns the corresponding word for the specified bit position.
-  /// This is a constant version.
-  inline uint64_t getWord(unsigned bitPosition) const { 
+  /// @brief Get the word corresponding to a bit position
+  inline uint64_t getWord(uint32_t bitPosition) const { 
     return isSingleWord() ? VAL : pVal[whichWord(bitPosition)]; 
   }
 
-  /// @brief Converts a char array into an integer.
-  void fromString(unsigned numBits, const char *StrStart, unsigned slen, 
+  /// This is used by the constructors that take string arguments.
+  /// @brief Converts a char array into an APInt
+  void fromString(uint32_t numBits, const char *StrStart, uint32_t slen, 
                   uint8_t radix);
 
+  /// This is used by the toString method to divide by the radix. It simply
+  /// provides a more convenient form of divide for internal use.
+  /// @brief An internal division function for dividing APInts.
+  static void divide(const APInt LHS, uint32_t lhsWords, 
+                     const APInt &RHS, uint32_t rhsWords,
+                     APInt *Quotient, APInt *Remainder);
+
+#ifndef NDEBUG
+  /// @brief debug method
+  void dump() const;
+#endif
+
 public:
-  /// @brief Create a new APInt of numBits bit-width, and initialized as val.
-  APInt(unsigned numBits, uint64_t val);
+  /// @brief Create a new APInt of numBits width, initialized as val.
+  APInt(uint32_t numBits, uint64_t val);
 
-  /// @brief Create a new APInt of numBits bit-width, and initialized as 
-  /// bigVal[].
-  APInt(unsigned numBits, unsigned numWords, uint64_t bigVal[]);
+  /// Note that numWords can be smaller or larger than the corresponding bit
+  /// width but any extraneous bits will be dropped.
+  /// @brief Create a new APInt of numBits width, initialized as bigVal[].
+  APInt(uint32_t numBits, uint32_t numWords, uint64_t bigVal[]);
 
   /// @brief Create a new APInt by translating the string represented 
   /// integer value.
-  APInt(unsigned numBits, const std::string& Val, uint8_t radix);
+  APInt(uint32_t numBits, const std::string& Val, uint8_t radix);
 
   /// @brief Create a new APInt by translating the char array represented
   /// integer value.
-  APInt(unsigned numBits, const char StrStart[], unsigned slen, uint8_t radix);
+  APInt(uint32_t numBits, const char StrStart[], uint32_t slen, uint8_t radix);
 
   /// @brief Copy Constructor.
   APInt(const APInt& API);
@@ -258,7 +264,7 @@ public:
   }
 
   /// @brief Array-indexing support.
-  bool operator[](unsigned bitPosition) const;
+  bool operator[](uint32_t bitPosition) const;
 
   /// Compare this APInt with the given APInt& RHS 
   /// for the validity of the equality relationship.
@@ -332,24 +338,24 @@ public:
 
   /// Arithmetic right-shift this APInt by shiftAmt.
   /// @brief Arithmetic right-shift function.
-  APInt ashr(unsigned shiftAmt) const;
+  APInt ashr(uint32_t shiftAmt) const;
 
   /// Logical right-shift this APInt by shiftAmt.
   /// @brief Logical right-shift function.
-  APInt lshr(unsigned shiftAmt) const;
+  APInt lshr(uint32_t shiftAmt) const;
 
   /// Left-shift this APInt by shiftAmt.
   /// @brief Left-shift function.
-  APInt shl(unsigned shiftAmt) const;
+  APInt shl(uint32_t shiftAmt) const;
 
   /// Signed divide this APInt by APInt RHS.
   /// @brief Signed division function for APInt.
   inline APInt sdiv(const APInt& RHS) const {
     bool isNegativeLHS = (*this)[BitWidth - 1];
     bool isNegativeRHS = RHS[RHS.BitWidth - 1];
-    APInt API = APIntOps::udiv(
+    APInt Result = APIntOps::udiv(
         isNegativeLHS ? -(*this) : (*this), isNegativeRHS ? -RHS : RHS);
-    return isNegativeLHS != isNegativeRHS ? -API : API;;
+    return isNegativeLHS != isNegativeRHS ? -Result : Result;
   }
 
   /// Unsigned divide this APInt by APInt RHS.
@@ -361,9 +367,9 @@ public:
   inline APInt srem(const APInt& RHS) const {
     bool isNegativeLHS = (*this)[BitWidth - 1];
     bool isNegativeRHS = RHS[RHS.BitWidth - 1];
-    APInt API = APIntOps::urem(
+    APInt Result = APIntOps::urem(
         isNegativeLHS ? -(*this) : (*this), isNegativeRHS ? -RHS : RHS);
-    return isNegativeLHS ? -API : API;
+    return isNegativeLHS ? -Result : Result;
   }
 
   /// Unsigned remainder operation on APInt.
@@ -373,34 +379,34 @@ public:
   /// Truncate the APInt to a specified width. It is an error to specify a width
   /// that is greater than or equal to the current width. 
   /// @brief Truncate to new width.
-  void trunc(unsigned width);
+  void trunc(uint32_t width);
 
   /// This operation sign extends the APInt to a new width. If the high order
   /// bit is set, the fill on the left will be done with 1 bits, otherwise zero.
   /// It is an error to specify a width that is less than or equal to the 
   /// current width.
   /// @brief Sign extend to a new width.
-  void sext(unsigned width);
+  void sext(uint32_t width);
 
   /// This operation zero extends the APInt to a new width. Thie high order bits
   /// are filled with 0 bits.  It is an error to specify a width that is less 
   /// than or equal to the current width.
   /// @brief Zero extend to a new width.
-  void zext(unsigned width);
+  void zext(uint32_t width);
 
   /// @brief Set every bit to 1.
   APInt& set();
 
   /// Set the given bit to 1 whose position is given as "bitPosition".
   /// @brief Set a given bit to 1.
-  APInt& set(unsigned bitPosition);
+  APInt& set(uint32_t bitPosition);
 
   /// @brief Set every bit to 0.
   APInt& clear();
 
   /// Set the given bit to 0 whose position is given as "bitPosition".
   /// @brief Set a given bit to 0.
-  APInt& clear(unsigned bitPosition);
+  APInt& clear(uint32_t bitPosition);
 
   /// @brief Toggle every bit to its opposite value.
   APInt& flip();
@@ -408,14 +414,14 @@ public:
   /// Toggle a given bit to its opposite value whose position is given 
   /// as "bitPosition".
   /// @brief Toggles a given bit to its opposite value.
-  APInt& flip(unsigned bitPosition);
+  APInt& flip(uint32_t bitPosition);
 
   /// This function returns the number of active bits which is defined as the
   /// bit width minus the number of leading zeros. This is used in several
   /// computations to see how "wide" the value is.
   /// @brief Compute the number of active bits in the value
-  inline unsigned getActiveBits() const {
-    return getNumWords() * APINT_BITS_PER_WORD - countLeadingZeros();
+  inline uint32_t getActiveBits() const {
+    return BitWidth - countLeadingZeros();
   }
 
   /// @returns a uint64_t value from this APInt. If this APInt contains a single
@@ -424,7 +430,7 @@ public:
     if (isSingleWord())
       return isSigned ? int64_t(VAL << (64 - BitWidth)) >> 
                                        (64 - BitWidth) : VAL;
-    unsigned n = getActiveBits();
+    uint32_t n = getActiveBits();
     if (n <= 64)
       return pVal[0];
     assert(0 && "This APInt's bitwidth > 64");
@@ -434,20 +440,20 @@ public:
   /// if isSign == true, it should be largest signed value, otherwise largest
   /// unsigned value.
   /// @brief Gets max value of the APInt with bitwidth <= 64.
-  static APInt getMaxValue(unsigned numBits, bool isSign);
+  static APInt getMaxValue(uint32_t numBits, bool isSign);
 
   /// @returns the smallest value for an APInt of the given bit-width and
   /// if isSign == true, it should be smallest signed value, otherwise zero.
   /// @brief Gets min value of the APInt with bitwidth <= 64.
-  static APInt getMinValue(unsigned numBits, bool isSign);
+  static APInt getMinValue(uint32_t numBits, bool isSign);
 
   /// @returns the all-ones value for an APInt of the specified bit-width.
   /// @brief Get the all-ones value.
-  static APInt getAllOnesValue(unsigned numBits);
+  static APInt getAllOnesValue(uint32_t numBits);
 
   /// @returns the '0' value for an APInt of the specified bit-width.
   /// @brief Get the '0' value.
-  static APInt getNullValue(unsigned numBits);
+  static APInt getNullValue(uint32_t numBits);
 
   /// This converts the APInt to a boolean valy as a test against zero.
   /// @brief Boolean conversion function. 
@@ -456,39 +462,39 @@ public:
   }
 
   /// @returns a character interpretation of the APInt.
-  std::string toString(uint8_t radix = 10) const;
+  std::string toString(uint8_t radix = 10, bool wantSigned = true) const;
 
   /// Get an APInt with the same BitWidth as this APInt, just zero mask
   /// the low bits and right shift to the least significant bit.
   /// @returns the high "numBits" bits of this APInt.
-  APInt getHiBits(unsigned numBits) const;
+  APInt getHiBits(uint32_t numBits) const;
 
   /// Get an APInt with the same BitWidth as this APInt, just zero mask
   /// the high bits.
   /// @returns the low "numBits" bits of this APInt.
-  APInt getLoBits(unsigned numBits) const;
+  APInt getLoBits(uint32_t numBits) const;
 
   /// @returns true if the argument APInt value is a power of two > 0.
   bool isPowerOf2() const; 
 
   /// @returns the number of zeros from the most significant bit to the first
   /// one bits.
-  unsigned countLeadingZeros() const;
+  uint32_t countLeadingZeros() const;
 
   /// @returns the number of zeros from the least significant bit to the first
   /// one bit.
-  unsigned countTrailingZeros() const;
+  uint32_t countTrailingZeros() const;
 
   /// @returns the number of set bits.
-  unsigned countPopulation() const; 
+  uint32_t countPopulation() const; 
 
   /// @returns the total number of bits.
-  inline unsigned getBitWidth() const { 
+  inline uint32_t getBitWidth() const { 
     return BitWidth; 
   }
 
   /// @brief Check if this APInt has a N-bits integer value.
-  inline bool isIntN(unsigned N) const {
+  inline bool isIntN(uint32_t N) const {
     assert(N && "N == 0 ???");
     if (isSingleWord()) {
       return VAL == (VAL & (~0ULL >> (64 - N)));
@@ -502,7 +508,7 @@ public:
   APInt byteSwap() const;
 
   /// @returns the floor log base 2 of this APInt.
-  inline unsigned logBase2() const {
+  inline uint32_t logBase2() const {
     return getNumWords() * APINT_BITS_PER_WORD - 1 - countLeadingZeros();
   }
 
@@ -514,19 +520,19 @@ public:
 namespace APIntOps {
 
 /// @brief Check if the specified APInt has a N-bits integer value.
-inline bool isIntN(unsigned N, const APInt& APIVal) {
+inline bool isIntN(uint32_t N, const APInt& APIVal) {
   return APIVal.isIntN(N);
 }
 
 /// @returns true if the argument APInt value is a sequence of ones
 /// starting at the least significant bit with the remainder zero.
-inline const bool isMask(unsigned numBits, const APInt& APIVal) {
+inline const bool isMask(uint32_t numBits, const APInt& APIVal) {
   return APIVal.getBoolValue() && ((APIVal + APInt(numBits,1)) & APIVal) == 0;
 }
 
 /// @returns true if the argument APInt value contains a sequence of ones
 /// with the remainder zero.
-inline const bool isShiftedMask(unsigned numBits, const APInt& APIVal) {
+inline const bool isShiftedMask(uint32_t numBits, const APInt& APIVal) {
   return isMask(numBits, (APIVal - APInt(numBits,1)) | APIVal);
 }
 
@@ -536,7 +542,7 @@ inline APInt byteSwap(const APInt& APIVal) {
 }
 
 /// @returns the floor log base 2 of the specified APInt value.
-inline unsigned logBase2(const APInt& APIVal) {
+inline uint32_t logBase2(const APInt& APIVal) {
   return APIVal.logBase2(); 
 }
 
@@ -564,19 +570,19 @@ inline APInt RoundFloatToAPInt(float Float) {
 
 /// Arithmetic right-shift the APInt by shiftAmt.
 /// @brief Arithmetic right-shift function.
-inline APInt ashr(const APInt& LHS, unsigned shiftAmt) {
+inline APInt ashr(const APInt& LHS, uint32_t shiftAmt) {
   return LHS.ashr(shiftAmt);
 }
 
 /// Logical right-shift the APInt by shiftAmt.
 /// @brief Logical right-shift function.
-inline APInt lshr(const APInt& LHS, unsigned shiftAmt) {
+inline APInt lshr(const APInt& LHS, uint32_t shiftAmt) {
   return LHS.lshr(shiftAmt);
 }
 
 /// Left-shift the APInt by shiftAmt.
 /// @brief Left-shift function.
-inline APInt shl(const APInt& LHS, unsigned shiftAmt) {
+inline APInt shl(const APInt& LHS, uint32_t shiftAmt) {
   return LHS.shl(shiftAmt);
 }