contrib/llvm/tools/clang/include/clang/Basic/FixedPoint.h

   1 //===- FixedPoint.h - Fixed point constant handling -------------*- C++ -*-===//
   2 //
   3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
   4 // See https://llvm.org/LICENSE.txt for license information.
   5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   6 //
   7 //===----------------------------------------------------------------------===//
   8 //
   9 /// \file
  10 /// Defines the fixed point number interface.
  11 /// This is a class for abstracting various operations performed on fixed point
  12 /// types described in ISO/IEC JTC1 SC22 WG14 N1169 starting at clause 4.
  13 //
  14 //===----------------------------------------------------------------------===//
  15
  16 #ifndef LLVM_CLANG_BASIC_FIXEDPOINT_H
  17 #define LLVM_CLANG_BASIC_FIXEDPOINT_H
  18
  19 #include "llvm/ADT/APSInt.h"
  20 #include "llvm/ADT/SmallString.h"
  21 #include "llvm/Support/raw_ostream.h"
  22
  23 namespace clang {
  24
  25 class ASTContext;
  26 class QualType;
  27
  28 /// The fixed point semantics work similarly to llvm::fltSemantics. The width
  29 /// specifies the whole bit width of the underlying scaled integer (with padding
  30 /// if any). The scale represents the number of fractional bits in this type.
  31 /// When HasUnsignedPadding is true and this type is signed, the first bit
  32 /// in the value this represents is treaded as padding.
  33 class FixedPointSemantics {
  34 public:
  35   FixedPointSemantics(unsigned Width, unsigned Scale, bool IsSigned,
  36                       bool IsSaturated, bool HasUnsignedPadding)
  37       : Width(Width), Scale(Scale), IsSigned(IsSigned),
  38         IsSaturated(IsSaturated), HasUnsignedPadding(HasUnsignedPadding) {
  39     assert(Width >= Scale && "Not enough room for the scale");
  40     assert(!(IsSigned && HasUnsignedPadding) &&
  41            "Cannot have unsigned padding on a signed type.");
  42   }
  43
  44   unsigned getWidth() const { return Width; }
  45   unsigned getScale() const { return Scale; }
  46   bool isSigned() const { return IsSigned; }
  47   bool isSaturated() const { return IsSaturated; }
  48   bool hasUnsignedPadding() const { return HasUnsignedPadding; }
  49
  50   void setSaturated(bool Saturated) { IsSaturated = Saturated; }
  51
  52   /// Return the number of integral bits represented by these semantics. These
  53   /// are separate from the fractional bits and do not include the sign or
  54   /// padding bit.
  55   unsigned getIntegralBits() const {
  56     if (IsSigned || (!IsSigned && HasUnsignedPadding))
  57       return Width - Scale - 1;
  58     else
  59       return Width - Scale;
  60   }
  61
  62   /// Return the FixedPointSemantics that allows for calculating the full
  63   /// precision semantic that can precisely represent the precision and ranges
  64   /// of both input values. This does not compute the resulting semantics for a
  65   /// given binary operation.
  66   FixedPointSemantics
  67   getCommonSemantics(const FixedPointSemantics &Other) const;
  68
  69   /// Return the FixedPointSemantics for an integer type.
  70   static FixedPointSemantics GetIntegerSemantics(unsigned Width,
  71                                                  bool IsSigned) {
  72     return FixedPointSemantics(Width, /*Scale=*/0, IsSigned,
  73                                /*IsSaturated=*/false,
  74                                /*HasUnsignedPadding=*/false);
  75   }
  76
  77 private:
  78   unsigned Width;
  79   unsigned Scale;
  80   bool IsSigned;
  81   bool IsSaturated;
  82   bool HasUnsignedPadding;
  83 };
  84
  85 /// The APFixedPoint class works similarly to APInt/APSInt in that it is a
  86 /// functional replacement for a scaled integer. It is meant to replicate the
  87 /// fixed point types proposed in ISO/IEC JTC1 SC22 WG14 N1169. The class carries
  88 /// info about the fixed point type's width, sign, scale, and saturation, and
  89 /// provides different operations that would normally be performed on fixed point
  90 /// types.
  91 ///
  92 /// Semantically this does not represent any existing C type other than fixed
  93 /// point types and should eventually be moved to LLVM if fixed point types gain
  94 /// native IR support.
  95 class APFixedPoint {
  96  public:
  97    APFixedPoint(const llvm::APInt &Val, const FixedPointSemantics &Sema)
  98        : Val(Val, !Sema.isSigned()), Sema(Sema) {
  99      assert(Val.getBitWidth() == Sema.getWidth() &&
 100             "The value should have a bit width that matches the Sema width");
 101    }
 102
 103    APFixedPoint(uint64_t Val, const FixedPointSemantics &Sema)
 104        : APFixedPoint(llvm::APInt(Sema.getWidth(), Val, Sema.isSigned()),
 105                       Sema) {}
 106
 107    // Zero initialization.
 108    APFixedPoint(const FixedPointSemantics &Sema) : APFixedPoint(0, Sema) {}
 109
 110    llvm::APSInt getValue() const { return llvm::APSInt(Val, !Sema.isSigned()); }
 111    inline unsigned getWidth() const { return Sema.getWidth(); }
 112    inline unsigned getScale() const { return Sema.getScale(); }
 113    inline bool isSaturated() const { return Sema.isSaturated(); }
 114    inline bool isSigned() const { return Sema.isSigned(); }
 115    inline bool hasPadding() const { return Sema.hasUnsignedPadding(); }
 116    FixedPointSemantics getSemantics() const { return Sema; }
 117
 118    bool getBoolValue() const { return Val.getBoolValue(); }
 119
 120    // Convert this number to match the semantics provided. If the overflow
 121    // parameter is provided, set this value to true or false to indicate if this
 122    // operation results in an overflow.
 123    APFixedPoint convert(const FixedPointSemantics &DstSema,
 124                         bool *Overflow = nullptr) const;
 125
 126    // Perform binary operations on a fixed point type. The resulting fixed point
 127    // value will be in the common, full precision semantics that can represent
 128    // the precision and ranges os both input values. See convert() for an
 129    // explanation of the Overflow parameter.
 130    APFixedPoint add(const APFixedPoint &Other, bool *Overflow = nullptr) const;
 131
 132    /// Perform a unary negation (-X) on this fixed point type, taking into
 133    /// account saturation if applicable.
 134    APFixedPoint negate(bool *Overflow = nullptr) const;
 135
 136    APFixedPoint shr(unsigned Amt) const {
 137      return APFixedPoint(Val >> Amt, Sema);
 138    }
 139
 140   APFixedPoint shl(unsigned Amt) const {
 141     return APFixedPoint(Val << Amt, Sema);
 142   }
 143
 144   /// Return the integral part of this fixed point number, rounded towards
 145   /// zero. (-2.5k -> -2)
 146   llvm::APSInt getIntPart() const {
 147     if (Val < 0 && Val != -Val) // Cover the case when we have the min val
 148       return -(-Val >> getScale());
 149     else
 150       return Val >> getScale();
 151   }
 152
 153   /// Return the integral part of this fixed point number, rounded towards
 154   /// zero. The value is stored into an APSInt with the provided width and sign.
 155   /// If the overflow parameter is provided, and the integral value is not able
 156   /// to be fully stored in the provided width and sign, the overflow parameter
 157   /// is set to true.
 158   ///
 159   /// If the overflow parameter is provided, set this value to true or false to
 160   /// indicate if this operation results in an overflow.
 161   llvm::APSInt convertToInt(unsigned DstWidth, bool DstSign,
 162                             bool *Overflow = nullptr) const;
 163
 164   void toString(llvm::SmallVectorImpl<char> &Str) const;
 165   std::string toString() const {
 166     llvm::SmallString<40> S;
 167     toString(S);
 168     return S.str();
 169   }
 170
 171   // If LHS > RHS, return 1. If LHS == RHS, return 0. If LHS < RHS, return -1.
 172   int compare(const APFixedPoint &Other) const;
 173   bool operator==(const APFixedPoint &Other) const {
 174     return compare(Other) == 0;
 175   }
 176   bool operator!=(const APFixedPoint &Other) const {
 177     return compare(Other) != 0;
 178   }
 179   bool operator>(const APFixedPoint &Other) const { return compare(Other) > 0; }
 180   bool operator<(const APFixedPoint &Other) const { return compare(Other) < 0; }
 181   bool operator>=(const APFixedPoint &Other) const {
 182     return compare(Other) >= 0;
 183   }
 184   bool operator<=(const APFixedPoint &Other) const {
 185     return compare(Other) <= 0;
 186   }
 187
 188   static APFixedPoint getMax(const FixedPointSemantics &Sema);
 189   static APFixedPoint getMin(const FixedPointSemantics &Sema);
 190
 191   /// Create an APFixedPoint with a value equal to that of the provided integer,
 192   /// and in the same semantics as the provided target semantics. If the value
 193   /// is not able to fit in the specified fixed point semantics, and the
 194   /// overflow parameter is provided, it is set to true.
 195   static APFixedPoint getFromIntValue(const llvm::APSInt &Value,
 196                                       const FixedPointSemantics &DstFXSema,
 197                                       bool *Overflow = nullptr);
 198
 199 private:
 200   llvm::APSInt Val;
 201   FixedPointSemantics Sema;
 202 };
 203
 204 inline llvm::raw_ostream &operator<<(llvm::raw_ostream &OS,
 205                                      const APFixedPoint &FX) {
 206   OS << FX.toString();
 207   return OS;
 208 }
 209
 210 }  // namespace clang
 211
 212 #endif