[clang][ExtractAPI] Modify declaration fragment methods to add a new fragment at an arbitrary offset.

[Ruturaj4]

Summary

The current implementation doesn't support merging declaration fragments at arbitrary offsets. This patch adds that support
by modifying declaration fragment methods.

[dang]

clang/include/clang/ExtractAPI/DeclarationFragments.h

102

This shouldn't need to be part of the public interface of the DeclarationFragments type and can just be a static function in DeclarationFragments.cpp.

114

Is this parameter intmax_t to allow negative indices? If so I really don't think it's a good idea. I would prefer if we exposed an iterator interface to DeclarationFragments to make the API more like that of a vector type. (The iterator would just need to be the iterator for the underlying vector).

clang/include/clang/ExtractAPI/ExtractAPIVisitor.h

119

I don't think the API naming makes it clear that you can and what it means to insert at a negative offset. I would much rather we had an iterator based interface and didn't necessarily do chained calls. It could look something like this:

auto &DeclFrag = Record.second->Declaration;
DeclFrag.insert(DeclFrag.begin(), "typedef", DeclarationGragments::FragmentKind::Keyword, "", nullptr);
// the rest of the code

[Ruturaj4]

Daniel, I made all the changes as you desired, thanks.

[Ruturaj4]

1. Updating D151048: [clang][ExtractAPI] Modify declaration fragment methods to add a new fragment at an arbitrary offset. #
2. Enter a brief description of the changes included in this update.
3. The first line is used as subject, next lines as comment. #
4. If you intended to create a new revision, use:
5. $ arc diff --create

I made all the suggested changes.

clang/include/clang/ExtractAPI/DeclarationFragments.h

struct Fragment {
     Fragment(StringRef Spelling, FragmentKind Kind, StringRef PreciseIdentifier,
              const Decl *Declaration)
         : Spelling(Spelling), Kind(Kind), PreciseIdentifier(PreciseIdentifier),
           Declaration(Declaration) {}
   };
 
   const std::vector<Fragment> &getFragments() const { return Fragments; }
 
-  // Add a new Fragment to the beginning of the Fragments.
-  DeclarationFragments &appendFront(StringRef Spelling, FragmentKind Kind,
+  size_t calculateOffset(intmax_t Index) const {
+    if (Index >= 0) {
+      size_t offset = static_cast<size_t>(Index);
+      if (offset > Fragments.size()) {
+        offset = Fragments.size();
+      }
+      return offset;
+    }
+    return Fragments.size() + static_cast<size_t>(Index);
+  }
+
+  // Add a new Fragment at an arbitrary offset.
+  DeclarationFragments &insertAtIndex(intmax_t Index, StringRef Spelling,
+                                      FragmentKind Kind,
                                       StringRef PreciseIdentifier = "",
                                       const Decl *Declaration = nullptr) {
-    Fragments.emplace(Fragments.begin(), Spelling, Kind, PreciseIdentifier,
-                      Declaration);
+    Fragments.insert(
+        Fragments.begin() + calculateOffset(Index),
+        std::move(Fragment(Spelling, Kind, PreciseIdentifier, Declaration)));
     return *this;
   }
 
-  DeclarationFragments &appendFront(DeclarationFragments &&Other) {
-    Fragments.insert(Fragments.begin(),
+  DeclarationFragments &insertAtIndex(intmax_t Index,
+                                      DeclarationFragments &&Other) {
+    Fragments.insert(Fragments.begin() + calculateOffset(Index),
                      std::make_move_iterator(Other.Fragments.begin()),
                      std::make_move_iterator(Other.Fragments.end()));
     Other.Fragments.clear();
     return *this;
   }
 
-  void removeLast() { Fragments.pop_back(); }
-
   /// Append a new Fragment to the end of the Fragments.
   ///
   /// \returns a reference to the DeclarationFragments object itself after
   /// appending to chain up consecutive appends.
   DeclarationFragments &append(StringRef Spelling, FragmentKind Kind,
                                StringRef PreciseIdentifier = "",
                                const Decl *Declaration = nullptr) {
     if (Kind == FragmentKind::Text && !Fragments.empty() &&

clang/include/clang/ExtractAPI/ExtractAPIVisitor.h

Derived &getDerivedExtractAPIVisitor() {
     return *static_cast<Derived *>(this);
   }
 };
 
 template <typename T>
 static void modifyRecords(const T &Records, const StringRef &Name) {
   for (const auto &Record : Records) {
     if (Name == Record.second.get()->Name) {
-      Record.second.get()->Declaration.removeLast();
       Record.second.get()
           ->Declaration
-          .appendFront(" ", DeclarationFragments::FragmentKind::Text)
-          .appendFront("typedef", DeclarationFragments::FragmentKind::Keyword,
-                       "", nullptr)
-          .append(" { ... } ", DeclarationFragments::FragmentKind::Text)
-          .append(Name, DeclarationFragments::FragmentKind::Identifier)
-          .append(";", DeclarationFragments::FragmentKind::Text);
+          .insertAtIndex(0, "typedef",
+                         DeclarationFragments::FragmentKind::Keyword, "",
+                         nullptr)
+          .insertAtIndex(1, " ", DeclarationFragments::FragmentKind::Text)
+          .insertAtIndex(-1, " { ... } ",
+                         DeclarationFragments::FragmentKind::Text)
+          .insertAtIndex(-1, Name,
+                         DeclarationFragments::FragmentKind::Identifier);
       break;
     }
   }
 }
 
 template <typename Derived>
 bool ExtractAPIVisitorBase<Derived>::VisitVarDecl(const VarDecl *Decl) {
   // skip function parameters.