clang 10.0.0git

Classes | Typedefs | Enumerations | Functions
Cursor manipulations
libclang: C Interface to Clang
Collaboration diagram for Cursor manipulations:

## Classes
struct | CXPlatformAvailability
| Describes the availability of a given entity on a particular platform, e.g., a particular class might only be available on Mac OS 10.7 or newer. More...

## Typedefs
typedef struct CXPlatformAvailability | CXPlatformAvailability
| Describes the availability of a given entity on a particular platform, e.g., a particular class might only be available on Mac OS 10.7 or newer. More...
typedef struct CXCursorSetImpl * | CXCursorSet
| A fast container representing a set of CXCursors. More...

## Enumerations
enum | CXLinkageKind { CXLinkage_Invalid, CXLinkage_NoLinkage, CXLinkage_Internal, CXLinkage_UniqueExternal, CXLinkage_External }
| Describe the linkage of the entity referred to by a cursor. More...
enum | CXVisibilityKind { CXVisibility_Invalid, CXVisibility_Hidden, CXVisibility_Protected, CXVisibility_Default }
enum | CXLanguageKind { CXLanguage_Invalid = 0, CXLanguage_C, CXLanguage_ObjC, CXLanguage_CPlusPlus }
| Describe the "language" of the entity referred to by a cursor. More...
enum | CXTLSKind { CXTLS_None = 0, CXTLS_Dynamic, CXTLS_Static }
| Describe the "thread-local storage (TLS) kind" of the declaration referred to by a cursor. More...

## Functions
CINDEX_LINKAGE CXCursor | clang_getNullCursor (void)
| Retrieve the NULL cursor, which represents no entity. More...
CINDEX_LINKAGE CXCursor | clang_getTranslationUnitCursor (CXTranslationUnit)
| Retrieve the cursor that represents the given translation unit. More...
CINDEX_LINKAGE unsigned | clang_equalCursors (CXCursor, CXCursor)
| Determine whether two cursors are equivalent. More...
CINDEX_LINKAGE int | clang_Cursor_isNull (CXCursor cursor)
| Returns non-zero if `cursor` is null. More...
CINDEX_LINKAGE unsigned | clang_hashCursor (CXCursor)
| Compute a hash value for the given cursor. More...
CINDEX_LINKAGE enum CXCursorKind | clang_getCursorKind (CXCursor)
| Retrieve the kind of the given cursor. More...
CINDEX_LINKAGE unsigned | clang_isDeclaration (enum CXCursorKind)
| Determine whether the given cursor kind represents a declaration. More...
CINDEX_LINKAGE unsigned | clang_isInvalidDeclaration (CXCursor)
| Determine whether the given declaration is invalid. More...
CINDEX_LINKAGE unsigned | clang_isReference (enum CXCursorKind)
| Determine whether the given cursor kind represents a simple reference. More...
CINDEX_LINKAGE unsigned | clang_isExpression (enum CXCursorKind)
| Determine whether the given cursor kind represents an expression. More...
CINDEX_LINKAGE unsigned | clang_isStatement (enum CXCursorKind)
| Determine whether the given cursor kind represents a statement. More...
CINDEX_LINKAGE unsigned | clang_isAttribute (enum CXCursorKind)
| Determine whether the given cursor kind represents an attribute. More...
CINDEX_LINKAGE unsigned | clang_Cursor_hasAttrs (CXCursor C)
| Determine whether the given cursor has any attributes. More...
CINDEX_LINKAGE unsigned | clang_isInvalid (enum CXCursorKind)
| Determine whether the given cursor kind represents an invalid cursor. More...
CINDEX_LINKAGE unsigned | clang_isTranslationUnit (enum CXCursorKind)
| Determine whether the given cursor kind represents a translation unit. More...
CINDEX_LINKAGE unsigned | clang_isPreprocessing (enum CXCursorKind)
CINDEX_LINKAGE unsigned | clang_isUnexposed (enum CXCursorKind)
CINDEX_LINKAGE enum CXLinkageKind | clang_getCursorLinkage (CXCursor cursor)
| Determine the linkage of the entity referred to by a given cursor. More...
CINDEX_LINKAGE enum CXVisibilityKind | clang_getCursorVisibility (CXCursor cursor)
| Describe the visibility of the entity referred to by a cursor. More...
CINDEX_LINKAGE enum CXAvailabilityKind | clang_getCursorAvailability (CXCursor cursor)
| Determine the availability of the entity that this cursor refers to, taking the current target platform into account. More...
CINDEX_LINKAGE int | clang_getCursorPlatformAvailability (CXCursor cursor, int *always_deprecated, CXString *deprecated_message, int *always_unavailable, CXString *unavailable_message, CXPlatformAvailability *availability, int availability_size)
| Determine the availability of the entity that this cursor refers to on any platforms for which availability information is known. More...
CINDEX_LINKAGE void | clang_disposeCXPlatformAvailability (CXPlatformAvailability *availability)
| Free the memory associated with a `CXPlatformAvailability` structure. More...
CINDEX_LINKAGE enum CXLanguageKind | clang_getCursorLanguage (CXCursor cursor)
| Determine the "language" of the entity referred to by a given cursor. More...
CINDEX_LINKAGE enum CXTLSKind | clang_getCursorTLSKind (CXCursor cursor)
| Determine the "thread-local storage (TLS) kind" of the declaration referred to by a cursor. More...
CINDEX_LINKAGE CXTranslationUnit | clang_Cursor_getTranslationUnit (CXCursor)
| Returns the translation unit that a cursor originated from. More...
CINDEX_LINKAGE CXCursorSet | clang_createCXCursorSet (void)
| Creates an empty CXCursorSet. More...
CINDEX_LINKAGE void | clang_disposeCXCursorSet (CXCursorSet cset)
| Disposes a CXCursorSet and releases its associated memory. More...
CINDEX_LINKAGE unsigned | clang_CXCursorSet_contains (CXCursorSet cset, CXCursor cursor)
| Queries a CXCursorSet to see if it contains a specific CXCursor. More...
CINDEX_LINKAGE unsigned | clang_CXCursorSet_insert (CXCursorSet cset, CXCursor cursor)
| Inserts a CXCursor into a CXCursorSet. More...
CINDEX_LINKAGE CXCursor | clang_getCursorSemanticParent (CXCursor cursor)
| Determine the semantic parent of the given cursor. More...
CINDEX_LINKAGE CXCursor | clang_getCursorLexicalParent (CXCursor cursor)
| Determine the lexical parent of the given cursor. More...
CINDEX_LINKAGE void | clang_getOverriddenCursors (CXCursor cursor, CXCursor **overridden, unsigned *num_overridden)
| Determine the set of methods that are overridden by the given method. More...
CINDEX_LINKAGE void | clang_disposeOverriddenCursors (CXCursor *overridden)
| Free the set of overridden cursors returned by `clang_getOverriddenCursors()`. More...
CINDEX_LINKAGE CXFile | clang_getIncludedFile (CXCursor cursor)
| Retrieve the file that is included by the given inclusion directive cursor. More...

## Detailed Description

## Typedef Documentation

## ◆ CXCursorSet

typedef struct CXCursorSetImpl* CXCursorSet

A fast container representing a set of CXCursors.

Definition at line 2992 of file Index.h.

## ◆ CXPlatformAvailability

typedef struct CXPlatformAvailability CXPlatformAvailability

Describes the availability of a given entity on a particular platform, e.g., a particular class might only be available on Mac OS 10.7 or newer.

## Enumeration Type Documentation

## ◆ CXLanguageKind

enum CXLanguageKind

Describe the "language" of the entity referred to by a cursor.

Enumerator
CXLanguage_Invalid |
CXLanguage_C |
CXLanguage_ObjC |
CXLanguage_CPlusPlus |

Definition at line 2956 of file Index.h.

## ◆ CXLinkageKind

enum CXLinkageKind

Describe the linkage of the entity referred to by a cursor.

Enumerator
CXLinkage_Invalid | This value indicates that no linkage information is available for a provided CXCursor.
CXLinkage_NoLinkage | This is the linkage for variables, parameters, and so on that have automatic storage. This covers normal (non-extern) local variables.
CXLinkage_Internal | This is the linkage for static variables and static functions.
CXLinkage_UniqueExternal | This is the linkage for entities with external linkage that live in C++ anonymous namespaces.
CXLinkage_External | This is the linkage for entities with true, external linkage.

Definition at line 2805 of file Index.h.

## ◆ CXTLSKind

enum CXTLSKind

Describe the "thread-local storage (TLS) kind" of the declaration referred to by a cursor.

Enumerator
CXTLS_None |
CXTLS_Dynamic |
CXTLS_Static |

Definition at line 2972 of file Index.h.

## ◆ CXVisibilityKind

enum CXVisibilityKind

Enumerator
CXVisibility_Invalid | This value indicates that no visibility information is available for a provided CXCursor.
CXVisibility_Hidden | Symbol not seen by the linker.
CXVisibility_Protected | Symbol seen by the linker but resolves to a symbol inside this object.
CXVisibility_Default | Symbol seen by the linker and acts like a normal symbol.

Definition at line 2828 of file Index.h.

## Function Documentation

## ◆ clang_createCXCursorSet()

CINDEX_LINKAGE CXCursorSet clang_createCXCursorSet | ( | void |  | ) |

Creates an empty CXCursorSet.

## ◆ clang_Cursor_getTranslationUnit()

CINDEX_LINKAGE CXTranslationUnit clang_Cursor_getTranslationUnit | ( | CXCursor |  | ) |

Returns the translation unit that a cursor originated from.

## ◆ clang_Cursor_hasAttrs()

CINDEX_LINKAGE unsigned clang_Cursor_hasAttrs | ( | CXCursor | C | ) |

Determine whether the given cursor has any attributes.

## ◆ clang_Cursor_isNull()

CINDEX_LINKAGE int clang_Cursor_isNull | ( | CXCursor | cursor | ) |

Returns non-zero if `cursor` is null.

## ◆ clang_CXCursorSet_contains()

CINDEX_LINKAGE unsigned clang_CXCursorSet_contains | ( | CXCursorSet | cset,
|  | CXCursor | cursor
| ) |  |

Queries a CXCursorSet to see if it contains a specific CXCursor.

Returns
  non-zero if the set contains the specified cursor.

## ◆ clang_CXCursorSet_insert()

CINDEX_LINKAGE unsigned clang_CXCursorSet_insert | ( | CXCursorSet | cset,
|  | CXCursor | cursor
| ) |  |

Inserts a CXCursor into a CXCursorSet.

Returns
  zero if the CXCursor was already in the set, and non-zero otherwise.

## ◆ clang_disposeCXCursorSet()

CINDEX_LINKAGE void clang_disposeCXCursorSet | ( | CXCursorSet | cset | ) |

Disposes a CXCursorSet and releases its associated memory.

## ◆ clang_disposeCXPlatformAvailability()

CINDEX_LINKAGE void clang_disposeCXPlatformAvailability | ( | CXPlatformAvailability * | availability | ) |

Free the memory associated with a `CXPlatformAvailability` structure.

## ◆ clang_disposeOverriddenCursors()

CINDEX_LINKAGE void clang_disposeOverriddenCursors | ( | CXCursor * | overridden | ) |

Free the set of overridden cursors returned by `clang_getOverriddenCursors()`.

## ◆ clang_equalCursors()

CINDEX_LINKAGE unsigned clang_equalCursors | ( | CXCursor | ,
|  | CXCursor |
| ) |  |

Determine whether two cursors are equivalent.

## ◆ clang_getCursorAvailability()

CINDEX_LINKAGE enum CXAvailabilityKind clang_getCursorAvailability | ( | CXCursor | cursor | ) |

Determine the availability of the entity that this cursor refers to, taking the current target platform into account.

Parameters

  cursor | The cursor to query.

Returns
  The availability of the cursor.

## ◆ clang_getCursorKind()

CINDEX_LINKAGE enum CXCursorKind clang_getCursorKind | ( | CXCursor |  | ) |

Retrieve the kind of the given cursor.

## ◆ clang_getCursorLanguage()

CINDEX_LINKAGE enum CXLanguageKind clang_getCursorLanguage | ( | CXCursor | cursor | ) |

Determine the "language" of the entity referred to by a given cursor.

## ◆ clang_getCursorLexicalParent()

CINDEX_LINKAGE CXCursor clang_getCursorLexicalParent | ( | CXCursor | cursor | ) |

Determine the lexical parent of the given cursor.

The lexical parent of a cursor is the cursor in which the given `cursor` was actually written. For many declarations, the lexical and semantic parents are equivalent (the semantic parent is returned by `clang_getCursorSemanticParent()`). They diverge when declarations or definitions are provided out-of-line. For example:

class C {
void f();
};
void C::f() { }

In the out-of-line definition of `C::f`, the semantic parent is the class `C`, of which this function is a member. The lexical parent is the place where the declaration actually occurs in the source code; in this case, the definition occurs in the translation unit. In general, the lexical parent for a given entity can change without affecting the semantics of the program, and the lexical parent of different declarations of the same entity may be different. Changing the semantic parent of a declaration, on the other hand, can have a major impact on semantics, and redeclarations of a particular entity should all have the same semantic context.

In the example above, both declarations of `C::f` have `C` as their semantic context, while the lexical context of the first `C::f` is `C` and the lexical context of the second `C::f` is the translation unit.

For declarations written in the global scope, the lexical parent is the translation unit.

## ◆ clang_getCursorLinkage()

CINDEX_LINKAGE enum CXLinkageKind clang_getCursorLinkage | ( | CXCursor | cursor | ) |

Determine the linkage of the entity referred to by a given cursor.

## ◆ clang_getCursorPlatformAvailability()

CINDEX_LINKAGE int clang_getCursorPlatformAvailability | ( | CXCursor | cursor,
|  | int * | always_deprecated,
|  | CXString * | deprecated_message,
|  | int * | always_unavailable,
|  | CXString * | unavailable_message,
|  | CXPlatformAvailability * | availability,
|  | int | availability_size
| ) |  |

Determine the availability of the entity that this cursor refers to on any platforms for which availability information is known.

Parameters

  cursor | The cursor to query.
  always_deprecated | If non-NULL, will be set to indicate whether the entity is deprecated on all platforms.
  deprecated_message | If non-NULL, will be set to the message text provided along with the unconditional deprecation of this entity. The client is responsible for deallocating this string.
  always_unavailable | If non-NULL, will be set to indicate whether the entity is unavailable on all platforms.
  unavailable_message | If non-NULL, will be set to the message text provided along with the unconditional unavailability of this entity. The client is responsible for deallocating this string.
  availability | If non-NULL, an array of CXPlatformAvailability instances that will be populated with platform availability information, up to either the number of platforms for which availability information is available (as returned by this function) or `availability_size`, whichever is smaller.
  availability_size | The number of elements available in the `availability` array.

Returns
  The number of platforms (N) for which availability information is available (which is unrelated to `availability_size`).

Note that the client is responsible for calling `clang_disposeCXPlatformAvailability` to free each of the platform-availability structures returned. There are `min(N, availability_size)` such structures.

## ◆ clang_getCursorSemanticParent()

CINDEX_LINKAGE CXCursor clang_getCursorSemanticParent | ( | CXCursor | cursor | ) |

Determine the semantic parent of the given cursor.

The semantic parent of a cursor is the cursor that semantically contains the given `cursor`. For many declarations, the lexical and semantic parents are equivalent (the lexical parent is returned by `clang_getCursorLexicalParent()`). They diverge when declarations or definitions are provided out-of-line. For example:

class C {
void f();
};
void C::f() { }

In the out-of-line definition of `C::f`, the semantic parent is the class `C`, of which this function is a member. The lexical parent is the place where the declaration actually occurs in the source code; in this case, the definition occurs in the translation unit. In general, the lexical parent for a given entity can change without affecting the semantics of the program, and the lexical parent of different declarations of the same entity may be different. Changing the semantic parent of a declaration, on the other hand, can have a major impact on semantics, and redeclarations of a particular entity should all have the same semantic context.

In the example above, both declarations of `C::f` have `C` as their semantic context, while the lexical context of the first `C::f` is `C` and the lexical context of the second `C::f` is the translation unit.

For global declarations, the semantic parent is the translation unit.

## ◆ clang_getCursorTLSKind()

CINDEX_LINKAGE enum CXTLSKind clang_getCursorTLSKind | ( | CXCursor | cursor | ) |

Determine the "thread-local storage (TLS) kind" of the declaration referred to by a cursor.

## ◆ clang_getCursorVisibility()

CINDEX_LINKAGE enum CXVisibilityKind clang_getCursorVisibility | ( | CXCursor | cursor | ) |

Describe the visibility of the entity referred to by a cursor.

This returns the default visibility if not explicitly specified by a visibility attribute. The default visibility may be changed by commandline arguments.

Parameters

  cursor | The cursor to query.

Returns
  The visibility of the cursor.

## ◆ clang_getIncludedFile()

CINDEX_LINKAGE CXFile clang_getIncludedFile | ( | CXCursor | cursor | ) |

Retrieve the file that is included by the given inclusion directive cursor.

## ◆ clang_getNullCursor()

CINDEX_LINKAGE CXCursor clang_getNullCursor | ( | void |  | ) |

Retrieve the NULL cursor, which represents no entity.

## ◆ clang_getOverriddenCursors()

CINDEX_LINKAGE void clang_getOverriddenCursors | ( | CXCursor | cursor,
|  | CXCursor ** | overridden,
|  | unsigned * | num_overridden
| ) |  |

Determine the set of methods that are overridden by the given method.

In both Objective-C and C++, a method (aka virtual member function, in C++) can override a virtual method in a base class. For Objective-C, a method is said to override any method in the class's base class, its protocols, or its categories' protocols, that has the same selector and is of the same kind (class or instance). If no such method exists, the search continues to the class's superclass, its protocols, and its categories, and so on. A method from an Objective-C implementation is considered to override the same methods as its corresponding method in the interface.

For C++, a virtual member function overrides any virtual member function with the same signature that occurs in its base classes. With multiple inheritance, a virtual member function can override several virtual member functions coming from different base classes.

In all cases, this function determines the immediate overridden method, rather than all of the overridden methods. For example, if a method is originally declared in a class A, then overridden in B (which in inherits from A) and also in C (which inherited from B), then the only overridden method returned from this function when invoked on C's method will be B's method. The client may then invoke this function again, given the previously-found overridden methods, to map out the complete method-override set.

Parameters

  cursor | A cursor representing an Objective-C or C++ method. This routine will compute the set of methods that this method overrides.
  overridden | A pointer whose pointee will be replaced with a pointer to an array of cursors, representing the set of overridden methods. If there are no overridden methods, the pointee will be set to NULL. The pointee must be freed via a call to `clang_disposeOverriddenCursors()`.
  num_overridden | A pointer to the number of overridden functions, will be set to the number of overridden functions in the array pointed to by `overridden`.

## ◆ clang_getTranslationUnitCursor()

CINDEX_LINKAGE CXCursor clang_getTranslationUnitCursor | ( | CXTranslationUnit |  | ) |

Retrieve the cursor that represents the given translation unit.

The translation unit cursor can be used to start traversing the various declarations within the given translation unit.

## ◆ clang_hashCursor()

CINDEX_LINKAGE unsigned clang_hashCursor | ( | CXCursor |  | ) |

Compute a hash value for the given cursor.

## ◆ clang_isAttribute()

CINDEX_LINKAGE unsigned clang_isAttribute | ( | enum | CXCursorKind | ) |

Determine whether the given cursor kind represents an attribute.

## ◆ clang_isDeclaration()

CINDEX_LINKAGE unsigned clang_isDeclaration | ( | enum | CXCursorKind | ) |

Determine whether the given cursor kind represents a declaration.

## ◆ clang_isExpression()

CINDEX_LINKAGE unsigned clang_isExpression | ( | enum | CXCursorKind | ) |

Determine whether the given cursor kind represents an expression.

## ◆ clang_isInvalid()

CINDEX_LINKAGE unsigned clang_isInvalid | ( | enum | CXCursorKind | ) |

Determine whether the given cursor kind represents an invalid cursor.

## ◆ clang_isInvalidDeclaration()

CINDEX_LINKAGE unsigned clang_isInvalidDeclaration | ( | CXCursor |  | ) |

Determine whether the given declaration is invalid.

A declaration is invalid if it could not be parsed successfully.

Returns
  non-zero if the cursor represents a declaration and it is invalid, otherwise NULL.

## ◆ clang_isPreprocessing()

CINDEX_LINKAGE unsigned clang_isPreprocessing | ( | enum | CXCursorKind | ) |

## ◆ clang_isReference()

CINDEX_LINKAGE unsigned clang_isReference | ( | enum | CXCursorKind | ) |

Determine whether the given cursor kind represents a simple reference.

Note that other kinds of cursors (such as expressions) can also refer to other cursors. Use clang_getCursorReferenced() to determine whether a particular cursor refers to another entity.

## ◆ clang_isStatement()

CINDEX_LINKAGE unsigned clang_isStatement | ( | enum | CXCursorKind | ) |

Determine whether the given cursor kind represents a statement.

## ◆ clang_isTranslationUnit()

CINDEX_LINKAGE unsigned clang_isTranslationUnit | ( | enum | CXCursorKind | ) |

Determine whether the given cursor kind represents a translation unit.

## ◆ clang_isUnexposed()

CINDEX_LINKAGE unsigned clang_isUnexposed | ( | enum | CXCursorKind | ) |