[rename] Introduce symbol occurrences

[arphaman]

Summary

Symbol occurrences store the results of local rename and will also be used for the global, indexed rename results. They can be converted to a set of AtomicChanges as well. This is a preparation patch for both the support of multi-piece local-renames (ObjC selectors) and the migration of clang-rename over to clang-refactor.
This is a non functional change, and I just wanted to make sure the general direction of this patch is accepted before committing.

[kimgr]

High-level comment from the peanut gallery:

The word "occurrences" is horrible to type and most people misspell it (you did great here!) Would you consider something like "SymbolMatches" or even "SymbolHits"?

[arphaman]

In D36156#827733, @kimgr wrote:

High-level comment from the peanut gallery:

The word "occurrences" is horrible to type and most people misspell it (you did great here!) Would you consider something like "SymbolMatches" or even "SymbolHits"?

Sure, it would be reasonable to change it something easier, as long as it's still descriptive. "SymbolMatches" could work, although I think I'd prefer something a bit more descriptive. What about "SymbolReference"/"References"?

[kimgr]

I was about to suggest SymbolLocation or even SymbolLoc, but it appears to keep track of more than locations. "Reference" sounds a little open-ended. No more ideas here, I'm afraid.

[klimek]

include/clang/Tooling/Refactoring/Rename/SymbolOccurrences.h

32 ↗

(On Diff #109133)

I understand the exact vs. non-exact idea, but can you expand a bit on how Obj-C code looks where a rename needs to touch more than one location? (I have no idea about Obj-C unfortunately)

50 ↗

(On Diff #109133)

Nit: s/fixup/fix/?

65–68 ↗

(On Diff #109133)

Any reason not to return ranges instead here?

72–73 ↗

(On Diff #109133)

Can we store ranges instead?

78 ↗

(On Diff #109133)

Why can't we put all data in SymbolOccurrence and just use a normal container here?

[arphaman]

include/clang/Tooling/Refactoring/Rename/SymbolOccurrences.h

65–68 ↗

(On Diff #109133)

I used ranges before, but I found that it was easier to create the atomic changes with location+lengths. Should I go back to ranges?

72–73 ↗

(On Diff #109133)

We could, but see above for my current reasoning.

[arphaman]

include/clang/Tooling/Refactoring/Rename/SymbolOccurrences.h

65–68 ↗

(On Diff #109133)

Oops, this is embarrassing! I didn't realize that AtomicChange had an additional overload that accepted CharSourceRange. I'll go back to ranges.

[arphaman]

Address review comments.

[arphaman]

Ping.

[hokein]

Sorry for the delay. The code looks good roughly, a few nits below.

include/clang/Tooling/Refactoring/Rename/SymbolName.h

19 ↗

(On Diff #109326)

An off-topic thought: currently we put everything into clang::tooling, I think we might need a separate namespace e.g. clang::tooling::refactoring in the future?

21 ↗

(On Diff #109326)

I think this can be removed?

lib/Tooling/Refactoring/Rename/RenamingAction.cpp

60 ↗

(On Diff #109326)

Maybe add a comment for this utility function.

The name is a bit confusing, IIUC, the function actually fills the FileToReplaces, not apply the changes? maybe a better name for it?

61 ↗

(On Diff #109326)

nit: For out parameter, I'd use pointer.

62 ↗

(On Diff #109326)

nit: const auto &

lib/Tooling/Refactoring/Rename/SymbolOccurrences.cpp

17 ↗

(On Diff #109326)

Shouldn't the definition be in clang::tooling namespace?

lib/Tooling/Refactoring/Rename/USRLocFinder.cpp

398 ↗

(On Diff #109326)

I think just returning Visitor.getOccurrences() is sufficient -- compiler can handle it well, also using std::move would prevent copy elision.

[arphaman]

include/clang/Tooling/Refactoring/Rename/SymbolName.h

19 ↗

(On Diff #109326)

That would be nice, I agree. Don't think it's in scope for this patch though, maybe for https://reviews.llvm.org/D36075?

lib/Tooling/Refactoring/Rename/SymbolOccurrences.cpp

17 ↗

(On Diff #109326)

That's not necessary because of the using namespace directives above. Only standalone functions have to be defined in namespaces, out-of-line member function definitions don't have to follow that rule because they already have the class qualifier.

lib/Tooling/Refactoring/Rename/USRLocFinder.cpp

398 ↗

(On Diff #109326)

I'm returning by non-const reference from getOccurrences, so the compiler copies by default. I have to move either here or return by value from getOccurrences and move there. We also have warnings for redundant std::move, and they don't fire here.

[arphaman]

Address review comments.

[hokein]

lib/Tooling/Refactoring/Rename/SymbolOccurrences.cpp

17 ↗

(On Diff #109326)

Ah, I see, thanks for the explanation. The constructor actually lives in "SymbolOccurrence". T

I'd like to use a more familiar way: namespace clang { namespace tooling { ... } }

lib/Tooling/Refactoring/Rename/USRLocFinder.cpp

398 ↗

(On Diff #109326)

Ok, didn't notice that getOccurance() returns non-const reference.

I think the method getOccurances may have potential effect -- the clients could change the Occurences member variable of USRLocFindingASTVisitor, after getting the non-const reference.

Another option is to rename getOccurances to takeOccurrences and return by value:

SymbolOccurrences takeOccurrences() { return std::move(Occurrences); }

What do you think?

[arphaman]

lib/Tooling/Refactoring/Rename/USRLocFinder.cpp

398 ↗

(On Diff #109326)

Yeah, takeOccurrences would be better I think. I'll update.

[arphaman]

Use takeOccurrences

[hokein]

LGTM.

include/clang/Tooling/Refactoring/Rename/SymbolName.h

19 ↗

(On Diff #109326)

Sounds good. No need to do it in this patch.

cfe/trunk/include/clang/Tooling/Refactoring/Rename/RenamingAction.h

 /// \brief Provides an action to rename every symbol at a point.
 ///
 //===----------------------------------------------------------------------===//
 
 #ifndef LLVM_CLANG_TOOLING_REFACTOR_RENAME_RENAMING_ACTION_H
 #define LLVM_CLANG_TOOLING_REFACTOR_RENAME_RENAMING_ACTION_H
 
 #include "clang/Tooling/Refactoring.h"
+#include "clang/Tooling/Refactoring/AtomicChange.h"
+#include "clang/Tooling/Refactoring/Rename/SymbolOccurrences.h"
+#include "llvm/Support/Error.h"
 
 namespace clang {
 class ASTConsumer;
 class CompilerInstance;
 
 namespace tooling {
 
 class RenamingAction {

 
 private:
   const std::vector<std::string> &NewNames, &PrevNames;
   const std::vector<std::vector<std::string>> &USRList;
   std::map<std::string, tooling::Replacements> &FileToReplaces;
   bool PrintLocations;
 };
 
+/// Returns source replacements that correspond to the rename of the given
+/// symbol occurrences.
+llvm::Expected<std::vector<AtomicChange>>
+createRenameReplacements(const SymbolOccurrences &Occurrences,
+                         const SourceManager &SM,
+                         ArrayRef<StringRef> NewNameStrings);
+
 /// Rename all symbols identified by the given USRs.
 class QualifiedRenamingAction {
 public:
   QualifiedRenamingAction(
       const std::vector<std::string> &NewNames,
       const std::vector<std::vector<std::string>> &USRList,
       std::map<std::string, tooling::Replacements> &FileToReplaces)
       : NewNames(NewNames), USRList(USRList), FileToReplaces(FileToReplaces) {}

cfe/trunk/include/clang/Tooling/Refactoring/Rename/SymbolName.h

+//===--- SymbolName.h - Clang refactoring library -------------------------===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef LLVM_CLANG_TOOLING_REFACTOR_RENAME_SYMBOL_NAME_H
+#define LLVM_CLANG_TOOLING_REFACTOR_RENAME_SYMBOL_NAME_H
+
+#include "clang/Basic/LLVM.h"
+#include "llvm/ADT/ArrayRef.h"
+#include "llvm/ADT/SmallVector.h"
+#include "llvm/ADT/StringRef.h"
+
+namespace clang {
+namespace tooling {
+
+/// A name of a symbol.
+///
+/// Symbol's name can be composed of multiple strings. For example, Objective-C
+/// methods can contain multiple argument lables:
+///
+/// \code
+/// - (void) myMethodNamePiece: (int)x anotherNamePieces:(int)y;
+/// //       ^~ string 0 ~~~~~         ^~ string 1 ~~~~~
+/// \endcode
+class SymbolName {
+public:
+  SymbolName(StringRef Name) {
+    // While empty symbol names are valid (Objective-C selectors can have empty
+    // name pieces), occurrences Objective-C selectors are created using an
+    // array of strings instead of just one string.
+    assert(!Name.empty() && "Invalid symbol name!");
+    this->Name.push_back(Name.str());
+  }
+
+  ArrayRef<std::string> getNamePieces() const { return Name; }
+
+private:
+  llvm::SmallVector<std::string, 1> Name;
+};
+
+} // end namespace tooling
+} // end namespace clang
+
+#endif // LLVM_CLANG_TOOLING_REFACTOR_RENAME_SYMBOL_NAME_H

cfe/trunk/include/clang/Tooling/Refactoring/Rename/SymbolOccurrences.h

+//===--- SymbolOccurrences.h - Clang refactoring library ------------------===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef LLVM_CLANG_TOOLING_REFACTOR_RENAME_SYMBOL_OCCURRENCES_H
+#define LLVM_CLANG_TOOLING_REFACTOR_RENAME_SYMBOL_OCCURRENCES_H
+
+#include "clang/Basic/LLVM.h"
+#include "clang/Basic/SourceLocation.h"
+#include "llvm/ADT/ArrayRef.h"
+#include "llvm/ADT/StringRef.h"
+#include <vector>
+
+namespace clang {
+namespace tooling {
+
+class SymbolName;
+
+/// An occurrence of a symbol in the source.
+///
+/// Occurrences can have difference kinds, that describe whether this occurrence
+/// is an exact semantic match, or whether this is a weaker textual match that's
+/// not guaranteed to represent the exact declaration.
+///
+/// A single occurrence of a symbol can span more than one source range. For
+/// example, Objective-C selectors can contain multiple argument labels:
+///
+/// \code
+/// [object selectorPiece1: ... selectorPiece2: ...];
+/// //      ^~~ range 0 ~~      ^~~ range 1 ~~
+/// \endcode
+///
+/// We have to replace the text in both range 0 and range 1 when renaming the
+/// Objective-C method 'selectorPiece1:selectorPiece2'.
+class SymbolOccurrence {
+public:
+  enum OccurrenceKind {
+    /// This occurrence is an exact match and can be renamed automatically.
+    ///
+    /// Note:
+    /// Symbol occurrences in macro arguments that expand to different
+    /// declarations get marked as exact matches, and thus the renaming engine
+    /// will rename them e.g.:
+    ///
+    /// \code
+    ///   #define MACRO(x) x + ns::x
+    ///   int foo(int var) {
+    ///     return MACRO(var); // var is renamed automatically here when
+    ///                        // either var or ns::var is renamed.
+    ///   };
+    /// \endcode
+    ///
+    /// The user will have to fix their code manually after performing such a
+    /// rename.
+    /// FIXME: The rename verifier should notify user about this issue.
+    MatchingSymbol
+  };
+
+  SymbolOccurrence(const SymbolName &Name, OccurrenceKind Kind,
+                   ArrayRef<SourceLocation> Locations);
+
+  SymbolOccurrence(SymbolOccurrence &&) = default;
+  SymbolOccurrence &operator=(SymbolOccurrence &&) = default;
+
+  OccurrenceKind getKind() const { return Kind; }
+
+  ArrayRef<SourceRange> getNameRanges() const {
+    if (MultipleRanges) {
+      return llvm::makeArrayRef(MultipleRanges.get(),
+                                RangeOrNumRanges.getBegin().getRawEncoding());
+    }
+    return RangeOrNumRanges;
+  }
+
+private:
+  OccurrenceKind Kind;
+  std::unique_ptr<SourceRange[]> MultipleRanges;
+  SourceRange RangeOrNumRanges;
+};
+
+using SymbolOccurrences = std::vector<SymbolOccurrence>;
+
+} // end namespace tooling
+} // end namespace clang
+
+#endif // LLVM_CLANG_TOOLING_REFACTOR_RENAME_SYMBOL_OCCURRENCES_H

cfe/trunk/include/clang/Tooling/Refactoring/Rename/USRLocFinder.h

 //===----------------------------------------------------------------------===//
 
 #ifndef LLVM_CLANG_TOOLING_REFACTOR_RENAME_USR_LOC_FINDER_H
 #define LLVM_CLANG_TOOLING_REFACTOR_RENAME_USR_LOC_FINDER_H
 
 #include "clang/AST/AST.h"
 #include "clang/Tooling/Core/Replacement.h"
 #include "clang/Tooling/Refactoring/AtomicChange.h"
+#include "clang/Tooling/Refactoring/Rename/SymbolOccurrences.h"
 #include "llvm/ADT/StringRef.h"
 #include <string>
 #include <vector>
 
 namespace clang {
 namespace tooling {
 
 /// Create atomic changes for renaming all symbol references which are
 /// identified by the USRs set to a given new name.
 ///
 /// \param USRs The set containing USRs of a particular old symbol.
 /// \param NewName The new name to replace old symbol name.
 /// \param TranslationUnitDecl The translation unit declaration.
 ///
 /// \return Atomic changes for renaming.
 std::vector<tooling::AtomicChange>
 createRenameAtomicChanges(llvm::ArrayRef<std::string> USRs,
                           llvm::StringRef NewName, Decl *TranslationUnitDecl);
 
-// FIXME: make this an AST matcher. Wouldn't that be awesome??? I agree!
-std::vector<SourceLocation>
-getLocationsOfUSRs(const std::vector<std::string> &USRs,
-                   llvm::StringRef PrevName, Decl *Decl);
+/// Finds the symbol occurrences for the symbol that's identified by the given
+/// USR set.
+///
+/// \return SymbolOccurrences that can be converted to AtomicChanges when
+/// renaming.
+SymbolOccurrences getOccurrencesOfUSRs(ArrayRef<std::string> USRs,
+                                       StringRef PrevName, Decl *Decl);
 
 } // end namespace tooling
 } // end namespace clang
 
 #endif // LLVM_CLANG_TOOLING_REFACTOR_RENAME_USR_LOC_FINDER_H

cfe/trunk/lib/Tooling/Refactoring/CMakeLists.txt

 set(LLVM_LINK_COMPONENTS Support)
 
 add_clang_library(clangToolingRefactor
   AtomicChange.cpp
   Rename/RenamingAction.cpp
+  Rename/SymbolOccurrences.cpp
   Rename/USRFinder.cpp
   Rename/USRFindingAction.cpp
   Rename/USRLocFinder.cpp
 
   LINK_LIBS
   clangAST
   clangASTMatchers
   clangBasic
   clangFormat
   clangIndex
   clangLex
   clangToolingCore
   )

cfe/trunk/lib/Tooling/Refactoring/Rename/RenamingAction.cpp

 #include "clang/Frontend/CompilerInstance.h"
 #include "clang/Frontend/FrontendAction.h"
 #include "clang/Lex/Lexer.h"
 #include "clang/Lex/Preprocessor.h"
 #include "clang/Tooling/CommonOptionsParser.h"
 #include "clang/Tooling/Refactoring.h"
 #include "clang/Tooling/Refactoring/Rename/USRLocFinder.h"
 #include "clang/Tooling/Tooling.h"
+#include "llvm/ADT/STLExtras.h"
 #include <string>
 #include <vector>
 
 using namespace llvm;
 
 namespace clang {
 namespace tooling {
 
+Expected<std::vector<AtomicChange>>
+createRenameReplacements(const SymbolOccurrences &Occurrences,
+                         const SourceManager &SM,
+                         ArrayRef<StringRef> NewNameStrings) {
+  // FIXME: A true local rename can use just one AtomicChange.
+  std::vector<AtomicChange> Changes;
+  for (const auto &Occurrence : Occurrences) {
+    ArrayRef<SourceRange> Ranges = Occurrence.getNameRanges();
+    assert(NewNameStrings.size() == Ranges.size() &&
+           "Mismatching number of ranges and name pieces");
+    AtomicChange Change(SM, Ranges[0].getBegin());
+    for (const auto &Range : llvm::enumerate(Ranges)) {
+      auto Error =
+          Change.replace(SM, CharSourceRange::getCharRange(Range.value()),
+                         NewNameStrings[Range.index()]);
+      if (Error)
+        return std::move(Error);
+    }
+    Changes.push_back(std::move(Change));
+  }
+  return Changes;
+}
+
+/// Takes each atomic change and inserts its replacements into the set of
+/// replacements that belong to the appropriate file.
+static void convertChangesToFileReplacements(
+    ArrayRef<AtomicChange> AtomicChanges,
+    std::map<std::string, tooling::Replacements> *FileToReplaces) {
+  for (const auto &AtomicChange : AtomicChanges) {
+    for (const auto &Replace : AtomicChange.getReplacements()) {
+      llvm::Error Err = (*FileToReplaces)[Replace.getFilePath()].add(Replace);
+      if (Err) {
+        llvm::errs() << "Renaming failed in " << Replace.getFilePath() << "! "
+                     << llvm::toString(std::move(Err)) << "\n";
+      }
+    }
+  }
+}
+
 class RenamingASTConsumer : public ASTConsumer {
 public:
   RenamingASTConsumer(
       const std::vector<std::string> &NewNames,
       const std::vector<std::string> &PrevNames,
       const std::vector<std::vector<std::string>> &USRList,
       std::map<std::string, tooling::Replacements> &FileToReplaces,
       bool PrintLocations)
       : NewNames(NewNames), PrevNames(PrevNames), USRList(USRList),
         FileToReplaces(FileToReplaces), PrintLocations(PrintLocations) {}
 
   void HandleTranslationUnit(ASTContext &Context) override {
     for (unsigned I = 0; I < NewNames.size(); ++I)
       HandleOneRename(Context, NewNames[I], PrevNames[I], USRList[I]);
   }
 
   void HandleOneRename(ASTContext &Context, const std::string &NewName,
                        const std::string &PrevName,
                        const std::vector<std::string> &USRs) {
     const SourceManager &SourceMgr = Context.getSourceManager();
-    std::vector<SourceLocation> RenamingCandidates;
-    std::vector<SourceLocation> NewCandidates;
 
-    NewCandidates = tooling::getLocationsOfUSRs(
+    SymbolOccurrences Occurrences = tooling::getOccurrencesOfUSRs(
         USRs, PrevName, Context.getTranslationUnitDecl());
-    RenamingCandidates.insert(RenamingCandidates.end(), NewCandidates.begin(),
-                              NewCandidates.end());
-
-    unsigned PrevNameLen = PrevName.length();
-    for (const auto &Loc : RenamingCandidates) {
-      if (PrintLocations) {
-        FullSourceLoc FullLoc(Loc, SourceMgr);
-        errs() << "clang-rename: renamed at: " << SourceMgr.getFilename(Loc)
+      for (const auto &Occurrence : Occurrences) {
+        FullSourceLoc FullLoc(Occurrence.getNameRanges()[0].getBegin(),
+                              SourceMgr);
+        errs() << "clang-rename: renamed at: " << SourceMgr.getFilename(FullLoc)
                << ":" << FullLoc.getSpellingLineNumber() << ":"
                << FullLoc.getSpellingColumnNumber() << "\n";
       }
-      // FIXME: better error handling.
-      tooling::Replacement Replace(SourceMgr, Loc, PrevNameLen, NewName);
-      llvm::Error Err = FileToReplaces[Replace.getFilePath()].add(Replace);
-      if (Err)
-        llvm::errs() << "Renaming failed in " << Replace.getFilePath() << "! "
-                     << llvm::toString(std::move(Err)) << "\n";
     }
+    // FIXME: Support multi-piece names.
+    // FIXME: better error handling (propagate error out).
+    StringRef NewNameRef = NewName;
+    Expected<std::vector<AtomicChange>> Change =
+        createRenameReplacements(Occurrences, SourceMgr, NewNameRef);
+    if (!Change) {
+      llvm::errs() << "Failed to create renaming replacements for '" << PrevName
+                   << "'! " << llvm::toString(Change.takeError()) << "\n";
+      return;
+    }
+    convertChangesToFileReplacements(*Change, &FileToReplaces);
   }
 
 private:
   const std::vector<std::string> &NewNames, &PrevNames;
   const std::vector<std::vector<std::string>> &USRList;
   std::map<std::string, tooling::Replacements> &FileToReplaces;
   bool PrintLocations;
 };
public:
   }
 
   void HandleTranslationUnit(ASTContext &Context) override {
     for (unsigned I = 0; I < NewNames.size(); ++I) {
       // FIXME: Apply AtomicChanges directly once the refactoring APIs are
       // ready.
       auto AtomicChanges = tooling::createRenameAtomicChanges(
           USRList[I], NewNames[I], Context.getTranslationUnitDecl());
-      for (const auto AtomicChange : AtomicChanges) {
-        for (const auto &Replace : AtomicChange.getReplacements()) {
-          llvm::Error Err = FileToReplaces[Replace.getFilePath()].add(Replace);
-          if (Err) {
-            llvm::errs() << "Renaming failed in " << Replace.getFilePath()
-                         << "! " << llvm::toString(std::move(Err)) << "\n";
-          }
-        }
-      }
+      convertChangesToFileReplacements(AtomicChanges, &FileToReplaces);
     }
   }
 
 private:
   const std::vector<std::string> &NewNames;
   const std::vector<std::vector<std::string>> &USRList;
   std::map<std::string, tooling::Replacements> &FileToReplaces;
 };

cfe/trunk/lib/Tooling/Refactoring/Rename/SymbolOccurrences.cpp

+//===--- SymbolOccurrences.cpp - Clang refactoring library ----------------===//
+//
+//                     The LLVM Compiler Infrastructure
+//
+// This file is distributed under the University of Illinois Open Source
+// License. See LICENSE.TXT for details.
+//
+//===----------------------------------------------------------------------===//
+
+#include "clang/Tooling/Refactoring/Rename/SymbolOccurrences.h"
+#include "clang/Tooling/Refactoring/Rename/SymbolName.h"
+#include "llvm/ADT/STLExtras.h"
+
+using namespace clang;
+using namespace tooling;
+
+SymbolOccurrence::SymbolOccurrence(const SymbolName &Name, OccurrenceKind Kind,
+                                   ArrayRef<SourceLocation> Locations)
+    : Kind(Kind) {
+  ArrayRef<std::string> NamePieces = Name.getNamePieces();
+  assert(Locations.size() == NamePieces.size() &&
+         "mismatching number of locations and lengths");
+  assert(!Locations.empty() && "no locations");
+  if (Locations.size() == 1) {
+    RangeOrNumRanges = SourceRange(
+        Locations[0], Locations[0].getLocWithOffset(NamePieces[0].size()));
+    return;
+  }
+  MultipleRanges = llvm::make_unique<SourceRange[]>(Locations.size());
+  RangeOrNumRanges.setBegin(
+      SourceLocation::getFromRawEncoding(Locations.size()));
+  for (const auto &Loc : llvm::enumerate(Locations)) {
+    MultipleRanges[Loc.index()] = SourceRange(
+        Loc.value(),
+        Loc.value().getLocWithOffset(NamePieces[Loc.index()].size()));
+  }
+}

cfe/trunk/lib/Tooling/Refactoring/Rename/USRLocFinder.cpp

 #include "clang/AST/ASTContext.h"
 #include "clang/AST/RecursiveASTVisitor.h"
 #include "clang/Basic/LLVM.h"
 #include "clang/Basic/SourceLocation.h"
 #include "clang/Basic/SourceManager.h"
 #include "clang/Lex/Lexer.h"
 #include "clang/Tooling/Core/Lookup.h"
 #include "clang/Tooling/Refactoring/RecursiveSymbolVisitor.h"
+#include "clang/Tooling/Refactoring/Rename/SymbolName.h"
 #include "clang/Tooling/Refactoring/Rename/USRFinder.h"
 #include "llvm/ADT/StringRef.h"
 #include "llvm/Support/Casting.h"
 #include <cstddef>
 #include <set>
 #include <string>
 #include <vector>
 
if (USRSet.find(getUSRForDecl(ND)) != USRSet.end()) {
         Loc = SM.getSpellingLoc(Loc);
       checkAndAddLocation(Loc);
     }
     return true;
   }
 
   // Non-visitors:
 
-  // \brief Returns a list of unique locations. Duplicate or overlapping
-  // locations are erroneous and should be reported!
-  const std::vector<clang::SourceLocation> &getLocationsFound() const {
-    return LocationsFound;
-  }
+  /// \brief Returns a set of unique symbol occurrences. Duplicate or
+  /// overlapping occurrences are erroneous and should be reported!
+  SymbolOccurrences takeOccurrences() { return std::move(Occurrences); }
 
 private:
   void checkAndAddLocation(SourceLocation Loc) {
     const SourceLocation BeginLoc = Loc;
     const SourceLocation EndLoc = Lexer::getLocForEndOfToken(
         BeginLoc, 0, Context.getSourceManager(), Context.getLangOpts());
     StringRef TokenName =
         Lexer::getSourceText(CharSourceRange::getTokenRange(BeginLoc, EndLoc),
                              Context.getSourceManager(), Context.getLangOpts());
-    size_t Offset = TokenName.find(PrevName);
+    size_t Offset = TokenName.find(PrevName.getNamePieces()[0]);
 
     // The token of the source location we find actually has the old
     // name.
     if (Offset != StringRef::npos)
-      LocationsFound.push_back(BeginLoc.getLocWithOffset(Offset));
+      Occurrences.emplace_back(PrevName, SymbolOccurrence::MatchingSymbol,
+                               BeginLoc.getLocWithOffset(Offset));
   }
 
   const std::set<std::string> USRSet;
-  const std::string PrevName;
-  std::vector<clang::SourceLocation> LocationsFound;
+  const SymbolName PrevName;
+  SymbolOccurrences Occurrences;
   const ASTContext &Context;
 };
 
 SourceLocation StartLocationForType(TypeLoc TL) {
   // For elaborated types (e.g. `struct a::A`) we want the portion after the
   // `struct` but including the namespace qualifier, `a::`.
   if (auto ElaboratedTypeLoc = TL.getAs<clang::ElaboratedTypeLoc>()) {
     NestedNameSpecifierLoc NestedNameSpecifier =
private:
   std::vector<RenameInfo> RenameInfos;
   // Record all interested using declarations which contains the using-shadow
   // declarations of the symbol declarations being renamed.
   std::vector<const UsingDecl *> UsingDecls;
 };
 
 } // namespace
 
-std::vector<SourceLocation>
-getLocationsOfUSRs(const std::vector<std::string> &USRs, StringRef PrevName,
-                   Decl *Decl) {
+SymbolOccurrences getOccurrencesOfUSRs(ArrayRef<std::string> USRs,
+                                       StringRef PrevName, Decl *Decl) {
   USRLocFindingASTVisitor Visitor(USRs, PrevName, Decl->getASTContext());
   Visitor.TraverseDecl(Decl);
-  return Visitor.getLocationsFound();
+  return Visitor.takeOccurrences();
 }
 
 std::vector<tooling::AtomicChange>
 createRenameAtomicChanges(llvm::ArrayRef<std::string> USRs,
                           llvm::StringRef NewName, Decl *TranslationUnitDecl) {
   RenameLocFinder Finder(USRs, TranslationUnitDecl->getASTContext());
   Finder.TraverseDecl(TranslationUnitDecl);