clang 8.0.0

Typedefs | Enumerations | Functions
Cross-referencing in the AST
libclang: C Interface to Clang

These routines provide the ability to determine references within and across translation units, by providing the names of the entities referenced by cursors, follow reference cursors to the declarations they reference, and associate declarations with their definitions. More...

Collaboration diagram for Cross-referencing in the AST:

## Typedefs
typedef void * | CXPrintingPolicy
| Opaque pointer representing a policy that controls pretty printing for `clang_getCursorPrettyPrinted`. More...

## Enumerations
enum | CXPrintingPolicyProperty { CXPrintingPolicy_Indentation, CXPrintingPolicy_SuppressSpecifiers, CXPrintingPolicy_SuppressTagKeyword, CXPrintingPolicy_IncludeTagDefinition, CXPrintingPolicy_SuppressScope, CXPrintingPolicy_SuppressUnwrittenScope, CXPrintingPolicy_SuppressInitializers, CXPrintingPolicy_ConstantArraySizeAsWritten, CXPrintingPolicy_AnonymousTagLocations, CXPrintingPolicy_SuppressStrongLifetime, CXPrintingPolicy_SuppressLifetimeQualifiers, CXPrintingPolicy_SuppressTemplateArgsInCXXConstructors, CXPrintingPolicy_Bool, CXPrintingPolicy_Restrict, CXPrintingPolicy_Alignof, CXPrintingPolicy_UnderscoreAlignof, CXPrintingPolicy_UseVoidForZeroParams, CXPrintingPolicy_TerseOutput, CXPrintingPolicy_PolishForDeclaration, CXPrintingPolicy_Half, CXPrintingPolicy_MSWChar, CXPrintingPolicy_IncludeNewlines, CXPrintingPolicy_MSVCFormatting, CXPrintingPolicy_ConstantsAsWritten, CXPrintingPolicy_SuppressImplicitBase, CXPrintingPolicy_FullyQualifiedName, CXPrintingPolicy_LastProperty = CXPrintingPolicy_FullyQualifiedName }
| Properties for the printing policy. More...
enum | CXObjCPropertyAttrKind { CXObjCPropertyAttr_noattr = 0x00, CXObjCPropertyAttr_readonly = 0x01, CXObjCPropertyAttr_getter = 0x02, CXObjCPropertyAttr_assign = 0x04, CXObjCPropertyAttr_readwrite = 0x08, CXObjCPropertyAttr_retain = 0x10, CXObjCPropertyAttr_copy = 0x20, CXObjCPropertyAttr_nonatomic = 0x40, CXObjCPropertyAttr_setter = 0x80, CXObjCPropertyAttr_atomic = 0x100, CXObjCPropertyAttr_weak = 0x200, CXObjCPropertyAttr_strong = 0x400, CXObjCPropertyAttr_unsafe_unretained = 0x800, CXObjCPropertyAttr_class = 0x1000 }
| Property attributes for a `CXCursor_ObjCPropertyDecl`. More...
enum | CXObjCDeclQualifierKind { CXObjCDeclQualifier_None = 0x0, CXObjCDeclQualifier_In = 0x1, CXObjCDeclQualifier_Inout = 0x2, CXObjCDeclQualifier_Out = 0x4, CXObjCDeclQualifier_Bycopy = 0x8, CXObjCDeclQualifier_Byref = 0x10, CXObjCDeclQualifier_Oneway = 0x20 }
| 'Qualifiers' written next to the return and parameter types in Objective-C method declarations. More...

## Functions
CINDEX_LINKAGE CXString | clang_getCursorUSR (CXCursor)
| Retrieve a Unified Symbol Resolution (USR) for the entity referenced by the given cursor. More...
CINDEX_LINKAGE CXString | clang_constructUSR_ObjCClass (const char *class_name)
| Construct a USR for a specified Objective-C class. More...
CINDEX_LINKAGE CXString | clang_constructUSR_ObjCCategory (const char *class_name, const char *category_name)
| Construct a USR for a specified Objective-C category. More...
CINDEX_LINKAGE CXString | clang_constructUSR_ObjCProtocol (const char *protocol_name)
| Construct a USR for a specified Objective-C protocol. More...
CINDEX_LINKAGE CXString | clang_constructUSR_ObjCIvar (const char *name, CXString classUSR)
| Construct a USR for a specified Objective-C instance variable and the USR for its containing class. More...
CINDEX_LINKAGE CXString | clang_constructUSR_ObjCMethod (const char *name, unsigned isInstanceMethod, CXString classUSR)
| Construct a USR for a specified Objective-C method and the USR for its containing class. More...
CINDEX_LINKAGE CXString | clang_constructUSR_ObjCProperty (const char *property, CXString classUSR)
| Construct a USR for a specified Objective-C property and the USR for its containing class. More...
CINDEX_LINKAGE CXString | clang_getCursorSpelling (CXCursor)
| Retrieve a name for the entity referenced by this cursor. More...
CINDEX_LINKAGE CXSourceRange | clang_Cursor_getSpellingNameRange (CXCursor, unsigned pieceIndex, unsigned options)
| Retrieve a range for a piece that forms the cursors spelling name. More...
CINDEX_LINKAGE unsigned | clang_PrintingPolicy_getProperty (CXPrintingPolicy Policy, enum CXPrintingPolicyProperty Property)
| Get a property value for the given printing policy. More...
CINDEX_LINKAGE void | clang_PrintingPolicy_setProperty (CXPrintingPolicy Policy, enum CXPrintingPolicyProperty Property, unsigned Value)
| Set a property value for the given printing policy. More...
CINDEX_LINKAGE CXPrintingPolicy | clang_getCursorPrintingPolicy (CXCursor)
| Retrieve the default policy for the cursor. More...
CINDEX_LINKAGE void | clang_PrintingPolicy_dispose (CXPrintingPolicy Policy)
| Release a printing policy. More...
CINDEX_LINKAGE CXString | clang_getCursorPrettyPrinted (CXCursor Cursor, CXPrintingPolicy Policy)
| Pretty print declarations. More...
CINDEX_LINKAGE CXString | clang_getCursorDisplayName (CXCursor)
| Retrieve the display name for the entity referenced by this cursor. More...
CINDEX_LINKAGE CXCursor | clang_getCursorReferenced (CXCursor)
| For a cursor that is a reference, retrieve a cursor representing the entity that it references. More...
CINDEX_LINKAGE CXCursor | clang_getCursorDefinition (CXCursor)
| For a cursor that is either a reference to or a declaration of some entity, retrieve a cursor that describes the definition of that entity. More...
CINDEX_LINKAGE unsigned | clang_isCursorDefinition (CXCursor)
| Determine whether the declaration pointed to by this cursor is also a definition of that entity. More...
CINDEX_LINKAGE CXCursor | clang_getCanonicalCursor (CXCursor)
| Retrieve the canonical cursor corresponding to the given cursor. More...
CINDEX_LINKAGE int | clang_Cursor_getObjCSelectorIndex (CXCursor)
| If the cursor points to a selector identifier in an Objective-C method or message expression, this returns the selector index. More...
CINDEX_LINKAGE int | clang_Cursor_isDynamicCall (CXCursor C)
| Given a cursor pointing to a C++ method call or an Objective-C message, returns non-zero if the method/message is "dynamic", meaning: More...
CINDEX_LINKAGE CXType | clang_Cursor_getReceiverType (CXCursor C)
| Given a cursor pointing to an Objective-C message or property reference, or C++ method call, returns the CXType of the receiver. More...
CINDEX_LINKAGE unsigned | clang_Cursor_getObjCPropertyAttributes (CXCursor C, unsigned reserved)
| Given a cursor that represents a property declaration, return the associated property attributes. More...
CINDEX_LINKAGE CXString | clang_Cursor_getObjCPropertyGetterName (CXCursor C)
| Given a cursor that represents a property declaration, return the name of the method that implements the getter. More...
CINDEX_LINKAGE CXString | clang_Cursor_getObjCPropertySetterName (CXCursor C)
| Given a cursor that represents a property declaration, return the name of the method that implements the setter, if any. More...
CINDEX_LINKAGE unsigned | clang_Cursor_getObjCDeclQualifiers (CXCursor C)
| Given a cursor that represents an Objective-C method or parameter declaration, return the associated Objective-C qualifiers for the return type or the parameter respectively. More...
CINDEX_LINKAGE unsigned | clang_Cursor_isObjCOptional (CXCursor C)
| Given a cursor that represents an Objective-C method or property declaration, return non-zero if the declaration was affected by "\@optional". More...
CINDEX_LINKAGE unsigned | clang_Cursor_isVariadic (CXCursor C)
| Returns non-zero if the given cursor is a variadic function or method. More...
CINDEX_LINKAGE unsigned | clang_Cursor_isExternalSymbol (CXCursor C, CXString *language, CXString *definedIn, unsigned *isGenerated)
| Returns non-zero if the given cursor points to a symbol marked with external_source_symbol attribute. More...
CINDEX_LINKAGE CXSourceRange | clang_Cursor_getCommentRange (CXCursor C)
| Given a cursor that represents a declaration, return the associated comment's source range. More...
CINDEX_LINKAGE CXString | clang_Cursor_getRawCommentText (CXCursor C)
| Given a cursor that represents a declaration, return the associated comment text, including comment markers. More...
CINDEX_LINKAGE CXString | clang_Cursor_getBriefCommentText (CXCursor C)
| Given a cursor that represents a documentable entity (e.g., declaration), return the associated. More...

## Detailed Description

These routines provide the ability to determine references within and across translation units, by providing the names of the entities referenced by cursors, follow reference cursors to the declarations they reference, and associate declarations with their definitions.

## Typedef Documentation

## ◆ CXPrintingPolicy

typedef void* CXPrintingPolicy

Opaque pointer representing a policy that controls pretty printing for `clang_getCursorPrettyPrinted`.

Definition at line 4243 of file Index.h.

## Enumeration Type Documentation

## ◆ CXObjCDeclQualifierKind

enum CXObjCDeclQualifierKind

'Qualifiers' written next to the return and parameter types in Objective-C method declarations.

Enumerator
CXObjCDeclQualifier_None |
CXObjCDeclQualifier_In |
CXObjCDeclQualifier_Inout |
CXObjCDeclQualifier_Out |
CXObjCDeclQualifier_Bycopy |
CXObjCDeclQualifier_Byref |
CXObjCDeclQualifier_Oneway |

Definition at line 4483 of file Index.h.

## ◆ CXObjCPropertyAttrKind

enum CXObjCPropertyAttrKind

Property attributes for a `CXCursor_ObjCPropertyDecl`.

Enumerator
CXObjCPropertyAttr_noattr |
CXObjCPropertyAttr_readonly |
CXObjCPropertyAttr_getter |
CXObjCPropertyAttr_assign |
CXObjCPropertyAttr_readwrite |
CXObjCPropertyAttr_retain |
CXObjCPropertyAttr_copy |
CXObjCPropertyAttr_nonatomic |
CXObjCPropertyAttr_setter |
CXObjCPropertyAttr_atomic |
CXObjCPropertyAttr_weak |
CXObjCPropertyAttr_strong |
CXObjCPropertyAttr_unsafe_unretained |
CXObjCPropertyAttr_class |

Definition at line 4440 of file Index.h.

## ◆ CXPrintingPolicyProperty

enum CXPrintingPolicyProperty

Properties for the printing policy.

See `clang::PrintingPolicy` for more information.

Enumerator
CXPrintingPolicy_Indentation |
CXPrintingPolicy_SuppressSpecifiers |
CXPrintingPolicy_SuppressTagKeyword |
CXPrintingPolicy_IncludeTagDefinition |
CXPrintingPolicy_SuppressScope |
CXPrintingPolicy_SuppressUnwrittenScope |
CXPrintingPolicy_SuppressInitializers |
CXPrintingPolicy_ConstantArraySizeAsWritten |
CXPrintingPolicy_AnonymousTagLocations |
CXPrintingPolicy_SuppressStrongLifetime |
CXPrintingPolicy_SuppressLifetimeQualifiers |
CXPrintingPolicy_SuppressTemplateArgsInCXXConstructors |
CXPrintingPolicy_Bool |
CXPrintingPolicy_Restrict |
CXPrintingPolicy_Alignof |
CXPrintingPolicy_UnderscoreAlignof |
CXPrintingPolicy_UseVoidForZeroParams |
CXPrintingPolicy_TerseOutput |
CXPrintingPolicy_PolishForDeclaration |
CXPrintingPolicy_Half |
CXPrintingPolicy_MSWChar |
CXPrintingPolicy_IncludeNewlines |
CXPrintingPolicy_MSVCFormatting |
CXPrintingPolicy_ConstantsAsWritten |
CXPrintingPolicy_SuppressImplicitBase |
CXPrintingPolicy_FullyQualifiedName |
CXPrintingPolicy_LastProperty |

Definition at line 4250 of file Index.h.

## Function Documentation

## ◆ clang_constructUSR_ObjCCategory()

CINDEX_LINKAGE CXString clang_constructUSR_ObjCCategory | ( | const char * | class_name,
|  | const char * | category_name
| ) |  |

Construct a USR for a specified Objective-C category.

## ◆ clang_constructUSR_ObjCClass()

CINDEX_LINKAGE CXString clang_constructUSR_ObjCClass | ( | const char * | class_name | ) |

Construct a USR for a specified Objective-C class.

## ◆ clang_constructUSR_ObjCIvar()

CINDEX_LINKAGE CXString clang_constructUSR_ObjCIvar | ( | const char * | name,
|  | CXString | classUSR
| ) |  |

Construct a USR for a specified Objective-C instance variable and the USR for its containing class.

## ◆ clang_constructUSR_ObjCMethod()

CINDEX_LINKAGE CXString clang_constructUSR_ObjCMethod | ( | const char * | name,
|  | unsigned | isInstanceMethod,
|  | CXString | classUSR
| ) |  |

Construct a USR for a specified Objective-C method and the USR for its containing class.

## ◆ clang_constructUSR_ObjCProperty()

CINDEX_LINKAGE CXString clang_constructUSR_ObjCProperty | ( | const char * | property,
|  | CXString | classUSR
| ) |  |

Construct a USR for a specified Objective-C property and the USR for its containing class.

## ◆ clang_constructUSR_ObjCProtocol()

CINDEX_LINKAGE CXString clang_constructUSR_ObjCProtocol | ( | const char * | protocol_name | ) |

Construct a USR for a specified Objective-C protocol.

## ◆ clang_Cursor_getBriefCommentText()

CINDEX_LINKAGE CXString clang_Cursor_getBriefCommentText | ( | CXCursor | C | ) |

Given a cursor that represents a documentable entity (e.g., declaration), return the associated.

first paragraph.

## ◆ clang_Cursor_getCommentRange()

CINDEX_LINKAGE CXSourceRange clang_Cursor_getCommentRange | ( | CXCursor | C | ) |

Given a cursor that represents a declaration, return the associated comment's source range.

The range may include multiple consecutive comments with whitespace in between.

## ◆ clang_Cursor_getObjCDeclQualifiers()

CINDEX_LINKAGE unsigned clang_Cursor_getObjCDeclQualifiers | ( | CXCursor | C | ) |

Given a cursor that represents an Objective-C method or parameter declaration, return the associated Objective-C qualifiers for the return type or the parameter respectively.

The bits are formed from CXObjCDeclQualifierKind.

## ◆ clang_Cursor_getObjCPropertyAttributes()

CINDEX_LINKAGE unsigned clang_Cursor_getObjCPropertyAttributes | ( | CXCursor | C,
|  | unsigned | reserved
| ) |  |

Given a cursor that represents a property declaration, return the associated property attributes.

The bits are formed from `CXObjCPropertyAttrKind`.

Parameters

  reserved | Reserved for future use, pass 0.

## ◆ clang_Cursor_getObjCPropertyGetterName()

CINDEX_LINKAGE CXString clang_Cursor_getObjCPropertyGetterName | ( | CXCursor | C | ) |

Given a cursor that represents a property declaration, return the name of the method that implements the getter.

## ◆ clang_Cursor_getObjCPropertySetterName()

CINDEX_LINKAGE CXString clang_Cursor_getObjCPropertySetterName | ( | CXCursor | C | ) |

Given a cursor that represents a property declaration, return the name of the method that implements the setter, if any.

## ◆ clang_Cursor_getObjCSelectorIndex()

CINDEX_LINKAGE int clang_Cursor_getObjCSelectorIndex | ( | CXCursor |  | ) |

If the cursor points to a selector identifier in an Objective-C method or message expression, this returns the selector index.

After getting a cursor with clang_getCursor, this can be called to determine if the location points to a selector identifier.

Returns
  The selector index if the cursor is an Objective-C method or message expression and the cursor is pointing to a selector identifier, or -1 otherwise.

## ◆ clang_Cursor_getRawCommentText()

CINDEX_LINKAGE CXString clang_Cursor_getRawCommentText | ( | CXCursor | C | ) |

Given a cursor that represents a declaration, return the associated comment text, including comment markers.

## ◆ clang_Cursor_getReceiverType()

CINDEX_LINKAGE CXType clang_Cursor_getReceiverType | ( | CXCursor | C | ) |

Given a cursor pointing to an Objective-C message or property reference, or C++ method call, returns the CXType of the receiver.

## ◆ clang_Cursor_getSpellingNameRange()

CINDEX_LINKAGE CXSourceRange clang_Cursor_getSpellingNameRange | ( | CXCursor | ,
|  | unsigned | pieceIndex,
|  | unsigned | options
| ) |  |

Retrieve a range for a piece that forms the cursors spelling name.

Most of the times there is only one range for the complete spelling but for Objective-C methods and Objective-C message expressions, there are multiple pieces for each selector identifier.

Parameters

  pieceIndex | the index of the spelling name piece. If this is greater than the actual number of pieces, it will return a NULL (invalid) range.
  options | Reserved.

## ◆ clang_Cursor_isDynamicCall()

CINDEX_LINKAGE int clang_Cursor_isDynamicCall | ( | CXCursor | C | ) |

Given a cursor pointing to a C++ method call or an Objective-C message, returns non-zero if the method/message is "dynamic", meaning:

For a C++ method: the call is virtual. For an Objective-C message: the receiver is an object instance, not 'super' or a specific class.

If the method/message is "static" or the cursor does not point to a method/message, it will return zero.

## ◆ clang_Cursor_isExternalSymbol()

CINDEX_LINKAGE unsigned clang_Cursor_isExternalSymbol | ( | CXCursor | C,
|  | CXString * | language,
|  | CXString * | definedIn,
|  | unsigned * | isGenerated
| ) |  |

Returns non-zero if the given cursor points to a symbol marked with external_source_symbol attribute.

Parameters

  language | If non-NULL, and the attribute is present, will be set to the 'language' string from the attribute.
  definedIn | If non-NULL, and the attribute is present, will be set to the 'definedIn' string from the attribute.
  isGenerated | If non-NULL, and the attribute is present, will be set to non-zero if the 'generated_declaration' is set in the attribute.

## ◆ clang_Cursor_isObjCOptional()

CINDEX_LINKAGE unsigned clang_Cursor_isObjCOptional | ( | CXCursor | C | ) |

Given a cursor that represents an Objective-C method or property declaration, return non-zero if the declaration was affected by "\@optional".

Returns zero if the cursor is not such a declaration or it is "\@required".

## ◆ clang_Cursor_isVariadic()

CINDEX_LINKAGE unsigned clang_Cursor_isVariadic | ( | CXCursor | C | ) |

Returns non-zero if the given cursor is a variadic function or method.

## ◆ clang_getCanonicalCursor()

CINDEX_LINKAGE CXCursor clang_getCanonicalCursor | ( | CXCursor |  | ) |

Retrieve the canonical cursor corresponding to the given cursor.

In the C family of languages, many kinds of entities can be declared several times within a single translation unit. For example, a structure type can be forward-declared (possibly multiple times) and later defined:

struct X;
struct X;
struct X {
int member;
};

The declarations and the definition of `X` are represented by three different cursors, all of which are declarations of the same underlying entity. One of these cursor is considered the "canonical" cursor, which is effectively the representative for the underlying entity. One can determine if two cursors are declarations of the same underlying entity by comparing their canonical cursors.

Returns
  The canonical cursor for the entity referred to by the given cursor.

## ◆ clang_getCursorDefinition()

CINDEX_LINKAGE CXCursor clang_getCursorDefinition | ( | CXCursor |  | ) |

For a cursor that is either a reference to or a declaration of some entity, retrieve a cursor that describes the definition of that entity.

Some entities can be declared multiple times within a translation unit, but only one of those declarations can also be a definition. For example, given:

int f(int, int);
int g(int x, int y) { return f(x, y); }
int f(int a, int b) { return a + b; }
int f(int, int);

there are three declarations of the function "f", but only the second one is a definition. The clang_getCursorDefinition() function will take any cursor pointing to a declaration of "f" (the first or fourth lines of the example) or a cursor referenced that uses "f" (the call to "f' inside "g") and will return a declaration cursor pointing to the definition (the second "f" declaration).

If given a cursor for which there is no corresponding definition, e.g., because there is no definition of that entity within this translation unit, returns a NULL cursor.

## ◆ clang_getCursorDisplayName()

CINDEX_LINKAGE CXString clang_getCursorDisplayName | ( | CXCursor |  | ) |

Retrieve the display name for the entity referenced by this cursor.

The display name contains extra information that helps identify the cursor, such as the parameters of a function or template or the arguments of a class template specialization.

## ◆ clang_getCursorPrettyPrinted()

CINDEX_LINKAGE CXString clang_getCursorPrettyPrinted | ( | CXCursor | Cursor,
|  | CXPrintingPolicy | Policy
| ) |  |

Pretty print declarations.

Parameters

  Cursor | The cursor representing a declaration.
  Policy | The policy to control the entities being printed. If NULL, a default policy is used.

Returns
  The pretty printed declaration or the empty string for other cursors.

## ◆ clang_getCursorPrintingPolicy()

CINDEX_LINKAGE CXPrintingPolicy clang_getCursorPrintingPolicy | ( | CXCursor |  | ) |

Retrieve the default policy for the cursor.

The policy should be released after use with `clang_PrintingPolicy_dispose`.

## ◆ clang_getCursorReferenced()

CINDEX_LINKAGE CXCursor clang_getCursorReferenced | ( | CXCursor |  | ) |

For a cursor that is a reference, retrieve a cursor representing the entity that it references.

Reference cursors refer to other entities in the AST. For example, an Objective-C superclass reference cursor refers to an Objective-C class. This function produces the cursor for the Objective-C class from the cursor for the superclass reference. If the input cursor is a declaration or definition, it returns that declaration or definition unchanged. Otherwise, returns the NULL cursor.

## ◆ clang_getCursorSpelling()

CINDEX_LINKAGE CXString clang_getCursorSpelling | ( | CXCursor |  | ) |

Retrieve a name for the entity referenced by this cursor.

## ◆ clang_getCursorUSR()

CINDEX_LINKAGE CXString clang_getCursorUSR | ( | CXCursor |  | ) |

Retrieve a Unified Symbol Resolution (USR) for the entity referenced by the given cursor.

A Unified Symbol Resolution (USR) is a string that identifies a particular entity (function, class, variable, etc.) within a program. USRs can be compared across translation units to determine, e.g., when references in one translation refer to an entity defined in another translation unit.

## ◆ clang_isCursorDefinition()

CINDEX_LINKAGE unsigned clang_isCursorDefinition | ( | CXCursor |  | ) |

Determine whether the declaration pointed to by this cursor is also a definition of that entity.

## ◆ clang_PrintingPolicy_dispose()

CINDEX_LINKAGE void clang_PrintingPolicy_dispose | ( | CXPrintingPolicy | Policy | ) |

Release a printing policy.

## ◆ clang_PrintingPolicy_getProperty()

CINDEX_LINKAGE unsigned clang_PrintingPolicy_getProperty | ( | CXPrintingPolicy | Policy,
|  | enum CXPrintingPolicyProperty | Property
| ) |  |

Get a property value for the given printing policy.

## ◆ clang_PrintingPolicy_setProperty()

CINDEX_LINKAGE void clang_PrintingPolicy_setProperty | ( | CXPrintingPolicy | Policy,
|  | enum CXPrintingPolicyProperty | Property,
|  | unsigned | Value
| ) |  |

Set a property value for the given printing policy.