LLVM  4.0.0
ConstantRange.h
Go to the documentation of this file.
1 //===- ConstantRange.h - Represent a range ----------------------*- 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 // Represent a range of possible values that may occur when the program is run
11 // for an integral value. This keeps track of a lower and upper bound for the
12 // constant, which MAY wrap around the end of the numeric range. To do this, it
13 // keeps track of a [lower, upper) bound, which specifies an interval just like
14 // STL iterators. When used with boolean values, the following are important
15 // ranges: :
16 //
17 // [F, F) = {} = Empty set
18 // [T, F) = {T}
19 // [F, T) = {F}
20 // [T, T) = {F, T} = Full set
21 //
22 // The other integral ranges use min/max values for special range values. For
23 // example, for 8-bit types, it uses:
24 // [0, 0) = {} = Empty set
25 // [255, 255) = {0..255} = Full Set
26 //
27 // Note that ConstantRange can be used to represent either signed or
28 // unsigned ranges.
29 //
30 //===----------------------------------------------------------------------===//
31 
32 #ifndef LLVM_IR_CONSTANTRANGE_H
33 #define LLVM_IR_CONSTANTRANGE_H
34 
35 #include "llvm/ADT/APInt.h"
36 #include "llvm/IR/InstrTypes.h"
37 #include "llvm/Support/DataTypes.h"
38 
39 namespace llvm {
40 
41 class MDNode;
42 
43 /// This class represents a range of values.
44 ///
46  APInt Lower, Upper;
47 
48  // If we have move semantics, pass APInts by value and move them into place.
49  typedef APInt APIntMoveTy;
50 
51 public:
52  /// Initialize a full (the default) or empty set for the specified bit width.
53  ///
54  explicit ConstantRange(uint32_t BitWidth, bool isFullSet = true);
55 
56  /// Initialize a range to hold the single specified value.
57  ///
59 
60  /// @brief Initialize a range of values explicitly. This will assert out if
61  /// Lower==Upper and Lower != Min or Max value for its type. It will also
62  /// assert out if the two APInt's are not the same bit width.
64 
65  /// Produce the smallest range such that all values that may satisfy the given
66  /// predicate with any value contained within Other is contained in the
67  /// returned range. Formally, this returns a superset of
68  /// 'union over all y in Other . { x : icmp op x y is true }'. If the exact
69  /// answer is not representable as a ConstantRange, the return value will be a
70  /// proper superset of the above.
71  ///
72  /// Example: Pred = ult and Other = i8 [2, 5) returns Result = [0, 4)
74  const ConstantRange &Other);
75 
76  /// Produce the largest range such that all values in the returned range
77  /// satisfy the given predicate with all values contained within Other.
78  /// Formally, this returns a subset of
79  /// 'intersection over all y in Other . { x : icmp op x y is true }'. If the
80  /// exact answer is not representable as a ConstantRange, the return value
81  /// will be a proper subset of the above.
82  ///
83  /// Example: Pred = ult and Other = i8 [2, 5) returns [0, 2)
85  const ConstantRange &Other);
86 
87  /// Produce the exact range such that all values in the returned range satisfy
88  /// the given predicate with any value contained within Other. Formally, this
89  /// returns the exact answer when the superset of 'union over all y in Other
90  /// is exactly same as the subset of intersection over all y in Other.
91  /// { x : icmp op x y is true}'.
92  ///
93  /// Example: Pred = ult and Other = i8 3 returns [0, 3)
95  const APInt &Other);
96 
97  /// Return the largest range containing all X such that "X BinOpC Y" is
98  /// guaranteed not to wrap (overflow) for all Y in Other.
99  ///
100  /// NB! The returned set does *not* contain **all** possible values of X for
101  /// which "X BinOpC Y" does not wrap -- some viable values of X may be
102  /// missing, so you cannot use this to contrain X's range. E.g. in the last
103  /// example, "(-2) + 1" is both nsw and nuw (so the "X" could be -2), but (-2)
104  /// is not in the set returned.
105  ///
106  /// Examples:
107  /// typedef OverflowingBinaryOperator OBO;
108  /// #define MGNR makeGuaranteedNoWrapRegion
109  /// MGNR(Add, [i8 1, 2), OBO::NoSignedWrap) == [-128, 127)
110  /// MGNR(Add, [i8 1, 2), OBO::NoUnsignedWrap) == [0, -1)
111  /// MGNR(Add, [i8 0, 1), OBO::NoUnsignedWrap) == Full Set
112  /// MGNR(Add, [i8 1, 2), OBO::NoUnsignedWrap | OBO::NoSignedWrap)
113  /// == [0,INT_MAX)
114  /// MGNR(Add, [i8 -1, 6), OBO::NoSignedWrap) == [INT_MIN+1, INT_MAX-4)
116  const ConstantRange &Other,
117  unsigned NoWrapKind);
118 
119  /// Set up \p Pred and \p RHS such that
120  /// ConstantRange::makeExactICmpRegion(Pred, RHS) == *this. Return true if
121  /// successful.
122  bool getEquivalentICmp(CmpInst::Predicate &Pred, APInt &RHS) const;
123 
124  /// Return the lower value for this range.
125  ///
126  const APInt &getLower() const { return Lower; }
127 
128  /// Return the upper value for this range.
129  ///
130  const APInt &getUpper() const { return Upper; }
131 
132  /// Get the bit width of this ConstantRange.
133  ///
134  uint32_t getBitWidth() const { return Lower.getBitWidth(); }
135 
136  /// Return true if this set contains all of the elements possible
137  /// for this data-type.
138  ///
139  bool isFullSet() const;
140 
141  /// Return true if this set contains no members.
142  ///
143  bool isEmptySet() const;
144 
145  /// Return true if this set wraps around the top of the range.
146  /// For example: [100, 8).
147  ///
148  bool isWrappedSet() const;
149 
150  /// Return true if this set wraps around the INT_MIN of
151  /// its bitwidth. For example: i8 [120, 140).
152  ///
153  bool isSignWrappedSet() const;
154 
155  /// Return true if the specified value is in the set.
156  ///
157  bool contains(const APInt &Val) const;
158 
159  /// Return true if the other range is a subset of this one.
160  ///
161  bool contains(const ConstantRange &CR) const;
162 
163  /// If this set contains a single element, return it, otherwise return null.
164  ///
165  const APInt *getSingleElement() const {
166  if (Upper == Lower + 1)
167  return &Lower;
168  return nullptr;
169  }
170 
171  /// If this set contains all but a single element, return it, otherwise return
172  /// null.
174  if (Lower == Upper + 1)
175  return &Upper;
176  return nullptr;
177  }
178 
179  /// Return true if this set contains exactly one member.
180  ///
181  bool isSingleElement() const { return getSingleElement() != nullptr; }
182 
183  /// Return the number of elements in this set.
184  ///
185  APInt getSetSize() const;
186 
187  /// Return the largest unsigned value contained in the ConstantRange.
188  ///
189  APInt getUnsignedMax() const;
190 
191  /// Return the smallest unsigned value contained in the ConstantRange.
192  ///
193  APInt getUnsignedMin() const;
194 
195  /// Return the largest signed value contained in the ConstantRange.
196  ///
197  APInt getSignedMax() const;
198 
199  /// Return the smallest signed value contained in the ConstantRange.
200  ///
201  APInt getSignedMin() const;
202 
203  /// Return true if this range is equal to another range.
204  ///
205  bool operator==(const ConstantRange &CR) const {
206  return Lower == CR.Lower && Upper == CR.Upper;
207  }
208  bool operator!=(const ConstantRange &CR) const {
209  return !operator==(CR);
210  }
211 
212  /// Subtract the specified constant from the endpoints of this constant range.
213  ConstantRange subtract(const APInt &CI) const;
214 
215  /// \brief Subtract the specified range from this range (aka relative
216  /// complement of the sets).
217  ConstantRange difference(const ConstantRange &CR) const;
218 
219  /// Return the range that results from the intersection of
220  /// this range with another range. The resultant range is guaranteed to
221  /// include all elements contained in both input ranges, and to have the
222  /// smallest possible set size that does so. Because there may be two
223  /// intersections with the same set size, A.intersectWith(B) might not
224  /// be equal to B.intersectWith(A).
225  ///
226  ConstantRange intersectWith(const ConstantRange &CR) const;
227 
228  /// Return the range that results from the union of this range
229  /// with another range. The resultant range is guaranteed to include the
230  /// elements of both sets, but may contain more. For example, [3, 9) union
231  /// [12,15) is [3, 15), which includes 9, 10, and 11, which were not included
232  /// in either set before.
233  ///
234  ConstantRange unionWith(const ConstantRange &CR) const;
235 
236  /// Return a new range representing the possible values resulting
237  /// from an application of the specified cast operator to this range. \p
238  /// BitWidth is the target bitwidth of the cast. For casts which don't
239  /// change bitwidth, it must be the same as the source bitwidth. For casts
240  /// which do change bitwidth, the bitwidth must be consistent with the
241  /// requested cast and source bitwidth.
243  uint32_t BitWidth) const;
244 
245  /// Return a new range in the specified integer type, which must
246  /// be strictly larger than the current type. The returned range will
247  /// correspond to the possible range of values if the source range had been
248  /// zero extended to BitWidth.
249  ConstantRange zeroExtend(uint32_t BitWidth) const;
250 
251  /// Return a new range in the specified integer type, which must
252  /// be strictly larger than the current type. The returned range will
253  /// correspond to the possible range of values if the source range had been
254  /// sign extended to BitWidth.
255  ConstantRange signExtend(uint32_t BitWidth) const;
256 
257  /// Return a new range in the specified integer type, which must be
258  /// strictly smaller than the current type. The returned range will
259  /// correspond to the possible range of values if the source range had been
260  /// truncated to the specified type.
261  ConstantRange truncate(uint32_t BitWidth) const;
262 
263  /// Make this range have the bit width given by \p BitWidth. The
264  /// value is zero extended, truncated, or left alone to make it that width.
265  ConstantRange zextOrTrunc(uint32_t BitWidth) const;
266 
267  /// Make this range have the bit width given by \p BitWidth. The
268  /// value is sign extended, truncated, or left alone to make it that width.
269  ConstantRange sextOrTrunc(uint32_t BitWidth) const;
270 
271  /// Return a new range representing the possible values resulting
272  /// from an application of the specified binary operator to an left hand side
273  /// of this range and a right hand side of \p Other.
275  const ConstantRange &Other) const;
276 
277  /// Return a new range representing the possible values resulting
278  /// from an addition of a value in this range and a value in \p Other.
279  ConstantRange add(const ConstantRange &Other) const;
280 
281  /// Return a new range representing the possible values resulting from a
282  /// known NSW addition of a value in this range and \p Other constant.
283  ConstantRange addWithNoSignedWrap(const APInt &Other) const;
284 
285  /// Return a new range representing the possible values resulting
286  /// from a subtraction of a value in this range and a value in \p Other.
287  ConstantRange sub(const ConstantRange &Other) const;
288 
289  /// Return a new range representing the possible values resulting
290  /// from a multiplication of a value in this range and a value in \p Other,
291  /// treating both this and \p Other as unsigned ranges.
292  ConstantRange multiply(const ConstantRange &Other) const;
293 
294  /// Return a new range representing the possible values resulting
295  /// from a signed maximum of a value in this range and a value in \p Other.
296  ConstantRange smax(const ConstantRange &Other) const;
297 
298  /// Return a new range representing the possible values resulting
299  /// from an unsigned maximum of a value in this range and a value in \p Other.
300  ConstantRange umax(const ConstantRange &Other) const;
301 
302  /// Return a new range representing the possible values resulting
303  /// from a signed minimum of a value in this range and a value in \p Other.
304  ConstantRange smin(const ConstantRange &Other) const;
305 
306  /// Return a new range representing the possible values resulting
307  /// from an unsigned minimum of a value in this range and a value in \p Other.
308  ConstantRange umin(const ConstantRange &Other) const;
309 
310  /// Return a new range representing the possible values resulting
311  /// from an unsigned division of a value in this range and a value in
312  /// \p Other.
313  ConstantRange udiv(const ConstantRange &Other) const;
314 
315  /// Return a new range representing the possible values resulting
316  /// from a binary-and of a value in this range by a value in \p Other.
317  ConstantRange binaryAnd(const ConstantRange &Other) const;
318 
319  /// Return a new range representing the possible values resulting
320  /// from a binary-or of a value in this range by a value in \p Other.
321  ConstantRange binaryOr(const ConstantRange &Other) const;
322 
323  /// Return a new range representing the possible values resulting
324  /// from a left shift of a value in this range by a value in \p Other.
325  /// TODO: This isn't fully implemented yet.
326  ConstantRange shl(const ConstantRange &Other) const;
327 
328  /// Return a new range representing the possible values resulting from a
329  /// logical right shift of a value in this range and a value in \p Other.
330  ConstantRange lshr(const ConstantRange &Other) const;
331 
332  /// Return a new range that is the logical not of the current set.
333  ///
334  ConstantRange inverse() const;
335 
336  /// Print out the bounds to a stream.
337  ///
338  void print(raw_ostream &OS) const;
339 
340  /// Allow printing from a debugger easily.
341  ///
342  void dump() const;
343 };
344 
346  CR.print(OS);
347  return OS;
348 }
349 
350 /// Parse out a conservative ConstantRange from !range metadata.
351 ///
352 /// E.g. if RangeMD is !{i32 0, i32 10, i32 15, i32 20} then return [0, 20).
353 ConstantRange getConstantRangeFromMetadata(const MDNode &RangeMD);
354 
355 } // End llvm namespace
356 
357 #endif
APInt getSignedMin() const
Return the smallest signed value contained in the ConstantRange.
bool operator==(const ConstantRange &CR) const
Return true if this range is equal to another range.
ConstantRange sextOrTrunc(uint32_t BitWidth) const
Make this range have the bit width given by BitWidth.
const APInt * getSingleElement() const
If this set contains a single element, return it, otherwise return null.
uint32_t getBitWidth() const
Get the bit width of this ConstantRange.
bool getEquivalentICmp(CmpInst::Predicate &Pred, APInt &RHS) const
Set up Pred and RHS such that ConstantRange::makeExactICmpRegion(Pred, RHS) == *this.
APInt getSignedMax() const
Return the largest signed value contained in the ConstantRange.
bool isSingleElement() const
Return true if this set contains exactly one member.
static ConstantRange makeAllowedICmpRegion(CmpInst::Predicate Pred, const ConstantRange &Other)
Produce the smallest range such that all values that may satisfy the given predicate with any value c...
ConstantRange smax(const ConstantRange &Other) const
Return a new range representing the possible values resulting from a signed maximum of a value in thi...
ConstantRange truncate(uint32_t BitWidth) const
Return a new range in the specified integer type, which must be strictly smaller than the current typ...
ConstantRange signExtend(uint32_t BitWidth) const
Return a new range in the specified integer type, which must be strictly larger than the current type...
ELFYAML::ELF_STO Other
Definition: ELFYAML.cpp:662
This file implements a class to represent arbitrary precision integral constant values and operations...
ConstantRange multiply(const ConstantRange &Other) const
Return a new range representing the possible values resulting from a multiplication of a value in thi...
bool operator!=(const ConstantRange &CR) const
bool contains(const APInt &Val) const
Return true if the specified value is in the set.
ConstantRange unionWith(const ConstantRange &CR) const
Return the range that results from the union of this range with another range.
ConstantRange subtract(const APInt &CI) const
Subtract the specified constant from the endpoints of this constant range.
static ConstantRange makeSatisfyingICmpRegion(CmpInst::Predicate Pred, const ConstantRange &Other)
Produce the largest range such that all values in the returned range satisfy the given predicate with...
void dump() const
Allow printing from a debugger easily.
ConstantRange intersectWith(const ConstantRange &CR) const
Return the range that results from the intersection of this range with another range.
bool isFullSet() const
Return true if this set contains all of the elements possible for this data-type. ...
ConstantRange lshr(const ConstantRange &Other) const
Return a new range representing the possible values resulting from a logical right shift of a value i...
ConstantRange getConstantRangeFromMetadata(const MDNode &RangeMD)
Parse out a conservative ConstantRange from !range metadata.
const APInt * getSingleMissingElement() const
If this set contains all but a single element, return it, otherwise return null.
bool isWrappedSet() const
Return true if this set wraps around the top of the range.
ConstantRange udiv(const ConstantRange &Other) const
Return a new range representing the possible values resulting from an unsigned division of a value in...
ConstantRange(uint32_t BitWidth, bool isFullSet=true)
Initialize a full (the default) or empty set for the specified bit width.
ConstantRange castOp(Instruction::CastOps CastOp, uint32_t BitWidth) const
Return a new range representing the possible values resulting from an application of the specified ca...
Predicate
This enumeration lists the possible predicates for CmpInst subclasses.
Definition: InstrTypes.h:880
unsigned getBitWidth() const
Return the number of bits in the APInt.
Definition: APInt.h:1255
ConstantRange binaryOp(Instruction::BinaryOps BinOp, const ConstantRange &Other) const
Return a new range representing the possible values resulting from an application of the specified bi...
ConstantRange addWithNoSignedWrap(const APInt &Other) const
Return a new range representing the possible values resulting from a known NSW addition of a value in...
ConstantRange sub(const ConstantRange &Other) const
Return a new range representing the possible values resulting from a subtraction of a value in this r...
void print(raw_ostream &OS) const
Print out the bounds to a stream.
ConstantRange zeroExtend(uint32_t BitWidth) const
Return a new range in the specified integer type, which must be strictly larger than the current type...
bool isEmptySet() const
Return true if this set contains no members.
ConstantRange difference(const ConstantRange &CR) const
Subtract the specified range from this range (aka relative complement of the sets).
ConstantRange add(const ConstantRange &Other) const
Return a new range representing the possible values resulting from an addition of a value in this ran...
static ConstantRange makeExactICmpRegion(CmpInst::Predicate Pred, const APInt &Other)
Produce the exact range such that all values in the returned range satisfy the given predicate with a...
bool isSignWrappedSet() const
Return true if this set wraps around the INT_MIN of its bitwidth.
APInt getSetSize() const
Return the number of elements in this set.
ConstantRange inverse() const
Return a new range that is the logical not of the current set.
This class represents a range of values.
Definition: ConstantRange.h:45
const APInt & getLower() const
Return the lower value for this range.
ConstantRange umin(const ConstantRange &Other) const
Return a new range representing the possible values resulting from an unsigned minimum of a value in ...
ConstantRange binaryOr(const ConstantRange &Other) const
Return a new range representing the possible values resulting from a binary-or of a value in this ran...
Class for arbitrary precision integers.
Definition: APInt.h:77
ConstantRange shl(const ConstantRange &Other) const
Return a new range representing the possible values resulting from a left shift of a value in this ra...
ConstantRange umax(const ConstantRange &Other) const
Return a new range representing the possible values resulting from an unsigned maximum of a value in ...
ConstantRange binaryAnd(const ConstantRange &Other) const
Return a new range representing the possible values resulting from a binary-and of a value in this ra...
raw_ostream & operator<<(raw_ostream &OS, const APInt &I)
Definition: APInt.h:1726
const APInt & getUpper() const
Return the upper value for this range.
static ConstantRange makeGuaranteedNoWrapRegion(Instruction::BinaryOps BinOp, const ConstantRange &Other, unsigned NoWrapKind)
Return the largest range containing all X such that "X BinOpC Y" is guaranteed not to wrap (overflow)...
LLVM Value Representation.
Definition: Value.h:71
ConstantRange smin(const ConstantRange &Other) const
Return a new range representing the possible values resulting from a signed minimum of a value in thi...
ConstantRange zextOrTrunc(uint32_t BitWidth) const
Make this range have the bit width given by BitWidth.
This class implements an extremely fast bulk output stream that can only output to a stream...
Definition: raw_ostream.h:44
APInt getUnsignedMax() const
Return the largest unsigned value contained in the ConstantRange.
APInt getUnsignedMin() const
Return the smallest unsigned value contained in the ConstantRange.