diff --git a/lldb/bindings/interface/SBType.i b/lldb/bindings/interface/SBType.i --- a/lldb/bindings/interface/SBType.i +++ b/lldb/bindings/interface/SBType.i @@ -111,8 +111,24 @@ }; %feature("docstring", -"Represents a data type in lldb. The FindFirstType() method of SBTarget/SBModule -returns a SBType. +"Represents a data type in lldb. + +The actual characteristics of each type are defined by the semantics of the +programming language and the specific language implementation that was used +to compile the target program. See the language-specific notes in the +documentation of each method. + +SBType instances can be obtained by a variety of methods. +`SBTarget.FindFirstType` and `SBModule.FindFirstType` can be used to create +`SBType` representations of types in executables/libraries with debug +information. For some languages such as C, C++ and Objective-C it is possible +to create new types by evaluating expressions that define a new type. + +Note that most `SBType` properties are computed independently of any runtime +information so for dynamic languages the functionality can be very limited. +`SBValue` can be used to represent runtime values which then can be more +accurately queried for certain information such as byte size. + SBType supports the eq/ne operator. For example,:: @@ -181,7 +197,7 @@ # id_type and int_type should be the same type! self.assertTrue(id_type == int_type) -...") SBType; +") SBType; class SBType { public: @@ -196,132 +212,649 @@ explicit operator bool() const; + + %feature("docstring", + "Returns the number of bytes a variable with the given types occupies in memory. + + Returns ``0`` if the size can't be determined. + + If a type occupies ``N`` bytes + ``M`` bits in memory, this function returns + the rounded up amount of bytes (i.e., if ``M`` is ``0``, + this function returns ``N`` and otherwise ``N + 1``). + + Language-specific behaviour: + + * C: The output is expected to match the value of ``sizeof(Type)``. If + ``sizeof(Type)`` is not a valid expression for the given type, the + function returns ``0``. + * C++: Same as in C. + * Objective-C: Same as in C. For Objective-C classes this always returns + `0`` as the actual size depends on runtime information. + ") GetByteSize; uint64_t GetByteSize(); + + %feature("docstring", + "Returns true if this type is a pointer type. + + Language-specific behaviour: + + * C: Returns true for C pointer types (or typedefs of these types). + * C++: Pointer types include the C pointer types as well as pointers to data + mebers or member functions. + * Objective-C: Pointer types include the C pointer types. ``id``, ``Class`` + and pointers to blocks are also considered pointer types. + ") IsPointerType; bool IsPointerType(); + %feature("docstring", + "Returns true if this type is a reference type. + + Language-specific behaviour: + + * C: Returns false for all types. + * C++: Both l-value and r-value references are considered reference types. + * Objective-C: Returns false for all types. + ") IsReferenceType; bool IsReferenceType(); + %feature("docstring", + "Returns true if this type is a function type. + + Language-specific behaviour: + + * C: Returns true for types that represent functions. Note that function + pointers are not function types (but their `GetPointeeType()` are function + types). + * C++: Same as in C. + * Objective-C: Returns false for all types. + ") IsPolymorphicClass; bool IsFunctionType (); + %feature("docstring", + "Returns true if this type is a polymorphic type. + + Language-specific behaviour: + + * C: Returns false for all types. + * C++: Returns true if the type is a class type that contains at least one + virtual member function or if at least one of its base classes is + considered a polymorphic type. + * Objective-C: Returns false for all types. + ") IsPolymorphicClass; bool IsPolymorphicClass (); + %feature("docstring", + "Returns true if this type is an array type. + + Language-specific behaviour: + + * C: Returns true if the types is an array type. This includes incomplete + array types ``T[]`` and array types with integer (``T[1]``) or variable + length (``T[some_variable]``). Pointer types are not considered arrays. + * C++: Includes C's array types and dependent array types (i.e., array types + in templates which size depends on template arguments). + * Objective-C: Same as in C. + ") IsArrayType; bool IsArrayType (); + %feature("docstring", + "Returns true if this type is a vector type. + + Language-specific behaviour: + + * C: Returns true if the types is a vector type created with + GCC's ``vector_size`` or Clang's ``ext_vector_type`` feature. + * C++: Same as in C. + * Objective-C: Same as in C. + ") IsVectorType; bool IsVectorType (); + %feature("docstring", + "Returns true if this type is a typedef. + + Language-specific behaviour: + + * C: Returns true if the type is a C typedef. + * C++: Same as in C. Also treats type aliases as typedefs. + * Objective-C: Same as in C. + ") IsTypedefType; bool IsTypedefType (); + %feature("docstring", + "Returns true if this type is an anonymous type. + + Language-specific behaviour: + + * C: Returns true for anonymous unions. Also returns true for + anonymous structs (which are a GNU language extension). + * C++: Same as in C. + * Objective-C: Same as in C. + ") IsAnonymousType; bool IsAnonymousType (); + %feature("docstring", + "Returns true if this type is a scoped enum. + + Language-specific behaviour: + + * C: Returns false for all types. + * C++: Return true only for C++11 scoped enums. + * Objective-C: Returns false for all types. + ") IsScopedEnumerationType; bool IsScopedEnumerationType (); + %feature("docstring", + "Returns a type that represents a pointer to this type. + + If the type system of the current language can't represent a pointer to this + type or this type is invalid, an invalid `SBType` is returned. + + Language-specific behaviour: + + * C: Returns the pointer type of this type. + * C++: Same as in C. + * Objective-C: Same as in C. + ") GetPointerType; lldb::SBType GetPointerType(); + %feature("docstring", + "Returns the underlying pointee type. + + If this type is a pointer type as specified by `IsPointerType` then this + returns the underlying type. If this is not a pointer type or an invalid + `SBType` then this returns an invalid `SBType`. + + Language-specific behaviour: + + * C: Returns the underlying type for for C pointer types or typedefs of + these types). For example, ``int *`` will return ``int``. + * C++: Same as in C. Returns an `SBType` representation for data members/ + member functions in case the `SBType` is a pointer to data member or + pointer to member function. + * Objective-C: Same as in C. The pointee type of ``id`` and ``Class`` is + an invalid `SBType`. The pointee type of pointers Objective-C types is an + `SBType` for the non-pointer type of the respective type. For example, + ``NSString *`` will return ``NSString`` as a pointee type. + ") GetPointeeType; lldb::SBType GetPointeeType(); + %feature("docstring", + "Returns a type that represents a reference to this type. + + If the type system of the current language can't represent a reference to + this type, an invalid `SBType` is returned. + + Language-specific behaviour: + + * C: Currently assumes the type system is C++ and returns an l-value + reference type. For example, ``int`` will return ``int&``. This behavior + is likely to change in the future and shouldn't be relied on. + * C++: Same as in C. + * Objective-C: Same as in C. + ") GetReferenceType; lldb::SBType GetReferenceType(); + %feature("docstring", + "Returns the underlying type of a typedef. + + If this type is a typedef as designated by `IsTypedefType`, then the + underlying type is being returned. Otherwise an invalid `SBType` is + returned. + + Language-specific behaviour: + + * C: Returns the underlying type of a typedef type. + * C++: Same as in C. For type aliases, the underlying type is returned. + * Objective-C: Same as in C. + ") GetTypedefedType; lldb::SBType SBType::GetTypedefedType(); + %feature("docstring", + "Returns the underlying type of a reference type. + + If this type is a reference as designated by `IsReferenceType`, then the + underlying type is being returned. Otherwise an invalid `SBType` is + returned. + + Language-specific behaviour: + + * C: Always returns an invalid type. + * C++: For l-value and r-value references the underlying type is returned. + For example, ``int &`` will return ``int``. + * Objective-C: Same as in C. + ") GetDereferencedType; lldb::SBType GetDereferencedType(); + %feature("docstring", + "Returns the unqualified version of this type. + + Language-specific behaviour: + + * C: If this type with any const or volatile specifier removed. + * C++: Same as in C. + * Objective-C: Same as in C. + ") GetUnqualifiedType; lldb::SBType GetUnqualifiedType(); lldb::SBType GetCanonicalType(); + %feature("docstring", + "Returns the underlying integer type if this is an enumeration type. + + If this type is an invalid `SBType` or not an enumeration type an invalid + `SBType` is returned. + + Language-specific behaviour: + + * C: Returns the underlying type for enums. + * C++: Same as in C but also returns the underlying type for scoped enums. + * Objective-C: Same as in C. + ") GetEnumerationIntegerType; lldb::SBType GetEnumerationIntegerType(); + %feature("docstring", + "Returns the array element type if this type is an array type. + + Otherwise returns an invalid `SBType` if this type is invalid or not an + array type. + + Language-specific behaviour: + + * C: If this is an array type (see `IsArrayType`) such as ``T[]``, returns + the element type. + * C++: Same as in C. + * Objective-C: Same as in C. + + See also `IsArrayType`. + ") GetArrayElementType; lldb::SBType GetArrayElementType (); + %feature("docstring", + "Returns the array type with the given constant size. + + Language-specific behaviour: + + * C: Returns a constant-size array `T[size]` for any non-void type. + * C++: Same as in C. + * Objective-C: Same as in C. + + See also `IsArrayType` and `GetArrayElementType`. + ") GetArrayType; lldb::SBType GetArrayType (uint64_t size); + %feature("docstring", + "Returns the vector element type if this type is a vector type. + + Otherwise returns an invalid `SBType` if this type is invalid or not a + vector type. + + Language-specific behaviour: + + * C: If this is a vector type (see `IsVectorType`), returns the element + type. + * C++: Same as in C. + * Objective-C: Same as in C. + + See also `IsVectorType`. + ") GetVectorElementType; lldb::SBType GetVectorElementType (); + %feature("docstring", + "Returns the `BasicType` value that is most appropriate to this type. + + Returns `eBasicTypeInvalid` if no appropriate `BasicType` was found or this + type is invalid. See the `BasicType` documentation for the language-specific m + aning of each `BasicType` value. + + **Overload behaviour:** When called with a `BasicType` parameter, the + following behaviour applies: + + Returns the `SBType` that represents the passed `BasicType` value. Returns + an invalid `SBType` if no fitting `SBType` could be created. + + Language-specific behaviour: + + * C: Returns the respective builtin type. Note that some types + (e.g. ``__uint128_t``) might even be successfully created even if they are + not available on the target platform. C++ and Objective-C specific types + might also be created even if the target program is not written in C++ or + Objective-C. + * C++: Same as in C. + * Objective-C: Same as in C. + "); lldb::BasicType GetBasicType(); lldb::SBType GetBasicType (lldb::BasicType type); + %feature("docstring", + "Returns the number of fields of this type. + + Returns ``0`` if this type does not have fields. + + Language-specific behaviour: + + * C: Returns the number of fields if the type is a struct. If the type + contains an anonymous struct/union it only counts as a single field (even + if the struct/union contains several fields). + * C++: Returns the number of non-static fields if the type is a + struct/class. If the type contains an anonymous struct/union it only + counts as a single field (even if the struct/union contains several + fields). The fields of any base classes are not included in the count. + * Objective-C: Same as in C for structs. For Objective-C classes the number + of ivars is returned. + + See also `GetFieldAtIndex`. + ") GetNumberOfFields; uint32_t GetNumberOfFields (); + %feature("docstring", + "Returns the number of base/parent classes of this type. + + Returns ``0`` if this type doesn't have any base classes. + + Language-specific behaviour: + + * C: Returns always ``0``. + * C++: The number of direct non-virtual base classes if this type is + a class. + * Objective-C: The number of super classes for Objective-C classes. + As Objective-C doesn't have multiple inheritance this is usually returns 1 + except for NSObject. + ") GetNumberOfDirectBaseClasses; uint32_t GetNumberOfDirectBaseClasses (); + %feature("docstring", + "Returns the number of virtual base/parent classes of this type + + Returns ``0`` if this type doesn't have any base classes. + + Language-specific behaviour: + + * C: Returns always ``0``. + * C++: The number of direct virtual base classes if this type is a + class. + * Objective-C: Returns always ``0``. + ") GetNumberOfVirtualBaseClasses; uint32_t GetNumberOfVirtualBaseClasses (); + %feature("docstring", + "Returns the field at the given index. + + Returns an invalid `SBType` if the index is out of range or the current + type doesn't have any fields. + + Language-specific behaviour: + + * C: Returns the field with the given index for struct types. Fields are + ordered/indexed starting from ``0`` for the first field in a struct (as + declared in the definition). + * C++: Returns the non-static field with the given index for struct types. + Fields are ordered/indexed starting from ``0`` for the first field in a + struct (as declared in the definition). + * Objective-C: Same as in C for structs. For Objective-C classes the ivar + with the given index is returned. ivars are indexed starting from ``0``. + ") GetFieldAtIndex; lldb::SBTypeMember GetFieldAtIndex (uint32_t idx); + %feature("docstring", + "Returns the direct base class as indexed by `GetNumberOfDirectBaseClasses`. + + Returns an invalid SBTypeMember if the index is invalid or this SBType is + invalid. + ") GetDirectBaseClassAtIndex; lldb::SBTypeMember GetDirectBaseClassAtIndex (uint32_t idx); + %feature("docstring", + "Returns the virtual base class as indexed by + `GetNumberOfVirtualBaseClasses`. + + Returns an invalid SBTypeMember if the index is invalid or this SBType is + invalid. + ") GetVirtualBaseClassAtIndex; lldb::SBTypeMember GetVirtualBaseClassAtIndex (uint32_t idx); lldb::SBTypeEnumMemberList GetEnumMembers(); + %feature("docstring", + "Returns the `SBModule` this `SBType` belongs to. + Returns no `SBModule` if this type does not belong to any specific + `SBModule` or this `SBType` is invalid. An invalid `SBModule` might also + indicate that once came from an `SBModule` but LLDB could no longer + determine the original module. + ") GetModule; lldb::SBModule GetModule(); + %feature("autodoc", "GetName() -> string") GetName; + %feature("docstring", + "Returns the name of this type. + + Returns an empty string if an error occurred or this type is invalid. + + Use this function when trying to match a specific type by name in a script. + The names returned by this function try to uniquely identify a name but + conflicts can occur (for example, if a C++ program contains two different + classes with the same name in different translation units. `GetName` can + return the same name for both class types.) + + + Language-specific behaviour: + + * C: The name of the type. For structs the ``struct`` prefix is omitted. + * C++: Returns the qualified name of the type (including anonymous/inline + namespaces and all template arguments). + * Objective-C: Same as in C. + ") GetName; const char* GetName(); + %feature("autodoc", "GetDisplayTypeName() -> string") GetDisplayTypeName; + %feature("docstring", + "Returns the name of this type in a user-friendly format. + + Returns an empty string if an error occurred or this type is invalid. + + Use this function when displaying a type name to the user. + + Language-specific behaviour: + + * C: Returns the type name. For structs the ``struct`` prefix is omitted. + * C++: Returns the qualified name. Anonymous/inline namespaces are omitted. + Template arguments that match their default value might also be hidden + (this functionality depends on whether LLDB can determine the template's + default arguments). + * Objective-C: Same as in C. + ") GetDisplayTypeName; const char * GetDisplayTypeName (); + %feature("autodoc", "GetTypeClass() -> TypeClass") GetTypeClass; + %feature("docstring", + "Returns the `TypeClass` for this type. + + Returns an `eTypeClassInvalid` if this `SBType` is invalid. + + See `TypeClass` for the language-specific meaning of each `TypeClass` value. + ") GetTypeClass; lldb::TypeClass GetTypeClass (); + %feature("docstring", + "Returns the number of template arguments of this type. + + Returns ``0`` if this type is not a template. + + Language-specific behaviour: + + * C: Always returns ``0``. + * C++: If this type is a class template instantiation then this returns the + number of template parameters that were used in this instantiation. This i + cludes both explicit and implicit template parameters. + * Objective-C: Always returns ``0``. + ") GetNumberOfTemplateArguments; uint32_t GetNumberOfTemplateArguments (); + %feature("docstring", + "Returns the type of the template argument with the given index. + + Returns an invalid `SBType` if there is no template argument with the given + index or this type is not a template. The first template argument has the + index ``0``. + + Language-specific behaviour: + + * C: Always returns an invalid SBType. + * C++: If this type is a class template instantiation and the template + parameter with the given index is a type template parameter, then this + returns the type of that parameter. Otherwise returns an invalid `SBType`. + * Objective-C: Always returns an invalid SBType. + ") GetTemplateArgumentType; lldb::SBType GetTemplateArgumentType (uint32_t idx); + %feature("docstring", + "Returns the kind of the template argument with the given index. + + Returns `eTemplateArgumentKindNull` if there is no template argument + with the given index or this type is not a template. The first template + argument has the index ``0``. + + Language-specific behaviour: + + * C: Always returns `eTemplateArgumentKindNull`. + * C++: If this type is a class template instantiation then this returns + the appropriate `TemplateArgument` value for the parameter with the given + index. See the documentation of `TemplateArgument` for how certain C++ + template parameter kinds are mapped to `TemplateArgument` values. + * Objective-C: Always returns `eTemplateArgumentKindNull`. + ") GetTemplateArgumentKind; lldb::TemplateArgumentKind GetTemplateArgumentKind (uint32_t idx); + %feature("docstring", + "Returns the return type if this type represents a function. + + Returns an invalid `SBType` if this type is not a function type or invalid. + + Language-specific behaviour: + + * C: For functions return the return type. Returns an invalid `SBType` if + this type is a function pointer type. + * C++: Same as in C for functions and instantiated template functions. + Member functions are also considered functions. For functions that have + their return type specified by a placeholder type specifier (``auto``) + this returns the deduced return type. + * Objective-C: Same as in C for functions. For Objective-C methods this + returns the return type of the method. + ") GetFunctionReturnType; lldb::SBType GetFunctionReturnType (); + %feature("docstring", + "Returns the list of argument types if this type represents a function. + + Returns an invalid `SBType` if this type is not a function type or invalid. + + Language-specific behaviour: + + * C: For functions return the types of each parameter. Returns an invalid + `SBType` if this type is a function pointer. For variadic functions this + just returns the list of parameters before the variadic arguments. + * C++: Same as in C for functions and instantiated template functions. + Member functions are also considered functions. + * Objective-C: Always returns an invalid SBType for Objective-C methods. + ") GetFunctionArgumentTypes; lldb::SBTypeList GetFunctionArgumentTypes (); + %feature("docstring", + "Returns the number of member functions of this type. + + Returns ``0`` if an error occurred or this type is invalid. + + Language-specific behaviour: + + * C: Always returns ``0``. + * C++: If this type represents a struct/class, then the number of + member functions (static and non-static) is returned. The count includes + constructors and destructors (both explicit and implicit). Member + functions of base classes are not included in the count. + * Objective-C: If this type represents a struct/class, then the + number of methods is returned. Methods in categories or super classes + are not counted. + ") GetNumberOfMemberFunctions; uint32_t GetNumberOfMemberFunctions (); + %feature("docstring", + "Returns the member function of this type with the given index. + + Returns an invalid `SBTypeMemberFunction` if the index is invalid or this + type is invalid. + + Language-specific behaviour: + + * C: Always returns an invalid `SBTypeMemberFunction`. + * C++: Returns the member function or constructor/destructor with the given + index. + * Objective-C: Returns the method with the given index. + + See `GetNumberOfMemberFunctions` for what functions can be queried by this + function. + ") GetMemberFunctionAtIndex; lldb::SBTypeMemberFunction GetMemberFunctionAtIndex (uint32_t idx); bool IsTypeComplete (); + %feature("docstring", + "Returns the `TypeFlags` values for this type. + + See the respective `TypeFlags` values for what values can be set. Returns an + integer in which each `TypeFlags` value is represented by a bit. Specific + flags can be checked via Python's bitwise operators. For example, the + `eTypeIsInteger` flag can be checked like this: + + ``(an_sb_type.GetTypeFlags() & lldb.eTypeIsInteger) != 0`` + + If this type is invalid this returns ``0``. + + See the different values for `TypeFlags` for the language-specific meanings + of each `TypeFlags` value. + ") GetTypeFlags; uint32_t GetTypeFlags ();