Package ghidra.program.model.data

# Interface Composite

All Superinterfaces:
  `DataType`

All Known Subinterfaces:
  `CompositeInternal`, `Structure`, `StructureInternal`, `Union`, `UnionInternal`

All Known Implementing Classes:
  `CompositeDataTypeImpl`, `StructureDataType`, `UnionDataType`

public interface Composite extends DataType
Interface for common methods in Structure and Union

- ## Field Summary

  ### Fields inherited from interface ghidra.program.model.data.DataType

  `CONFLICT_SUFFIX, DEFAULT, NO_LAST_CHANGE_TIME, NO_SOURCE_SYNC_TIME, TYPEDEF_ATTRIBUTE_PREFIX, TYPEDEF_ATTRIBUTE_SUFFIX, VOID`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `DataTypeComponent`
  `add(DataType dataType)`
  Adds a new datatype to the end of this composite.
  `DataTypeComponent`
  `add(DataType dataType, int length)`
  Adds a new datatype to the end of this composite.
  `DataTypeComponent`
  `add(DataType dataType, int length, String name, String comment)`
  Adds a new datatype to the end of this composite.
  `DataTypeComponent`
  `add(DataType dataType, String name, String comment)`
  Adds a new datatype to the end of this composite.
  `DataTypeComponent`
  `addBitField(DataType baseDataType, int bitSize, String componentName, String comment)`
  Adds a new bitfield to the end of this composite.
  `default void`
  `align(int minAlignment)`
  Same as `setExplicitMinimumAlignment(int)`.
  `void`
  `dataTypeAlignmentChanged(DataType dt)`
  The alignment changed for the specified data type.
  `void`
  `delete(int ordinal)`
  Deletes the component at the given ordinal position.
  `void`
  `delete(Set<Integer> ordinals)`
  Deletes the specified set of components at the given ordinal positions.
  `int`
  `getAlignment()`
  Get the computed alignment for this composite based upon packing and minimum alignment settings as well as component alignment.
  `AlignmentType`
  `getAlignmentType()`
  `DataTypeComponent`
  `getComponent(int ordinal)`
  Returns the component of this data type with the indicated ordinal.
  `DataTypeComponent[]`
  `getComponents()`
  Returns an array of Data Type Components that make up this composite including undefined filler components which may be present within a Structure which has packing disabled.
  `DataTypeComponent[]`
  `getDefinedComponents()`
  Returns an array of Data Type Components that make up this composite excluding undefined filler components which may be present within Structures where packing is disabled.
  `int`
  `getExplicitMinimumAlignment()`
  Get the explicit minimum alignment setting for this Composite which contributes to the actual computed alignment value (see `getAlignment()`.
  `int`
  `getExplicitPackingValue()`
  Gets the current packing value (typically a power of 2).
  `int`
  `getNumComponents()`
  Gets the number of component data types in this composite.
  `int`
  `getNumDefinedComponents()`
  Returns the number of explicitly defined components in this composite.
  `PackingType`
  `getPackingType()`
  `default boolean`
  `hasDefaultPacking()`
  Determine if default packing is enabled.
  `default boolean`
  `hasExplicitMinimumAlignment()`
  Determine if an explicit minimum alignment has been set (see `getExplicitMinimumAlignment()`).
  `default boolean`
  `hasExplicitPackingValue()`
  Determine if packing is enabled with an explicit packing value (see `getExplicitPackingValue()`).
  `DataTypeComponent`
  `insert(int ordinal, DataType dataType)`
  Inserts a new datatype at the specified ordinal position in this composite.
  `DataTypeComponent`
  `insert(int ordinal, DataType dataType, int length)`
  Inserts a new datatype at the specified ordinal position in this composite.
  `DataTypeComponent`
  `insert(int ordinal, DataType dataType, int length, String name, String comment)`
  Inserts a new datatype at the specified ordinal position in this composite.
  `default boolean`
  `isDefaultAligned()`
  Whether or not this data type is using the default alignment.
  `default boolean`
  `isMachineAligned()`
  Whether or not this data type is using the machine alignment value, specified by `DataOrganization.getMachineAlignment()`, for its alignment.
  `default boolean`
  `isPackingEnabled()`
  Determine if this data type has its internal components currently packed based upon alignment and packing settings.
  `boolean`
  `isPartOf(DataType dataType)`
  Check if a data type is part of this data type.
  `default void`
  `pack(int packingValue)`
  Same as `setExplicitPackingValue(int)`.
  `void`
  `repack()`
  Updates packed composite to any changes in the data organization.
  `void`
  `setDescription(String desc)`
  Sets the string describing this data type.
  `void`
  `setExplicitMinimumAlignment(int minAlignment)`
  Sets this data type's explicit minimum alignment (positive value).
  `void`
  `setExplicitPackingValue(int packingValue)`
  Sets the pack value for this composite (positive value, usually a power of 2).
  `void`
  `setPackingEnabled(boolean enabled)`
  Sets whether this data type's internal components are currently packed.
  `void`
  `setToDefaultAligned()`
  Sets this data type's alignment to its default alignment.
  `void`
  `setToDefaultPacking()`
  Enables default packing behavior.
  `void`
  `setToMachineAligned()`
  Sets this data type's minimum alignment to the machine alignment which is specified by `DataOrganization.getMachineAlignment()`.

  ### Methods inherited from interface ghidra.program.model.data.DataType

  `addParent, clone, copy, dataTypeDeleted, dataTypeNameChanged, dataTypeReplaced, dataTypeSizeChanged, dependsOn, encodeRepresentation, encodeValue, getAlignedLength, getCategoryPath, getDataOrganization, getDataTypeManager, getDataTypePath, getDefaultAbbreviatedLabelPrefix, getDefaultLabelPrefix, getDefaultLabelPrefix, getDefaultOffcutLabelPrefix, getDefaultSettings, getDescription, getDisplayName, getDocs, getLastChangeTime, getLastChangeTimeInSourceArchive, getLength, getMnemonic, getName, getParents, getPathName, getRepresentation, getSettingsDefinitions, getSourceArchive, getTypeDefSettingsDefinitions, getUniversalID, getValue, getValueClass, hasLanguageDependantLength, isDeleted, isEncodable, isEquivalent, isNotYetDefined, isZeroLength, removeParent, replaceWith, setCategoryPath, setLastChangeTime, setLastChangeTimeInSourceArchive, setName, setNameAndCategory, setSourceArchive`

- ## Method Details

  - ### setDescription

    void setDescription(String desc)
    Sets the string describing this data type.
    Specified by:
      `setDescription` in interface `DataType`
    Parameters:
      `desc` - the new description.

  - ### getNumComponents

    int getNumComponents()
    Gets the number of component data types in this composite. If this is Structure with packing disabled, the count will include all undefined filler components which may be present.
    Returns:
      the number of components that make up this composite

  - ### getNumDefinedComponents

    int getNumDefinedComponents()
    Returns the number of explicitly defined components in this composite. For Unions and packed Structures this is equivalent to `getNumComponents()` since they do not contain undefined components. This count will always exclude all undefined filler components which may be present within a Structure whose packing is disabled (see `isPackingEnabled()`).
    Returns:
      the number of explicitly defined components in this composite

  - ### getComponent

    DataTypeComponent getComponent(int ordinal) throws IndexOutOfBoundsException
    Returns the component of this data type with the indicated ordinal.
    Parameters:
      `ordinal` - the component's ordinal (zero based).
    Returns:
      the data type component.
    Throws:
      `IndexOutOfBoundsException` - if the ordinal is out of bounds

  - ### getComponents

    DataTypeComponent[] getComponents()
    Returns an array of Data Type Components that make up this composite including undefined filler components which may be present within a Structure which has packing disabled. The number of components corresponds to `getNumComponents()`.
    Returns:
      array all components

  - ### getDefinedComponents

    DataTypeComponent[] getDefinedComponents()
    Returns an array of Data Type Components that make up this composite excluding undefined filler components which may be present within Structures where packing is disabled. The number of components corresponds to `getNumDefinedComponents()`. For Unions and packed Structures this is equivalent to `getComponents()` since they do not contain undefined filler components.
    Returns:
      array all explicitly defined components

  - ### add

    DataTypeComponent add(DataType dataType) throws IllegalArgumentException
    Adds a new datatype to the end of this composite. This is the preferred method to use for adding components to an aligned structure for fixed-length dataTypes.
    Parameters:
      `dataType` - the datatype to add.
    Returns:
      the DataTypeComponent created.
    Throws:
      `IllegalArgumentException` - if the specified data type is not allowed to be added to this composite data type. For example, suppose dt1 contains dt2. Therefore it is not valid to add dt1 to dt2 since this would cause a cyclic dependency.

  - ### add

    DataTypeComponent add(DataType dataType, int length) throws IllegalArgumentException
    Adds a new datatype to the end of this composite. This is the preferred method to use for adding components to an aligned structure for dynamic dataTypes such as strings whose length must be specified.
    Parameters:
      `dataType` - the datatype to add.
      `length` - the length to associate with the datatype. For fixed length types a length <= 0 will use the length of the resolved dataType.
    Returns:
      the componentDataType created.
    Throws:
      `IllegalArgumentException` - if the specified data type is not allowed to be added to this composite data type or an invalid length is specified. For example, suppose dt1 contains dt2. Therefore it is not valid to add dt1 to dt2 since this would cause a cyclic dependency.

  - ### add

    DataTypeComponent add(DataType dataType, String name, String comment) throws IllegalArgumentException
    Adds a new datatype to the end of this composite. This is the preferred method to use for adding components to an aligned structure for fixed-length dataTypes.
    Parameters:
      `dataType` - the datatype to add.
      `name` - the field name to associate with this component.
      `comment` - the comment to associate with this component.
    Returns:
      the componentDataType created.
    Throws:
      `IllegalArgumentException` - if the specified data type is not allowed to be added to this composite data type. For example, suppose dt1 contains dt2. Therefore it is not valid to add dt1 to dt2 since this would cause a cyclic dependency.

  - ### addBitField

    DataTypeComponent addBitField(DataType baseDataType, int bitSize, String componentName, String comment) throws InvalidDataTypeException
    Adds a new bitfield to the end of this composite. This method is intended to be used with packed structures/unions only where the bitfield will be appropriately packed. The minimum storage storage byte size will be applied. It will not provide useful results for composites with packing disabled.
    Parameters:
      `baseDataType` - the bitfield base datatype (certain restrictions apply).
      `bitSize` - the bitfield size in bits
      `componentName` - the field name to associate with this component.
      `comment` - the comment to associate with this component.
    Returns:
      the componentDataType created whose associated data type will be BitFieldDataType.
    Throws:
      `InvalidDataTypeException` - if the specified data type is not a valid base type for bitfields.

  - ### add

    DataTypeComponent add(DataType dataType, int length, String name, String comment) throws IllegalArgumentException
    Adds a new datatype to the end of this composite. This is the preferred method to use for adding components to an aligned structure for dynamic dataTypes such as strings whose length must be specified.
    Parameters:
      `dataType` - the datatype to add.
      `length` - the length to associate with the datatype. For fixed length types a length <= 0 will use the length of the resolved dataType.
      `name` - the field name to associate with this component.
      `comment` - the comment to associate with this component.
    Returns:
      the componentDataType created.
    Throws:
      `IllegalArgumentException` - if the specified data type is not allowed to be added to this composite data type or an invalid length is specified. For example, suppose dt1 contains dt2. Therefore it is not valid to add dt1 to dt2 since this would cause a cyclic dependency.

  - ### insert

    DataTypeComponent insert(int ordinal, DataType dataType) throws IndexOutOfBoundsException, IllegalArgumentException
    Inserts a new datatype at the specified ordinal position in this composite.
    Note: For an aligned structure the ordinal position will get adjusted automatically to provide the proper alignment.
    Parameters:
      `ordinal` - the ordinal where the new datatype is to be inserted.
      `dataType` - the datatype to insert.
    Returns:
      the componentDataType created.
    Throws:
      `IllegalArgumentException` - if the specified data type is not allowed to be inserted into this composite data type. For example, suppose dt1 contains dt2. Therefore it is not valid to insert dt1 to dt2 since this would cause a cyclic dependency.
      `IndexOutOfBoundsException` - if component ordinal is out of bounds

  - ### insert

    DataTypeComponent insert(int ordinal, DataType dataType, int length) throws IndexOutOfBoundsException, IllegalArgumentException
    Inserts a new datatype at the specified ordinal position in this composite.
    Note: For an aligned structure the ordinal position will get adjusted automatically to provide the proper alignment.
    Parameters:
      `ordinal` - the ordinal where the new datatype is to be inserted.
      `dataType` - the datatype to insert.
      `length` - the length to associate with the datatype. For fixed length types a length <= 0 will use the length of the resolved dataType.
    Returns:
      the componentDataType created.
    Throws:
      `IllegalArgumentException` - if the specified data type is not allowed to be inserted into this composite data type or an invalid length is specified. For example, suppose dt1 contains dt2. Therefore it is not valid to insert dt1 to dt2 since this would cause a cyclic dependency.
      `IndexOutOfBoundsException` - if component ordinal is out of bounds

  - ### insert

    DataTypeComponent insert(int ordinal, DataType dataType, int length, String name, String comment) throws IndexOutOfBoundsException, IllegalArgumentException
    Inserts a new datatype at the specified ordinal position in this composite.
    Note: For an aligned structure the ordinal position will get adjusted automatically to provide the proper alignment.
    Parameters:
      `ordinal` - the ordinal where the new datatype is to be inserted.
      `dataType` - the datatype to insert.
      `length` - the length to associate with the datatype. For fixed length types a length <= 0 will use the length of the resolved dataType.
      `name` - the field name to associate with this component.
      `comment` - the comment to associate with this component.
    Returns:
      the componentDataType created.
    Throws:
      `IllegalArgumentException` - if the specified data type is not allowed to be inserted into this composite data type or an invalid length is specified. For example, suppose dt1 contains dt2. Therefore it is not valid to insert dt1 to dt2 since this would cause a cyclic dependency.
      `IndexOutOfBoundsException` - if component ordinal is out of bounds

  - ### delete

    void delete(int ordinal) throws IndexOutOfBoundsException
    Deletes the component at the given ordinal position.
    Note: Removal of bitfields from a structure with packing disabled will not shift other components causing vacated bytes to revert to undefined filler.
    Parameters:
      `ordinal` - the ordinal of the component to be deleted.
    Throws:
      `IndexOutOfBoundsException` - if component ordinal is out of bounds

  - ### delete

    void delete(Set<Integer> ordinals) throws IndexOutOfBoundsException
    Deletes the specified set of components at the given ordinal positions.
    Note: Removal of bitfields from a structure with packing disabled will not shift other components causing vacated bytes to revert to undefined filler.
    Parameters:
      `ordinals` - the ordinals of the component to be deleted.
    Throws:
      `IndexOutOfBoundsException` - if any specified component ordinal is out of bounds

  - ### isPartOf

    boolean isPartOf(DataType dataType)
    Check if a data type is part of this data type. A data type could be part of another by:
    Being the same data type.
    containing the data type directly
    containing another data type that has the data type as a part of it.
    Parameters:
      `dataType` - the data type to look for.
    Returns:
      true if the indicated data type is part of a sub-component of this data type.

  - ### dataTypeAlignmentChanged

    void dataTypeAlignmentChanged(DataType dt)
    The alignment changed for the specified data type. If packing is enabled for this composite, the placement of the component may be affected by a change in its alignment. A non-packed composite can ignore this notification.
    Specified by:
      `dataTypeAlignmentChanged` in interface `DataType`
    Parameters:
      `dt` - the data type whose alignment changed.

  - ### repack

    void repack()
    Updates packed composite to any changes in the data organization. If the composite does not have packing enabled this method does nothing.
    NOTE: Changes to data organization is discouraged. Attempts to use this method in such cases should be performed on all composites in dependency order (ignoring pointer components).

  - ### getPackingType

    PackingType getPackingType()
    Returns:
      the packing type set for this composite

  - ### isPackingEnabled

    default boolean isPackingEnabled()
    Determine if this data type has its internal components currently packed based upon alignment and packing settings. If disabled, component placement is based upon explicit placement by offset.
    Returns:
      true if this data type's components auto-packed

  - ### setPackingEnabled

    void setPackingEnabled(boolean enabled)
    Sets whether this data type's internal components are currently packed. The affect of disabled packing differs between `Structure` and `Union`. When packing disabled:
    - Structures utilize explicit component offsets and produce undefined filler components where defined components do not consume space.
    - Unions always place components at offset 0 and do not pad for alignment.
    In addition, when packing is disabled the default alignment is always 1 unless a different minimum alignment has been set. When packing is enabled the overall composite length influenced by the composite's minimum alignment setting. If a change in enablement occurs, the default alignment and packing behavior will be used.
    Parameters:
      `enabled` - true enables packing of components respecting component alignment and pack setting, whereas false disables packing.

  - ### hasExplicitPackingValue

    default boolean hasExplicitPackingValue()
    Determine if packing is enabled with an explicit packing value (see `getExplicitPackingValue()`).
    Returns:
      true if packing is enabled with an explicit packing value, else false.

  - ### hasDefaultPacking

    default boolean hasDefaultPacking()
    Determine if default packing is enabled.
    Returns:
      true if default packing is enabled.

  - ### getExplicitPackingValue

    int getExplicitPackingValue()
    Gets the current packing value (typically a power of 2). If this isn't a packed composite with an explicit packing value (see `hasExplicitPackingValue()`) then the return value is undefined.
    Returns:
      the current packing value or an undefined non-positive value

  - ### setExplicitPackingValue

    void setExplicitPackingValue(int packingValue)
    Sets the pack value for this composite (positive value, usually a power of 2). If packing was previously disabled, packing will be enabled. This value will establish the maximum effective alignment for this composite and each of the components during the alignment computation (e.g., a value of 1 will eliminate any padding). The overall composite length may be influenced by the composite's minimum alignment setting.
    Parameters:
      `packingValue` - the new positive packing value.
    Throws:
      `IllegalArgumentException` - if a non-positive value is specified.

  - ### pack

    default void pack(int packingValue)
    Same as `setExplicitPackingValue(int)`.
    Parameters:
      `packingValue` - the new positive packing value.
    Throws:
      `IllegalArgumentException` - if a non-positive value is specified.

  - ### setToDefaultPacking

    void setToDefaultPacking()
    Enables default packing behavior. If packing was previously disabled, packing will be enabled. Composite will automatically pack based upon the alignment requirements of its components with overall composite length possibly influenced by the composite's minimum alignment setting.

  - ### getAlignment

    int getAlignment()
    Get the computed alignment for this composite based upon packing and minimum alignment settings as well as component alignment. If packing is disabled, the alignment will always be 1 unless a minimum alignment has been set.
    Specified by:
      `getAlignment` in interface `DataType`
    Returns:
      this composites alignment

  - ### getAlignmentType

    AlignmentType getAlignmentType()
    Returns:
      the alignment type set for this composite

  - ### isDefaultAligned

    default boolean isDefaultAligned()
    Whether or not this data type is using the default alignment. When Structure packing is disabled the default alignment is always 1 (see `setPackingEnabled(boolean)`.
    Returns:
      true if this data type is using its default alignment.

  - ### isMachineAligned

    default boolean isMachineAligned()
    Whether or not this data type is using the machine alignment value, specified by `DataOrganization.getMachineAlignment()`, for its alignment.
    Returns:
      true if this data type is using the machine alignment as its alignment.

  - ### hasExplicitMinimumAlignment

    default boolean hasExplicitMinimumAlignment()
    Determine if an explicit minimum alignment has been set (see `getExplicitMinimumAlignment()`). An undefined value is returned if default alignment or machine alignment is enabled.
    Returns:
      true if an explicit minimum alignment has been set, else false

  - ### getExplicitMinimumAlignment

    int getExplicitMinimumAlignment()
    Get the explicit minimum alignment setting for this Composite which contributes to the actual computed alignment value (see `getAlignment()`.
    Returns:
      the minimum alignment setting for this Composite or an undefined non-positive value if an explicit minimum alignment has not been set.

  - ### setExplicitMinimumAlignment

    void setExplicitMinimumAlignment(int minAlignment)
    Sets this data type's explicit minimum alignment (positive value). Together with the pack setting and component alignments will affect the actual computed alignment of this composite. When packing is enabled, the alignment setting may also affect padding at the end of the composite and its length. When packing is disabled, this setting will not affect the length of this composite.
    Parameters:
      `minAlignment` - the minimum alignment for this Composite.
    Throws:
      `IllegalArgumentException` - if a non-positive value is specified

  - ### align

    default void align(int minAlignment)
    Same as `setExplicitMinimumAlignment(int)`.
    Parameters:
      `minAlignment` - the explicit minimum alignment for this Composite.
    Throws:
      `IllegalArgumentException` - if a non-positive value is specified

  - ### setToDefaultAligned

    void setToDefaultAligned()
    Sets this data type's alignment to its default alignment. For packed composites, this data type's alignment will be based upon the components it contains and its current pack settings. This is the default state and only needs to be used when changing from a non-default alignment type.

  - ### setToMachineAligned

    void setToMachineAligned()
    Sets this data type's minimum alignment to the machine alignment which is specified by `DataOrganization.getMachineAlignment()`. The machine alignment is defined as the maximum useful alignment for the target machine.