1 //===- SourceLocation.h - Compact identifier for Source Files ---*- 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 clang::SourceLocation class and associated facilities. 11 // 12 //===----------------------------------------------------------------------===// 13 14 #ifndef LLVM_CLANG_BASIC_SOURCELOCATION_H 15 #define LLVM_CLANG_BASIC_SOURCELOCATION_H 16 17 #include "clang/Basic/LLVM.h" 18 #include "llvm/ADT/StringRef.h" 19 #include <cassert> 20 #include <cstdint> 21 #include <string> 22 #include <utility> 23 24 namespace llvm { 25 26 template <typename T> struct DenseMapInfo; 27 28 class FoldingSetNodeID; 29 template <typename T> struct FoldingSetTrait; 30 31 } // namespace llvm 32 33 namespace clang { 34 35 class SourceManager; 36 37 /// An opaque identifier used by SourceManager which refers to a 38 /// source file (MemoryBuffer) along with its \#include path and \#line data. 39 /// 40 class FileID { 41 /// A mostly-opaque identifier, where 0 is "invalid", >0 is 42 /// this module, and <-1 is something loaded from another module. 43 int ID = 0; 44 45 public: isValid()46 bool isValid() const { return ID != 0; } isInvalid()47 bool isInvalid() const { return ID == 0; } 48 49 bool operator==(const FileID &RHS) const { return ID == RHS.ID; } 50 bool operator<(const FileID &RHS) const { return ID < RHS.ID; } 51 bool operator<=(const FileID &RHS) const { return ID <= RHS.ID; } 52 bool operator!=(const FileID &RHS) const { return !(*this == RHS); } 53 bool operator>(const FileID &RHS) const { return RHS < *this; } 54 bool operator>=(const FileID &RHS) const { return RHS <= *this; } 55 getSentinel()56 static FileID getSentinel() { return get(-1); } getHashValue()57 unsigned getHashValue() const { return static_cast<unsigned>(ID); } 58 59 private: 60 friend class ASTWriter; 61 friend class ASTReader; 62 friend class SourceManager; 63 get(int V)64 static FileID get(int V) { 65 FileID F; 66 F.ID = V; 67 return F; 68 } 69 getOpaqueValue()70 int getOpaqueValue() const { return ID; } 71 }; 72 73 /// Encodes a location in the source. The SourceManager can decode this 74 /// to get at the full include stack, line and column information. 75 /// 76 /// Technically, a source location is simply an offset into the manager's view 77 /// of the input source, which is all input buffers (including macro 78 /// expansions) concatenated in an effectively arbitrary order. The manager 79 /// actually maintains two blocks of input buffers. One, starting at offset 80 /// 0 and growing upwards, contains all buffers from this module. The other, 81 /// starting at the highest possible offset and growing downwards, contains 82 /// buffers of loaded modules. 83 /// 84 /// In addition, one bit of SourceLocation is used for quick access to the 85 /// information whether the location is in a file or a macro expansion. 86 /// 87 /// It is important that this type remains small. It is currently 32 bits wide. 88 class SourceLocation { 89 friend class ASTReader; 90 friend class ASTWriter; 91 friend class SourceManager; 92 friend struct llvm::FoldingSetTrait<SourceLocation>; 93 94 public: 95 using UIntTy = uint32_t; 96 using IntTy = int32_t; 97 98 private: 99 UIntTy ID = 0; 100 101 enum : UIntTy { MacroIDBit = 1ULL << (8 * sizeof(UIntTy) - 1) }; 102 103 public: 104 bool isFileID() const { return (ID & MacroIDBit) == 0; } 105 bool isMacroID() const { return (ID & MacroIDBit) != 0; } 106 107 /// Return true if this is a valid SourceLocation object. 108 /// 109 /// Invalid SourceLocations are often used when events have no corresponding 110 /// location in the source (e.g. a diagnostic is required for a command line 111 /// option). 112 bool isValid() const { return ID != 0; } 113 bool isInvalid() const { return ID == 0; } 114 115 private: 116 /// Return the offset into the manager's global input view. 117 UIntTy getOffset() const { return ID & ~MacroIDBit; } 118 119 static SourceLocation getFileLoc(UIntTy ID) { 120 assert((ID & MacroIDBit) == 0 && "Ran out of source locations!"); 121 SourceLocation L; 122 L.ID = ID; 123 return L; 124 } 125 126 static SourceLocation getMacroLoc(UIntTy ID) { 127 assert((ID & MacroIDBit) == 0 && "Ran out of source locations!"); 128 SourceLocation L; 129 L.ID = MacroIDBit | ID; 130 return L; 131 } 132 133 public: 134 /// Return a source location with the specified offset from this 135 /// SourceLocation. 136 SourceLocation getLocWithOffset(IntTy Offset) const { 137 assert(((getOffset()+Offset) & MacroIDBit) == 0 && "offset overflow"); 138 SourceLocation L; 139 L.ID = ID+Offset; 140 return L; 141 } 142 143 /// When a SourceLocation itself cannot be used, this returns 144 /// an (opaque) 32-bit integer encoding for it. 145 /// 146 /// This should only be passed to SourceLocation::getFromRawEncoding, it 147 /// should not be inspected directly. 148 UIntTy getRawEncoding() const { return ID; } 149 150 /// Turn a raw encoding of a SourceLocation object into 151 /// a real SourceLocation. 152 /// 153 /// \see getRawEncoding. 154 static SourceLocation getFromRawEncoding(UIntTy Encoding) { 155 SourceLocation X; 156 X.ID = Encoding; 157 return X; 158 } 159 160 /// When a SourceLocation itself cannot be used, this returns 161 /// an (opaque) pointer encoding for it. 162 /// 163 /// This should only be passed to SourceLocation::getFromPtrEncoding, it 164 /// should not be inspected directly. 165 void* getPtrEncoding() const { 166 // Double cast to avoid a warning "cast to pointer from integer of different 167 // size". 168 return (void*)(uintptr_t)getRawEncoding(); 169 } 170 171 /// Turn a pointer encoding of a SourceLocation object back 172 /// into a real SourceLocation. 173 static SourceLocation getFromPtrEncoding(const void *Encoding) { 174 return getFromRawEncoding((SourceLocation::UIntTy)(uintptr_t)Encoding); 175 } 176 177 static bool isPairOfFileLocations(SourceLocation Start, SourceLocation End) { 178 return Start.isValid() && Start.isFileID() && End.isValid() && 179 End.isFileID(); 180 } 181 182 unsigned getHashValue() const; 183 void print(raw_ostream &OS, const SourceManager &SM) const; 184 std::string printToString(const SourceManager &SM) const; 185 void dump(const SourceManager &SM) const; 186 }; 187 188 inline bool operator==(const SourceLocation &LHS, const SourceLocation &RHS) { 189 return LHS.getRawEncoding() == RHS.getRawEncoding(); 190 } 191 192 inline bool operator!=(const SourceLocation &LHS, const SourceLocation &RHS) { 193 return !(LHS == RHS); 194 } 195 196 // Ordering is meaningful only if LHS and RHS have the same FileID! 197 // Otherwise use SourceManager::isBeforeInTranslationUnit(). 198 inline bool operator<(const SourceLocation &LHS, const SourceLocation &RHS) { 199 return LHS.getRawEncoding() < RHS.getRawEncoding(); 200 } 201 inline bool operator>(const SourceLocation &LHS, const SourceLocation &RHS) { 202 return LHS.getRawEncoding() > RHS.getRawEncoding(); 203 } 204 inline bool operator<=(const SourceLocation &LHS, const SourceLocation &RHS) { 205 return LHS.getRawEncoding() <= RHS.getRawEncoding(); 206 } 207 inline bool operator>=(const SourceLocation &LHS, const SourceLocation &RHS) { 208 return LHS.getRawEncoding() >= RHS.getRawEncoding(); 209 } 210 211 /// A trivial tuple used to represent a source range. 212 class SourceRange { 213 SourceLocation B; 214 SourceLocation E; 215 216 public: 217 SourceRange() = default; 218 SourceRange(SourceLocation loc) : B(loc), E(loc) {} 219 SourceRange(SourceLocation begin, SourceLocation end) : B(begin), E(end) {} 220 221 SourceLocation getBegin() const { return B; } 222 SourceLocation getEnd() const { return E; } 223 224 void setBegin(SourceLocation b) { B = b; } 225 void setEnd(SourceLocation e) { E = e; } 226 227 bool isValid() const { return B.isValid() && E.isValid(); } 228 bool isInvalid() const { return !isValid(); } 229 230 bool operator==(const SourceRange &X) const { 231 return B == X.B && E == X.E; 232 } 233 234 bool operator!=(const SourceRange &X) const { 235 return B != X.B || E != X.E; 236 } 237 238 // Returns true iff other is wholly contained within this range. 239 bool fullyContains(const SourceRange &other) const { 240 return B <= other.B && E >= other.E; 241 } 242 243 void print(raw_ostream &OS, const SourceManager &SM) const; 244 std::string printToString(const SourceManager &SM) const; 245 void dump(const SourceManager &SM) const; 246 }; 247 248 /// Represents a character-granular source range. 249 /// 250 /// The underlying SourceRange can either specify the starting/ending character 251 /// of the range, or it can specify the start of the range and the start of the 252 /// last token of the range (a "token range"). In the token range case, the 253 /// size of the last token must be measured to determine the actual end of the 254 /// range. 255 class CharSourceRange { 256 SourceRange Range; 257 bool IsTokenRange = false; 258 259 public: 260 CharSourceRange() = default; 261 CharSourceRange(SourceRange R, bool ITR) : Range(R), IsTokenRange(ITR) {} 262 263 static CharSourceRange getTokenRange(SourceRange R) { 264 return CharSourceRange(R, true); 265 } 266 267 static CharSourceRange getCharRange(SourceRange R) { 268 return CharSourceRange(R, false); 269 } 270 271 static CharSourceRange getTokenRange(SourceLocation B, SourceLocation E) { 272 return getTokenRange(SourceRange(B, E)); 273 } 274 275 static CharSourceRange getCharRange(SourceLocation B, SourceLocation E) { 276 return getCharRange(SourceRange(B, E)); 277 } 278 279 /// Return true if the end of this range specifies the start of 280 /// the last token. Return false if the end of this range specifies the last 281 /// character in the range. 282 bool isTokenRange() const { return IsTokenRange; } 283 bool isCharRange() const { return !IsTokenRange; } 284 285 SourceLocation getBegin() const { return Range.getBegin(); } 286 SourceLocation getEnd() const { return Range.getEnd(); } 287 SourceRange getAsRange() const { return Range; } 288 289 void setBegin(SourceLocation b) { Range.setBegin(b); } 290 void setEnd(SourceLocation e) { Range.setEnd(e); } 291 void setTokenRange(bool TR) { IsTokenRange = TR; } 292 293 bool isValid() const { return Range.isValid(); } 294 bool isInvalid() const { return !isValid(); } 295 }; 296 297 /// Represents an unpacked "presumed" location which can be presented 298 /// to the user. 299 /// 300 /// A 'presumed' location can be modified by \#line and GNU line marker 301 /// directives and is always the expansion point of a normal location. 302 /// 303 /// You can get a PresumedLoc from a SourceLocation with SourceManager. 304 class PresumedLoc { 305 const char *Filename = nullptr; 306 FileID ID; 307 unsigned Line, Col; 308 SourceLocation IncludeLoc; 309 310 public: 311 PresumedLoc() = default; 312 PresumedLoc(const char *FN, FileID FID, unsigned Ln, unsigned Co, 313 SourceLocation IL) 314 : Filename(FN), ID(FID), Line(Ln), Col(Co), IncludeLoc(IL) {} 315 316 /// Return true if this object is invalid or uninitialized. 317 /// 318 /// This occurs when created with invalid source locations or when walking 319 /// off the top of a \#include stack. 320 bool isInvalid() const { return Filename == nullptr; } 321 bool isValid() const { return Filename != nullptr; } 322 323 /// Return the presumed filename of this location. 324 /// 325 /// This can be affected by \#line etc. 326 const char *getFilename() const { 327 assert(isValid()); 328 return Filename; 329 } 330 331 FileID getFileID() const { 332 assert(isValid()); 333 return ID; 334 } 335 336 /// Return the presumed line number of this location. 337 /// 338 /// This can be affected by \#line etc. 339 unsigned getLine() const { 340 assert(isValid()); 341 return Line; 342 } 343 344 /// Return the presumed column number of this location. 345 /// 346 /// This cannot be affected by \#line, but is packaged here for convenience. 347 unsigned getColumn() const { 348 assert(isValid()); 349 return Col; 350 } 351 352 /// Return the presumed include location of this location. 353 /// 354 /// This can be affected by GNU linemarker directives. 355 SourceLocation getIncludeLoc() const { 356 assert(isValid()); 357 return IncludeLoc; 358 } 359 }; 360 361 class FileEntry; 362 363 /// A SourceLocation and its associated SourceManager. 364 /// 365 /// This is useful for argument passing to functions that expect both objects. 366 class FullSourceLoc : public SourceLocation { 367 const SourceManager *SrcMgr = nullptr; 368 369 public: 370 /// Creates a FullSourceLoc where isValid() returns \c false. 371 FullSourceLoc() = default; 372 373 explicit FullSourceLoc(SourceLocation Loc, const SourceManager &SM) 374 : SourceLocation(Loc), SrcMgr(&SM) {} 375 376 bool hasManager() const { 377 bool hasSrcMgr = SrcMgr != nullptr; 378 assert(hasSrcMgr == isValid() && "FullSourceLoc has location but no manager"); 379 return hasSrcMgr; 380 } 381 382 /// \pre This FullSourceLoc has an associated SourceManager. 383 const SourceManager &getManager() const { 384 assert(SrcMgr && "SourceManager is NULL."); 385 return *SrcMgr; 386 } 387 388 FileID getFileID() const; 389 390 FullSourceLoc getExpansionLoc() const; 391 FullSourceLoc getSpellingLoc() const; 392 FullSourceLoc getFileLoc() const; 393 PresumedLoc getPresumedLoc(bool UseLineDirectives = true) const; 394 bool isMacroArgExpansion(FullSourceLoc *StartLoc = nullptr) const; 395 FullSourceLoc getImmediateMacroCallerLoc() const; 396 std::pair<FullSourceLoc, StringRef> getModuleImportLoc() const; 397 unsigned getFileOffset() const; 398 399 unsigned getExpansionLineNumber(bool *Invalid = nullptr) const; 400 unsigned getExpansionColumnNumber(bool *Invalid = nullptr) const; 401 402 unsigned getSpellingLineNumber(bool *Invalid = nullptr) const; 403 unsigned getSpellingColumnNumber(bool *Invalid = nullptr) const; 404 405 const char *getCharacterData(bool *Invalid = nullptr) const; 406 407 unsigned getLineNumber(bool *Invalid = nullptr) const; 408 unsigned getColumnNumber(bool *Invalid = nullptr) const; 409 410 const FileEntry *getFileEntry() const; 411 412 /// Return a StringRef to the source buffer data for the 413 /// specified FileID. 414 StringRef getBufferData(bool *Invalid = nullptr) const; 415 416 /// Decompose the specified location into a raw FileID + Offset pair. 417 /// 418 /// The first element is the FileID, the second is the offset from the 419 /// start of the buffer of the location. 420 std::pair<FileID, unsigned> getDecomposedLoc() const; 421 422 bool isInSystemHeader() const; 423 424 /// Determines the order of 2 source locations in the translation unit. 425 /// 426 /// \returns true if this source location comes before 'Loc', false otherwise. 427 bool isBeforeInTranslationUnitThan(SourceLocation Loc) const; 428 429 /// Determines the order of 2 source locations in the translation unit. 430 /// 431 /// \returns true if this source location comes before 'Loc', false otherwise. 432 bool isBeforeInTranslationUnitThan(FullSourceLoc Loc) const { 433 assert(Loc.isValid()); 434 assert(SrcMgr == Loc.SrcMgr && "Loc comes from another SourceManager!"); 435 return isBeforeInTranslationUnitThan((SourceLocation)Loc); 436 } 437 438 /// Comparison function class, useful for sorting FullSourceLocs. 439 struct BeforeThanCompare { 440 bool operator()(const FullSourceLoc& lhs, const FullSourceLoc& rhs) const { 441 return lhs.isBeforeInTranslationUnitThan(rhs); 442 } 443 }; 444 445 /// Prints information about this FullSourceLoc to stderr. 446 /// 447 /// This is useful for debugging. 448 void dump() const; 449 450 friend bool 451 operator==(const FullSourceLoc &LHS, const FullSourceLoc &RHS) { 452 return LHS.getRawEncoding() == RHS.getRawEncoding() && 453 LHS.SrcMgr == RHS.SrcMgr; 454 } 455 456 friend bool 457 operator!=(const FullSourceLoc &LHS, const FullSourceLoc &RHS) { 458 return !(LHS == RHS); 459 } 460 }; 461 462 } // namespace clang 463 464 namespace llvm { 465 466 /// Define DenseMapInfo so that FileID's can be used as keys in DenseMap and 467 /// DenseSets. 468 template <> 469 struct DenseMapInfo<clang::FileID> { 470 static clang::FileID getEmptyKey() { 471 return {}; 472 } 473 474 static clang::FileID getTombstoneKey() { 475 return clang::FileID::getSentinel(); 476 } 477 478 static unsigned getHashValue(clang::FileID S) { 479 return S.getHashValue(); 480 } 481 482 static bool isEqual(clang::FileID LHS, clang::FileID RHS) { 483 return LHS == RHS; 484 } 485 }; 486 487 /// Define DenseMapInfo so that SourceLocation's can be used as keys in 488 /// DenseMap and DenseSet. This trait class is eqivalent to 489 /// DenseMapInfo<unsigned> which uses SourceLocation::ID is used as a key. 490 template <> struct DenseMapInfo<clang::SourceLocation> { 491 static clang::SourceLocation getEmptyKey() { 492 constexpr clang::SourceLocation::UIntTy Zero = 0; 493 return clang::SourceLocation::getFromRawEncoding(~Zero); 494 } 495 496 static clang::SourceLocation getTombstoneKey() { 497 constexpr clang::SourceLocation::UIntTy Zero = 0; 498 return clang::SourceLocation::getFromRawEncoding(~Zero - 1); 499 } 500 501 static unsigned getHashValue(clang::SourceLocation Loc) { 502 return Loc.getHashValue(); 503 } 504 505 static bool isEqual(clang::SourceLocation LHS, clang::SourceLocation RHS) { 506 return LHS == RHS; 507 } 508 }; 509 510 // Allow calling FoldingSetNodeID::Add with SourceLocation object as parameter 511 template <> struct FoldingSetTrait<clang::SourceLocation> { 512 static void Profile(const clang::SourceLocation &X, FoldingSetNodeID &ID); 513 }; 514 515 } // namespace llvm 516 517 #endif // LLVM_CLANG_BASIC_SOURCELOCATION_H 518