Package ghidra.program.model.data

# Class ArrayDataType

java.lang.Object
ghidra.program.model.data.AbstractDataType
ghidra.program.model.data.DataTypeImpl
ghidra.program.model.data.ArrayDataType

All Implemented Interfaces:
  `Array`, `DataType`

public class ArrayDataType extends DataTypeImpl implements Array
Basic implementation of the Array interface.

- ## Field Summary

  ### Fields inherited from class ghidra.program.model.data.DataTypeImpl

  `defaultSettings`

  ### Fields inherited from class ghidra.program.model.data.AbstractDataType

  `categoryPath, dataMgr, name`

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

  `ARRAY_LABEL_PREFIX`

  ### 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`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ArrayDataType(DataType dataType, int numElements, int elementLength)`
  Constructs a new Array dataType.
  `ArrayDataType(DataType dataType, int numElements, int elementLength, DataTypeManager dtm)`
  Constructs a new Array dataType.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `final DataType`
  `clone(DataTypeManager dtm)`
  Returns an instance of this DataType using the specified `DataTypeManager` to allow its use of the corresponding `DataOrganization` while retaining its unique identity (see `DataType.getUniversalID()` and archive association (see `DataType.getSourceArchive()`) if applicable.
  `final DataType`
  `copy(DataTypeManager dtm)`
  Returns a new instance (shallow copy) of this DataType with a new identity and no source archive association.
  `void`
  `dataTypeAlignmentChanged(DataType dt)`
  Notification that the given datatype's alignment has changed.
  `void`
  `dataTypeDeleted(DataType dt)`
  Informs this datatype that the given datatype has been deleted.
  `void`
  `dataTypeNameChanged(DataType dt, String oldName)`
  Informs this datatype that its name has changed from the indicated old name.
  `void`
  `dataTypeReplaced(DataType oldDt, DataType newDt)`
  Informs this datatype that the given oldDT has been replaced with newDT
  `void`
  `dataTypeSizeChanged(DataType dt)`
  Notification that the given datatype's size has changed.
  `boolean`
  `dependsOn(DataType dt)`
  Check if this datatype depends on the existence of the given datatype.
  `int`
  `getAlignedLength()`
  Get the aligned-length of this datatype as a number of 8-bit bytes.
  `CategoryPath`
  `getCategoryPath()`
  Gets the categoryPath associated with this datatype
  `DataType`
  `getDataType()`
  Returns the dataType of the elements in the array.
  `String`
  `getDefaultLabelPrefix()`
  Returns the appropriate string to use as the default label prefix in the absence of any data.
  `String`
  `getDefaultLabelPrefix(MemBuffer buf, Settings settings, int len, DataTypeDisplayOptions options)`
  Returns the appropriate string to use as the default label prefix.
  `String`
  `getDefaultOffcutLabelPrefix(MemBuffer buf, Settings settings, int len, DataTypeDisplayOptions options, int offcutLength)`
  Returns the appropriate string to use as the default label prefix.
  `String`
  `getDescription()`
  Get a String briefly describing this DataType.
  `int`
  `getElementLength()`
  Returns the length of an element in the array.
  `long`
  `getLastChangeTime()`
  Get the timestamp corresponding to the last time this type was changed within its datatype manager
  `int`
  `getLength()`
  Get the length of this DataType as a number of 8-bit bytes.
  `String`
  `getMnemonic(Settings settings)`
  Get the mnemonic for this DataType.
  `int`
  `getNumElements()`
  Returns the number of elements in the array
  `String`
  `getRepresentation(MemBuffer buf, Settings settings, int length)`
  Get bytes from memory in a printable format for this type.
  `SettingsDefinition[]`
  `getSettingsDefinitions()`
  Get the list of settings definitions available for use with this datatype.
  `TypeDefSettingsDefinition[]`
  `getTypeDefSettingsDefinitions()`
  Get the list of all settings definitions for this datatype that may be used for an associated `TypeDef`.
  `Object`
  `getValue(MemBuffer buf, Settings settings, int length)`
  Returns the interpreted data value as an instance of the `advertised value class`.
  `Class<?>`
  `getValueClass(Settings settings)`
  Get the Class of the value Object to be returned by this datatype (see `DataType.getValue(MemBuffer, Settings, int)`).
  `boolean`
  `hasLanguageDependantLength()`
  Indicates if the length of this data-type is determined based upon the `DataOrganization` obtained from the associated `DataTypeManager`.
  `boolean`
  `isDeleted()`
  Returns true if this datatype has been deleted and is no longer valid
  `boolean`
  `isEquivalent(DataType obj)`
  Check if the given datatype is equivalent to this datatype.
  `boolean`
  `isZeroLength()`
  Indicates this datatype is defined with a zero length.
  `void`
  `setCategoryPath(CategoryPath path)`
  Set the categoryPath associated with this datatype
  `void`
  `setName(String name)`
  Sets the name of the datatype
  `void`
  `setNameAndCategory(CategoryPath path, String name)`
  Sets the name and category of a datatype at the same time.

  ### Methods inherited from class ghidra.program.model.data.DataTypeImpl

  `addParent, equals, getAlignment, getDefaultSettings, getLastChangeTimeInSourceArchive, getParents, getPathName, getSourceArchive, getUniversalID, hashCode, notifyAlignmentChanged, notifyDeleted, notifyNameChanged, notifyParents, notifyReplaced, notifySizeChanged, removeParent, replaceWith, setDescription, setLastChangeTime, setLastChangeTimeInSourceArchive, setSourceArchive`

  ### Methods inherited from class ghidra.program.model.data.AbstractDataType

  `encodeRepresentation, encodeValue, getDataOrganization, getDataOrganization, getDataTypeManager, getDataTypePath, getDefaultAbbreviatedLabelPrefix, getDisplayName, getDocs, getName, isEncodable, isNotYetDefined, toString`

  ### Methods inherited from class java.lang.Object

  `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

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

  `getArrayDefaultLabelPrefix, getArrayDefaultOffcutLabelPrefix, getArrayRepresentation, getArrayValue, getArrayValueClass`

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

  `addParent, encodeRepresentation, encodeValue, getAlignment, getDataOrganization, getDataTypeManager, getDataTypePath, getDefaultAbbreviatedLabelPrefix, getDefaultSettings, getDisplayName, getDocs, getLastChangeTimeInSourceArchive, getName, getParents, getPathName, getSourceArchive, getUniversalID, isEncodable, isNotYetDefined, removeParent, replaceWith, setDescription, setLastChangeTime, setLastChangeTimeInSourceArchive, setSourceArchive`

- ## Constructor Details

  - ### ArrayDataType

    public ArrayDataType(DataType dataType, int numElements, int elementLength)
    Constructs a new Array dataType.
    Parameters:
      `dataType` - the dataType of the elements in the array (null is not permitted).
      `numElements` - the number of elements in the array (0 is permitted).
      `elementLength` - the length of an individual element in the array. This value is only used for `Dynamic` dataType where `Dynamic.canSpecifyLength()` returns true.

  - ### ArrayDataType

    public ArrayDataType(DataType dataType, int numElements, int elementLength, DataTypeManager dtm)
    Constructs a new Array dataType.
    Parameters:
      `dataType` - the dataType of the elements in the array.
      `numElements` - the number of elements in the array (0 is permitted).
      `elementLength` - the length of an individual element in the array. This value is only used for `Dynamic` dataType where `Dynamic.canSpecifyLength()` returns true.
      `dtm` - datatype manager or null

- ## Method Details

  - ### hasLanguageDependantLength

    public boolean hasLanguageDependantLength()
    Description copied from interface: `DataType`
    Indicates if the length of this data-type is determined based upon the `DataOrganization` obtained from the associated `DataTypeManager`.
    Specified by:
      `hasLanguageDependantLength` in interface `DataType`
    Overrides:
      `hasLanguageDependantLength` in class `AbstractDataType`
    Returns:
      true length is language/compiler-specification dependent, else false

  - ### getSettingsDefinitions

    public SettingsDefinition[] getSettingsDefinitions()
    Description copied from interface: `DataType`
    Get the list of settings definitions available for use with this datatype.

    In the case of a `TypeDef`, the return list will include the `TypeDefSettingsDefinition` list from the associated base data type.

    Unlike `TypeDefSettingsDefinition` standard settings definitions generally support default, component-default and data-instance use. In addition, standard settings definitions are never considered during `DataType.isEquivalent(DataType)` checking or during the resolve process.

    Specified by:
      `getSettingsDefinitions` in interface `DataType`
    Overrides:
      `getSettingsDefinitions` in class `DataTypeImpl`
    Returns:
      list of the settings definitions for this datatype.

  - ### getTypeDefSettingsDefinitions

    public TypeDefSettingsDefinition[] getTypeDefSettingsDefinitions()
    Description copied from interface: `DataType`
    Get the list of all settings definitions for this datatype that may be used for an associated `TypeDef`. When used for an associated `TypeDef`, these settings will be considered during a `DataType.isEquivalent(DataType)` check and will be preserved during the resolve process.
    Specified by:
      `getTypeDefSettingsDefinitions` in interface `DataType`
    Overrides:
      `getTypeDefSettingsDefinitions` in class `AbstractDataType`
    Returns:
      a list of the settings definitions for a `TypeDef` associated with this datatype.

  - ### isEquivalent

    public boolean isEquivalent(DataType obj)
    Description copied from interface: `DataType`
    Check if the given datatype is equivalent to this datatype.

    The precise meaning of "equivalent" is datatype dependent.
    NOTE: if invoked by a DB object or manager it should be invoked on the DataTypeDB object passing the other datatype as the argument.

    Specified by:
      `isEquivalent` in interface `DataType`
    Parameters:
      `obj` - the datatype being tested for equivalence.
    Returns:
      true if the if the given datatype is equivalent to this datatype.

  - ### getNumElements

    public int getNumElements()
    Description copied from interface: `Array`
    Returns the number of elements in the array
    Specified by:
      `getNumElements` in interface `Array`
    Returns:
      the number of elements in the array

  - ### getMnemonic

    public String getMnemonic(Settings settings)
    Description copied from interface: `DataType`
    Get the mnemonic for this DataType.
    Specified by:
      `getMnemonic` in interface `DataType`
    Overrides:
      `getMnemonic` in class `AbstractDataType`
    Parameters:
      `settings` - settings which may influence the result or null
    Returns:
      the mnemonic for this DataType.

  - ### isZeroLength

    public boolean isZeroLength()
    Description copied from interface: `DataType`
    Indicates this datatype is defined with a zero length.

    This method should not be confused with `DataType.isNotYetDefined()` which indicates that nothing but the name and basic type is known.

    NOTE: a zero-length datatype must return a length of 1 via `DataType.getLength()`. Zero-length datatypes used as a component within a `Composite` may, or may not, be assigned a component length of 0. The method `DataTypeComponent.usesZeroLengthComponent(DataType)` is used to make this determination.

    Specified by:
      `isZeroLength` in interface `DataType`
    Overrides:
      `isZeroLength` in class `AbstractDataType`
    Returns:
      true if type definition has a length of 0, else false

  - ### getLength

    public int getLength()
    Description copied from interface: `DataType`
    Get the length of this DataType as a number of 8-bit bytes.

    For primitive datatypes this reflects the smallest varnode which can be used to contain its value (i.e., raw data length).

    Example: For x86 32-bit gcc an 80-bit `long double` `raw data length` of 10-bytes will fit within a floating point register while its `aligned-length` of 12-bytes is used by the gcc compiler for data/array/component allocations to maintain alignment (i.e., `sizeof(long double)` ).

    NOTE: Other than the `VoidDataType`, no datatype should ever return 0, even if `DataType.isZeroLength()`, and only `Dynamic`/`FactoryDataType` datatypes should return -1. If `DataType.isZeroLength()` is true a length of 1 should be returned. Where a zero-length datatype can be handled (e.g., `Composite`) the `DataType.isZeroLength()` method should be used.

    Specified by:
      `getLength` in interface `DataType`
    Returns:
      the length of this DataType

  - ### getAlignedLength

    public int getAlignedLength()
    Description copied from interface: `DataType`
    Get the aligned-length of this datatype as a number of 8-bit bytes.

    For primitive datatypes this is equivalent to the C/C++ "sizeof" operation within source code and should be used when determining `Array` element length or component sizing for a `Composite`. For `Pointer`, `Composite` and `Array` types this will return the same value as `DataType.getLength()`.

    Example: For x86 32-bit gcc an 80-bit `long double` `raw data length` of 10-bytes will fit within a floating point register while its `aligned-length` of 12-bytes is used by the gcc compiler for data/array/component allocations to maintain alignment (i.e., `sizeof(long double)` ).

    NOTE: Other than the `VoidDataType`, no datatype should ever return 0, even if `DataType.isZeroLength()`, and only `Dynamic` / `FactoryDataType` / `FunctionDefinition` datatypes should return -1. If `DataType.isZeroLength()` is true a length of 1 should be returned.

    Specified by:
      `getAlignedLength` in interface `DataType`
    Overrides:
      `getAlignedLength` in class `DataTypeImpl`
    Returns:
      byte length of binary encoding.

  - ### getDescription

    public String getDescription()
    Description copied from interface: `DataType`
    Get a String briefly describing this DataType.
    Specified by:
      `getDescription` in interface `DataType`
    Returns:
      a one-liner describing this DataType.

  - ### getDataType

    public DataType getDataType()
    Description copied from interface: `Array`
    Returns the dataType of the elements in the array.
    Specified by:
      `getDataType` in interface `Array`
    Returns:
      the dataType of the elements in the array

  - ### clone

    public final DataType clone(DataTypeManager dtm)
    Description copied from interface: `DataType`
    Returns an instance of this DataType using the specified `DataTypeManager` to allow its use of the corresponding `DataOrganization` while retaining its unique identity (see `DataType.getUniversalID()` and archive association (see `DataType.getSourceArchive()`) if applicable.

    This instance will be returned if this datatype's DataTypeManager matches the specified dtm. The recursion depth of a clone will stop on any datatype whose `DataTypeManager` matches the specified dtm and simply use the existing datatype instance.

    NOTE: In general, this method should not be used to obtain an instance to be modified. In most cases changes may be made directly to this instance if supported or to a `DataType.copy(DataTypeManager)` of this type.

    Specified by:
      `clone` in interface `DataType`
    Parameters:
      `dtm` - the data-type manager instance whose data-organization should apply.
    Returns:
      cloned instance which may be the same as this instance

  - ### copy

    public final DataType copy(DataTypeManager dtm)
    Description copied from interface: `DataType`
    Returns a new instance (shallow copy) of this DataType with a new identity and no source archive association.

    Any reference to other datatypes will use `DataType.clone(DataTypeManager)`.

    Specified by:
      `copy` in interface `DataType`
    Parameters:
      `dtm` - the data-type manager instance whose data-organization should apply.
    Returns:
      new instanceof of this datatype

  - ### dataTypeSizeChanged

    public void dataTypeSizeChanged(DataType dt)
    Description copied from interface: `DataType`
    Notification that the given datatype's size has changed.

    DataTypes may need to make internal changes in response.
    TODO: This method is reserved for internal DB use.

    Specified by:
      `dataTypeSizeChanged` in interface `DataType`
    Overrides:
      `dataTypeSizeChanged` in class `AbstractDataType`
    Parameters:
      `dt` - the datatype that has changed.

  - ### dataTypeAlignmentChanged

    public void dataTypeAlignmentChanged(DataType dt)
    Description copied from interface: `DataType`
    Notification that the given datatype's alignment has changed.

    DataTypes may need to make internal changes in response.
    TODO: This method is reserved for internal DB use.

    Specified by:
      `dataTypeAlignmentChanged` in interface `DataType`
    Overrides:
      `dataTypeAlignmentChanged` in class `AbstractDataType`
    Parameters:
      `dt` - the datatype that has changed.

  - ### getValueClass

    public Class<?> getValueClass(Settings settings)
    Description copied from interface: `DataType`
    Get the Class of the value Object to be returned by this datatype (see `DataType.getValue(MemBuffer, Settings, int)`).
    Specified by:
      `getValueClass` in interface `DataType`
    Overrides:
      `getValueClass` in class `DataTypeImpl`
    Parameters:
      `settings` - the relevant settings to use or null for default.
    Returns:
      Class of the value to be returned by this datatype or null if it can vary or is unspecified. Types which correspond to a string or char array will return the String class.

  - ### setName

    public void setName(String name) throws InvalidNameException
    Description copied from interface: `DataType`
    Sets the name of the datatype
    Specified by:
      `setName` in interface `DataType`
    Overrides:
      `setName` in class `AbstractDataType`
    Parameters:
      `name` - the new name for this datatype.
    Throws:
      `InvalidNameException` - if the given name does not form a valid name.

  - ### getElementLength

    public int getElementLength()
    Description copied from interface: `Array`
    Returns the length of an element in the array. In the case of a Dynamic base datatype, this element length will have been explicitly specified at the time of construction. For a zero-length base type an element length of 1 will be reported with `DataType.getLength()` returning the number of elements.
    Specified by:
      `getElementLength` in interface `Array`
    Returns:
      the length of one element in the array.

  - ### dataTypeDeleted

    public void dataTypeDeleted(DataType dt)
    Description copied from interface: `DataType`
    Informs this datatype that the given datatype has been deleted.

    TODO: This method is reserved for internal DB use.

    Specified by:
      `dataTypeDeleted` in interface `DataType`
    Overrides:
      `dataTypeDeleted` in class `AbstractDataType`
    Parameters:
      `dt` - the datatype that has been deleted.

  - ### isDeleted

    public boolean isDeleted()
    Description copied from interface: `DataType`
    Returns true if this datatype has been deleted and is no longer valid
    Specified by:
      `isDeleted` in interface `DataType`
    Overrides:
      `isDeleted` in class `AbstractDataType`
    Returns:
      true if this datatype has been deleted and is no longer valid.

  - ### dataTypeReplaced

    public void dataTypeReplaced(DataType oldDt, DataType newDt)
    Description copied from interface: `DataType`
    Informs this datatype that the given oldDT has been replaced with newDT

    TODO: This method is reserved for internal DB use.

    Specified by:
      `dataTypeReplaced` in interface `DataType`
    Overrides:
      `dataTypeReplaced` in class `AbstractDataType`
    Parameters:
      `oldDt` - old datatype
      `newDt` - new datatype

  - ### setCategoryPath

    public void setCategoryPath(CategoryPath path) throws DuplicateNameException
    Description copied from interface: `DataType`
    Set the categoryPath associated with this datatype
    Specified by:
      `setCategoryPath` in interface `DataType`
    Overrides:
      `setCategoryPath` in class `AbstractDataType`
    Parameters:
      `path` - the new path
    Throws:
      `DuplicateNameException` - if an attempt to place this datatype into the specified category resulted in a name collision. This should not occur for non-DB DataType instances.

  - ### setNameAndCategory

    public void setNameAndCategory(CategoryPath path, String name) throws InvalidNameException, DuplicateNameException
    Description copied from interface: `DataType`
    Sets the name and category of a datatype at the same time.
    Specified by:
      `setNameAndCategory` in interface `DataType`
    Overrides:
      `setNameAndCategory` in class `AbstractDataType`
    Parameters:
      `path` - the new category path.
      `name` - the new name
    Throws:
      `InvalidNameException` - if the name is invalid
      `DuplicateNameException` - if name change on stored `DataType` is a duplicate of another datatype within the same category (only applies to DB stored `DataType`).

  - ### getCategoryPath

    public CategoryPath getCategoryPath()
    Description copied from interface: `DataType`
    Gets the categoryPath associated with this datatype
    Specified by:
      `getCategoryPath` in interface `DataType`
    Overrides:
      `getCategoryPath` in class `AbstractDataType`
    Returns:
      the datatype's category path

  - ### dataTypeNameChanged

    public void dataTypeNameChanged(DataType dt, String oldName)
    Description copied from interface: `DataType`
    Informs this datatype that its name has changed from the indicated old name.

    TODO: This method is reserved for internal DB use.

    Specified by:
      `dataTypeNameChanged` in interface `DataType`
    Overrides:
      `dataTypeNameChanged` in class `AbstractDataType`
    Parameters:
      `dt` - the datatype whose name changed
      `oldName` - the datatype's old name

  - ### dependsOn

    public boolean dependsOn(DataType dt)
    Description copied from interface: `DataType`
    Check if this datatype depends on the existence of the given datatype.

    For example byte[] depends on byte. If byte were deleted, then byte[] would also be deleted.

    Specified by:
      `dependsOn` in interface `DataType`
    Overrides:
      `dependsOn` in class `AbstractDataType`
    Parameters:
      `dt` - the datatype to test that this datatype depends on.
    Returns:
      true if the existence of this datatype relies on the existence of the specified datatype dt.

  - ### getDefaultLabelPrefix

    public String getDefaultLabelPrefix()
    Description copied from interface: `DataType`
    Returns the appropriate string to use as the default label prefix in the absence of any data.
    Specified by:
      `getDefaultLabelPrefix` in interface `DataType`
    Overrides:
      `getDefaultLabelPrefix` in class `AbstractDataType`
    Returns:
      the default label prefix or null if none specified.

  - ### getDefaultLabelPrefix

    public String getDefaultLabelPrefix(MemBuffer buf, Settings settings, int len, DataTypeDisplayOptions options)
    Description copied from interface: `DataType`
    Returns the appropriate string to use as the default label prefix.
    Specified by:
      `getDefaultLabelPrefix` in interface `DataType`
    Overrides:
      `getDefaultLabelPrefix` in class `AbstractDataType`
    Parameters:
      `buf` - memory buffer containing the bytes.
      `settings` - the Settings object
      `len` - the length of the data.
      `options` - options for how to format the default label prefix.
    Returns:
      the default label prefix or null if none specified.

  - ### getDefaultOffcutLabelPrefix

    public String getDefaultOffcutLabelPrefix(MemBuffer buf, Settings settings, int len, DataTypeDisplayOptions options, int offcutLength)
    Description copied from interface: `DataType`
    Returns the appropriate string to use as the default label prefix.

    This takes into account the fact that there exists a reference to the data that references `offcutLength` bytes into this type

    Specified by:
      `getDefaultOffcutLabelPrefix` in interface `DataType`
    Overrides:
      `getDefaultOffcutLabelPrefix` in class `AbstractDataType`
    Parameters:
      `buf` - memory buffer containing the bytes.
      `settings` - the Settings object
      `len` - the length of the data.
      `options` - options for how to format the default label prefix.
      `offcutLength` - offset into datatype
    Returns:
      the default label prefix.

  - ### getLastChangeTime

    public long getLastChangeTime()
    Description copied from interface: `DataType`
    Get the timestamp corresponding to the last time this type was changed within its datatype manager
    Specified by:
      `getLastChangeTime` in interface `DataType`
    Overrides:
      `getLastChangeTime` in class `DataTypeImpl`
    Returns:
      timestamp of last change within datatype manager

  - ### getValue

    public Object getValue(MemBuffer buf, Settings settings, int length)
    Description copied from interface: `DataType`
    Returns the interpreted data value as an instance of the `advertised value class`.

    For instance, `Pointer` data types should return an Address object (or null), or integer data types should return a `Scalar` object.

    Specified by:
      `getValue` in interface `DataType`
    Parameters:
      `buf` - the data buffer
      `settings` - the settings to use.
      `length` - indicates the maximum number of bytes that may be consumed by a `Dynamic` datatype, otherwise this value is ignored. A value of -1 may be specified to allow a Dynamic datatype to determine the length based upon the actual data bytes
    Returns:
      the data object, or null if data is invalid

  - ### getRepresentation

    public String getRepresentation(MemBuffer buf, Settings settings, int length)
    Description copied from interface: `DataType`
    Get bytes from memory in a printable format for this type.
    Specified by:
      `getRepresentation` in interface `DataType`
    Parameters:
      `buf` - the data.
      `settings` - the settings to use for the representation.
      `length` - the number of bytes to represent.
    Returns:
      the representation of the data in this format, never null.