Add clang_CXXMethod_isCopyAssignmentOperator to libclang

[diseraluca]

Summary

The new method is a wrapper of CXXMethodDecl::isCopyAssignmentOperator and
can be used to recognized copy-assignment operators in libclang.

An export for the method, together with its documentation, was added to
"clang/include/clang-c/Index.h" with an implementation provided in
"clang/tools/libclang/CIndex.cpp". The implementation was based on
similar clang_CXXMethod.* implementations, following the same
structure but calling CXXMethodDecl::isCopyAssignmentOperator for its
main logic.

The new symbol was further added to "clang/tools/libclang/libclang.map"
to be exported, under the LLVM16 tag.

"clang/tools/c-index-test/c-index-test.c" was modified to print a
specific tag, "(copy-assignment operator)", for cursors that are
recognized by clang_CXXMethod_isCopyAssignmentOperator.
A new regression test file,
"clang/test/Index/copy-assignment-operator.cpp", was added to ensure
that the correct constructs were recognized or not by the new function.

The "clang/test/Index/get-cursor.cpp" regression test file was updated
as it was affected by the new "(copy-assignment operator)" tag.

A binding for the new function was added to libclang's python's
bindings, in "clang/bindings/python/clang/cindex.py", adding a new
method for Cursor, is_copy_assignment_operator_method.

The current release note, clang/docs/ReleaseNotes.rst, was modified to
report the new addition under the "libclang" section.

[aaron.ballman]

LGTM!

Would you like to obtain commit access to land this one on your own (https://llvm.org/docs/DeveloperPolicy.html#obtaining-commit-access)? If not, that's fine, I can also land it on your behalf.

[diseraluca]

In D136604#3879928, @aaron.ballman wrote:

LGTM!

Would you like to obtain commit access to land this one on your own (https://llvm.org/docs/DeveloperPolicy.html#obtaining-commit-access)? If not, that's fine, I can also land it on your behalf.

That seems like a nice idea, especially if it can save other people's time by having me finalize the commit. I've sent an email as detailed in the link you posted. I'll wait for an answer and, if it is positive, I'll try to do the landing myself.

[aaron.ballman]

In D136604#3881949, @diseraluca wrote:

In D136604#3879928, @aaron.ballman wrote:

LGTM!

Would you like to obtain commit access to land this one on your own (https://llvm.org/docs/DeveloperPolicy.html#obtaining-commit-access)? If not, that's fine, I can also land it on your behalf.

That seems like a nice idea, especially if it can save other people's time by having me finalize the commit. I've sent an email as detailed in the link you posted. I'll wait for an answer and, if it is positive, I'll try to do the landing myself.

Sounds great! If you run into problems or have questions, let me know and I'm happy to help. Thanks again for the improvements!

[diseraluca]

In D136604#3882192, @aaron.ballman wrote:

In D136604#3881949, @diseraluca wrote:

In D136604#3879928, @aaron.ballman wrote:

LGTM!

Would you like to obtain commit access to land this one on your own (https://llvm.org/docs/DeveloperPolicy.html#obtaining-commit-access)? If not, that's fine, I can also land it on your behalf.

That seems like a nice idea, especially if it can save other people's time by having me finalize the commit. I've sent an email as detailed in the link you posted. I'll wait for an answer and, if it is positive, I'll try to do the landing myself.

Sounds great! If you run into problems or have questions, let me know and I'm happy to help. Thanks again for the improvements!

Followed the guidelines to push the change. Hopefully I've done everything correctly.

clang/bindings/python/clang/cindex.py

def is_default_method(self):
         return conf.lib.clang_CXXMethod_isDefaulted(self)
 
     def is_deleted_method(self):
         """Returns True if the cursor refers to a C++ member function or member
         function template that is declared '= delete'.
         """
         return conf.lib.clang_CXXMethod_isDeleted(self)
 
+    def is_copy_assignment_operator_method(self):
+        """Returnrs True if the cursor refers to a copy-assignment operator.
+
+        A copy-assignment operator `X::operator=` is a non-static,
+        non-template member function of _class_ `X` with exactly one
+        parameter of type `X`, `X&`, `const X&`, `volatile X&` or `const
+        volatile X&`.
+
+
+        That is, for example, the `operator=` in:
+
+           class Foo {
+               bool operator=(const volatile Foo&);
+           };
+
+        Is a copy-assignment operator, while the `operator=` in:
+
+           class Bar {
+               bool operator=(const int&);
+           };
+
+        Is not.
+        """
+        return conf.lib.clang_CXXMethod_isCopyAssignmentOperator(self)
+
     def is_mutable_field(self):
         """Returns True if the cursor refers to a C++ field that is declared
         'mutable'.
         """
         return conf.lib.clang_CXXField_isMutable(self)
 
     def is_pure_virtual_method(self):
         """Returns True if the cursor refers to a C++ member function or member
functionList = [
   ("clang_CXXMethod_isDefaulted",
    [Cursor],
    bool),
 
   ("clang_CXXMethod_isDeleted",
    [Cursor],
    bool),
 
+  ("clang_CXXMethod_isCopyAssignmentOperator",
+   [Cursor],
+   bool),
+
   ("clang_CXXMethod_isPureVirtual",
    [Cursor],
    bool),
 
   ("clang_CXXMethod_isStatic",
    [Cursor],
    bool),
 

clang/docs/ReleaseNotes.rst

 libclang
 --------
 - Introduced the new function ``clang_getUnqualifiedType``, which mimics
   the behavior of ``QualType::getUnqualifiedType`` for ``CXType``.
 - Introduced the new function ``clang_getNonReferenceType``, which mimics
   the behavior of ``QualType::getNonReferenceType`` for ``CXType``.
 - Introduced the new function ``clang_CXXMethod_isDeleted``, which queries
   whether the method is declared ``= delete``.
-- ``clang_Cursor_getNumTemplateArguments``, ``clang_Cursor_getTemplateArgumentKind``,
-  ``clang_Cursor_getTemplateArgumentType``, ``clang_Cursor_getTemplateArgumentValue`` and
+- Introduced the new function ``clang_CXXMethod_isCopyAssignmentOperator``,
+  which identifies whether a method cursor is a copy-assignment
+  operator.
+- ``clang_Cursor_getNumTemplateArguments``, ``clang_Cursor_getTemplateArgumentKind``, 
+  ``clang_Cursor_getTemplateArgumentType``, ``clang_Cursor_getTemplateArgumentValue`` and 
   ``clang_Cursor_getTemplateArgumentUnsignedValue`` now work on struct, class,
   and partial template specialization cursors in addition to function cursors.
 
 Static Analyzer
 ---------------
 - Removed the deprecated ``-analyzer-store`` and
   ``-analyzer-opt-analyze-nested-blocks`` analyzer flags.
   ``scanbuild`` was also updated accordingly.

clang/include/clang-c/Index.h

 /**
  * Determine if a C++ member function or member function template is
  * explicitly declared 'virtual' or if it overrides a virtual method from
  * one of the base classes.
  */
 CINDEX_LINKAGE unsigned clang_CXXMethod_isVirtual(CXCursor C);
 
 /**
+ * Determine if a C++ member function is a copy-assignment operator,
+ * returning 1 if such is the case and 0 otherwise.
+ *
+ * > A copy-assignment operator `X::operator=` is a non-static,
+ * > non-template member function of _class_ `X` with exactly one
+ * > parameter of type `X`, `X&`, `const X&`, `volatile X&` or `const
+ * > volatile X&`.
+ *
+ * That is, for example, the `operator=` in:
+ *
+ *    class Foo {
+ *        bool operator=(const volatile Foo&);
+ *    };
+ *
+ * Is a copy-assignment operator, while the `operator=` in:
+ *
+ *    class Bar {
+ *        bool operator=(const int&);
+ *    };
+ *
+ * Is not.
+ */
+CINDEX_LINKAGE unsigned clang_CXXMethod_isCopyAssignmentOperator(CXCursor C);
+
+/**
  * Determine if a C++ record is abstract, i.e. whether a class or struct
  * has a pure virtual member function.
  */
 CINDEX_LINKAGE unsigned clang_CXXRecord_isAbstract(CXCursor C);
 
 /**
  * Determine if an enum declaration refers to a scoped enum.
  */

clang/test/Index/copy-assignment-operator.cpp

+struct Foo {
+    // Those are copy-assignment operators
+    bool operator=(const Foo&);
+    bool operator=(Foo&);
+    bool operator=(volatile Foo&);
+    bool operator=(const volatile Foo&);
+    bool operator=(Foo);
+
+    // Those are not copy-assignment operators
+    template<typename T>
+    bool operator=(const T&);
+    bool operator=(const bool&);
+    bool operator=(char&);
+    bool operator=(volatile unsigned int&);
+    bool operator=(const volatile unsigned char&);
+    bool operator=(int);
+};
+
+// Positive-check that the recognition works for templated classes too
+template <typename T>
+class Bar {
+    bool operator=(const Bar&);
+    bool operator=(Bar<T>&);
+    bool operator=(volatile Bar&);
+    bool operator=(const volatile Bar<T>&);
+    bool operator=(Bar);
+};
+
+// RUN: c-index-test -test-print-type --std=c++11 %s | FileCheck %s
+// CHECK: StructDecl=Foo:1:8 (Definition) [type=Foo] [typekind=Record] [isPOD=0]
+// CHECK: CXXMethod=operator=:3:10 (copy-assignment operator) [type=bool (const Foo &)] [typekind=FunctionProto] [canonicaltype=bool (const Foo &)] [canonicaltypekind=FunctionProto] [resulttype=bool] [resulttypekind=Bool] [args= [const Foo &] [LValueReference]] [isPOD=0] [isAnonRecDecl=0]
+// CHECK: CXXMethod=operator=:4:10 (copy-assignment operator) [type=bool (Foo &)] [typekind=FunctionProto] [canonicaltype=bool (Foo &)] [canonicaltypekind=FunctionProto] [resulttype=bool] [resulttypekind=Bool] [args= [Foo &] [LValueReference]] [isPOD=0] [isAnonRecDecl=0]
+// CHECK: CXXMethod=operator=:5:10 (copy-assignment operator) [type=bool (volatile Foo &)] [typekind=FunctionProto] [canonicaltype=bool (volatile Foo &)] [canonicaltypekind=FunctionProto] [resulttype=bool] [resulttypekind=Bool] [args= [volatile Foo &] [LValueReference]] [isPOD=0] [isAnonRecDecl=0]
+// CHECK: CXXMethod=operator=:6:10 (copy-assignment operator) [type=bool (const volatile Foo &)] [typekind=FunctionProto] [canonicaltype=bool (const volatile Foo &)] [canonicaltypekind=FunctionProto] [resulttype=bool] [resulttypekind=Bool] [args= [const volatile Foo &] [LValueReference]] [isPOD=0] [isAnonRecDecl=0]
+// CHECK: CXXMethod=operator=:7:10 (copy-assignment operator) [type=bool (Foo)] [typekind=FunctionProto] [canonicaltype=bool (Foo)] [canonicaltypekind=FunctionProto] [resulttype=bool] [resulttypekind=Bool] [args= [Foo] [Elaborated]] [isPOD=0] [isAnonRecDecl=0]
+// CHECK: FunctionTemplate=operator=:11:10 [type=bool (const T &)] [typekind=FunctionProto] [canonicaltype=bool (const type-parameter-0-0 &)] [canonicaltypekind=FunctionProto] [resulttype=bool] [resulttypekind=Bool] [isPOD=0] [isAnonRecDecl=0]
+// CHECK: CXXMethod=operator=:12:10 [type=bool (const bool &)] [typekind=FunctionProto] [resulttype=bool] [resulttypekind=Bool] [args= [const bool &] [LValueReference]] [isPOD=0] [isAnonRecDecl=0]
+// CHECK: CXXMethod=operator=:13:10 [type=bool (char &)] [typekind=FunctionProto] [resulttype=bool] [resulttypekind=Bool] [args= [char &] [LValueReference]] [isPOD=0] [isAnonRecDecl=0]
+// CHECK: CXXMethod=operator=:14:10 [type=bool (volatile unsigned int &)] [typekind=FunctionProto] [resulttype=bool] [resulttypekind=Bool] [args= [volatile unsigned int &] [LValueReference]] [isPOD=0] [isAnonRecDecl=0]
+// CHECK: CXXMethod=operator=:15:10 [type=bool (const volatile unsigned char &)] [typekind=FunctionProto] [resulttype=bool] [resulttypekind=Bool] [args= [const volatile unsigned char &] [LValueReference]] [isPOD=0] [isAnonRecDecl=0]
+// CHECK: CXXMethod=operator=:16:10 [type=bool (int)] [typekind=FunctionProto] [resulttype=bool] [resulttypekind=Bool] [args= [int] [Int]] [isPOD=0] [isAnonRecDecl=0]
+// CHECK: ClassTemplate=Bar:21:7 (Definition) [type=] [typekind=Invalid] [isPOD=0] [isAnonRecDecl=0]
+// CHECK: CXXMethod=operator=:22:10 (copy-assignment operator) [type=bool (const Bar<T> &)] [typekind=FunctionProto] [canonicaltype=bool (const Bar<T> &)] [canonicaltypekind=FunctionProto] [resulttype=bool] [resulttypekind=Bool] [args= [const Bar<T> &] [LValueReference]] [isPOD=0] [isAnonRecDecl=0]
+// CHECK: CXXMethod=operator=:23:10 (copy-assignment operator) [type=bool (Bar<T> &)] [typekind=FunctionProto] [canonicaltype=bool (Bar<T> &)] [canonicaltypekind=FunctionProto] [resulttype=bool] [resulttypekind=Bool] [args= [Bar<T> &] [LValueReference]] [isPOD=0] [isAnonRecDecl=0]
+// CHECK: CXXMethod=operator=:24:10 (copy-assignment operator) [type=bool (volatile Bar<T> &)] [typekind=FunctionProto] [canonicaltype=bool (volatile Bar<T> &)] [canonicaltypekind=FunctionProto] [resulttype=bool] [resulttypekind=Bool] [args= [volatile Bar<T> &] [LValueReference]] [isPOD=0] [isAnonRecDecl=0]
+// CHECK: CXXMethod=operator=:25:10 (copy-assignment operator) [type=bool (const volatile Bar<T> &)] [typekind=FunctionProto] [canonicaltype=bool (const volatile Bar<T> &)] [canonicaltypekind=FunctionProto] [resulttype=bool] [resulttypekind=Bool] [args= [const volatile Bar<T> &] [LValueReference]] [isPOD=0] [isAnonRecDecl=0]
+// CHECK: CXXMethod=operator=:26:10 (copy-assignment operator) [type=bool (Bar<T>)] [typekind=FunctionProto] [canonicaltype=bool (Bar<T>)] [canonicaltypekind=FunctionProto] [resulttype=bool] [resulttypekind=Bool] [args= [Bar<T>] [Elaborated]] [isPOD=0] [isAnonRecDecl=0]

clang/test/Index/get-cursor.cpp

 // CHECK-TEMPLPARAM: 55:23 TypeRef=struct X:3:8 Extent=[55:23 - 55:24] Spelling=struct X ([55:23 - 55:24])
 
 // RUN: c-index-test -cursor-at=%s:66:23 %s | FileCheck -check-prefix=CHECK-TEMPLSPEC %s
 // CHECK-TEMPLSPEC: 66:23 ClassDecl=TC:66:23 (Definition) [Specialization of TC:59:7] [Template arg 0: kind: 1, type: char] Extent=[66:1 - 66:31] Spelling=TC ([66:23 - 66:25])
 
 // RUN: c-index-test -cursor-at=%s:69:3 -cursor-at=%s:70:11 -cursor-at=%s:73:6 -cursor-at=%s:74:6 -cursor-at=%s:77:8 -cursor-at=%s:78:8 -cursor-at=%s:79:8 -cursor-at=%s:80:8 -cursor-at=%s:81:8 -cursor-at=%s:82:8 -cursor-at=%s:85:6 -cursor-at=%s:86:6 -cursor-at=%s:87:6 -cursor-at=%s:88:6 -cursor-at=%s:91:5 -cursor-at=%s:92:5 -cursor-at=%s:93:5 -cursor-at=%s:94:5 -cursor-at=%s:95:5 -cursor-at=%s:96:5 -cursor-at=%s:97:5 -cursor-at=%s:98:5 -cursor-at=%s:100:5 -cursor-at=%s:101:5 -cursor-at=%s:104:6 -cursor-at=%s:105:6 -cursor-at=%s:106:6 -cursor-at=%s:107:6 -cursor-at=%s:108:6 -cursor-at=%s:109:6 -cursor-at=%s:110:6 -cursor-at=%s:111:6 -cursor-at=%s:113:6 -cursor-at=%s:114:6 -cursor-at=%s:117:8 -cursor-at=%s:118:8 -cursor-at=%s:120:8 -cursor-at=%s:121:8 -cursor-at=%s:122:8 -cursor-at=%s:123:8 -cursor-at=%s:124:8 -cursor-at=%s:125:8 -cursor-at=%s:128:6 -cursor-at=%s:129:6 -cursor-at=%s:130:6 -cursor-at=%s:132:3 -cursor-at=%s:146:15 -cursor-at=%s:149:6 -cursor-at=%s:150:25 -cursor-at=%s:151:6 -cursor-at=%s:152:6 -cursor-at=%s:153:6 -cursor-at=%s:154:6 -cursor-at=%s:155:6 -std=c++11 %s | FileCheck -check-prefix=CHECK-SPELLING %s
 // CHECK-SPELLING: 69:3 CXXConstructor=A:69:3 (default constructor) Extent=[69:3 - 69:6] Spelling=A ([69:3 - 69:4])
 // CHECK-SPELLING: 70:11 CXXDestructor=~A:70:11 (virtual) Extent=[70:3 - 70:15] Spelling=~A ([70:11 - 70:13])
-// CHECK-SPELLING: 73:6 CXXMethod=operator=:73:6 Extent=[73:3 - 73:25] Spelling=operator= ([73:6 - 73:15])
+// CHECK-SPELLING: 73:6 CXXMethod=operator=:73:6 (copy-assignment operator) Extent=[73:3 - 73:25] Spelling=operator= ([73:6 - 73:15])
 // CHECK-SPELLING: 74:6 CXXMethod=operator=:74:6 (noexcept) Extent=[74:3 - 74:29] Spelling=operator= ([74:6 - 74:15])
 // CHECK-SPELLING: 77:8 CXXMethod=operator+:77:8 (const) Extent=[77:3 - 77:25] Spelling=operator+ ([77:8 - 77:17])
 // CHECK-SPELLING: 78:8 CXXMethod=operator-:78:8 (const) Extent=[78:3 - 78:25] Spelling=operator- ([78:8 - 78:17])
 // CHECK-SPELLING: 79:8 CXXMethod=operator~:79:8 (const) Extent=[79:3 - 79:25] Spelling=operator~ ([79:8 - 79:17])
 // CHECK-SPELLING: 80:8 CXXMethod=operator*:80:8 (const) Extent=[80:3 - 80:25] Spelling=operator* ([80:8 - 80:17])
 // CHECK-SPELLING: 81:8 CXXMethod=operator&:81:8 (const) Extent=[81:3 - 81:25] Spelling=operator& ([81:8 - 81:17])
 // CHECK-SPELLING: 82:8 CXXMethod=operator!:82:8 (const) Extent=[82:3 - 82:25] Spelling=operator! ([82:8 - 82:17])
 // CHECK-SPELLING: 85:6 CXXMethod=operator++:85:6 Extent=[85:3 - 85:18] Spelling=operator++ ([85:6 - 85:16])

clang/tools/c-index-test/c-index-test.c

else {
     if (clang_CXXMethod_isStatic(Cursor))
       printf(" (static)");
     if (clang_CXXMethod_isVirtual(Cursor))
       printf(" (virtual)");
     if (clang_CXXMethod_isConst(Cursor))
       printf(" (const)");
     if (clang_CXXMethod_isPureVirtual(Cursor))
       printf(" (pure)");
+    if (clang_CXXMethod_isCopyAssignmentOperator(Cursor))
+      printf(" (copy-assignment operator)");
     if (clang_CXXRecord_isAbstract(Cursor))
       printf(" (abstract)");
     if (clang_EnumDecl_isScoped(Cursor))
       printf(" (scoped)");
     if (clang_Cursor_isVariadic(Cursor))
       printf(" (variadic)");
     if (clang_Cursor_isObjCOptional(Cursor))
       printf(" (@optional)");

clang/tools/libclang/CIndex.cpp

if (!clang_isDeclaration(C.kind))
     return 0;
 
   const Decl *D = cxcursor::getCursorDecl(C);
   const CXXMethodDecl *Method =
       D ? dyn_cast_or_null<CXXMethodDecl>(D->getAsFunction()) : nullptr;
   return (Method && Method->isVirtual()) ? 1 : 0;
 }
 
+unsigned clang_CXXMethod_isCopyAssignmentOperator(CXCursor C) {
+  if (!clang_isDeclaration(C.kind))
+    return 0;
+
+  const Decl *D = cxcursor::getCursorDecl(C);
+  const CXXMethodDecl *Method =
+      D ? dyn_cast_or_null<CXXMethodDecl>(D->getAsFunction()) : nullptr;
+
+  return (Method && Method->isCopyAssignmentOperator()) ? 1 : 0;
+}
+
 unsigned clang_CXXRecord_isAbstract(CXCursor C) {
   if (!clang_isDeclaration(C.kind))
     return 0;
 
   const auto *D = cxcursor::getCursorDecl(C);
   const auto *RD = dyn_cast_or_null<CXXRecordDecl>(D);
   if (RD)
     RD = RD->getDefinition();

clang/tools/libclang/libclang.map

LLVM_13 {
   local: *;
 };
 
 LLVM_16 {
   global:
     clang_getUnqualifiedType;
     clang_getNonReferenceType;
     clang_CXXMethod_isDeleted;
+    clang_CXXMethod_isCopyAssignmentOperator;
 };
 
 # Example of how to add a new symbol version entry.  If you do add a new symbol
 # version, please update the example to depend on the version you added.
 # LLVM_X {
 # global:
 #   clang_newsymbol;
 # };