Package ghidra.program.model.data

# Class DataUtilities

java.lang.Object
ghidra.program.model.data.DataUtilities

public final class DataUtilities extends Object

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static enum`
  `DataUtilities.ClearDataMode`
  `ClearDataMode` specifies how conflicting data should be cleared when creating/re-creating data

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static Data`
  `createData(Program program, Address addr, DataType newType, int length, boolean stackPointers, DataUtilities.ClearDataMode clearMode)`
  Create data where existing data may already exist.
  `static Data`
  `createData(Program program, Address addr, DataType newType, int length, DataUtilities.ClearDataMode clearMode)`
  Create data where existing data may already exist.
  `static Address`
  `findFirstConflictingAddress(Program program, Address addr, int length, boolean ignoreUndefinedData)`
  Finds the first conflicting address in the given address range.
  `static Data`
  `getDataAtAddress(Program program, Address address)`
  Get the data for the given address.
  `static Data`
  `getDataAtLocation(ProgramLocation loc)`
  Get the data for the given address; if the code unit at the address is an instruction, return null.
  `static Address`
  `getMaxAddressOfUndefinedRange(Program program, Address addr)`
  Get the maximum address of an undefined data range starting at addr.
  `static Data`
  `getNextNonUndefinedDataAfter(Program program, Address addr, Address maxAddr)`
  Get the next defined data that comes after the address indicated by addr and that is no more than the specified maxAddr and that is not a sized undefined data type.
  `static boolean`
  `isUndefinedData(Program program, Address addr)`
  Determine if the specified addr corresponds to an undefined data location where both undefined code units and defined data which has an Undefined data type is considered to be undefined.
  `static boolean`
  `isUndefinedRange(Program program, Address startAddress, Address endAddress)`
  Determine if there is only undefined data from the specified startAddress to the specified endAddress.
  `static boolean`
  `isValidDataTypeName(String name)`
  Determine if the specified name is a valid data-type name
  `static DataType`
  `reconcileAppliedDataType(DataType originalDataType, DataType newDataType, boolean stackPointers)`
  Determine the final data-type which should be applied based upon a user applied type of newDataType on an existing originalDataType.

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

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Method Details

  - ### isValidDataTypeName

    public static boolean isValidDataTypeName(String name)
    Determine if the specified name is a valid data-type name
    Parameters:
      `name` - candidate data-type name
    Returns:
      true if name is valid, else false

  - ### createData

    public static Data createData(Program program, Address addr, DataType newType, int length, DataUtilities.ClearDataMode clearMode) throws CodeUnitInsertionException
    Create data where existing data may already exist. Pointer datatype stacking will not be performed.
    Parameters:
      `program` - the program
      `addr` - data address (offcut data address only allowed if clearMode == ClearDataMode.CLEAR_ALL_CONFLICT_DATA)
      `newType` - new data-type being applied
      `length` - data length (used only for Dynamic newDataType which has canSpecifyLength()==true)
      `clearMode` - see CreateDataMode
    Returns:
      new data created
    Throws:
      `CodeUnitInsertionException` - if data creation failed

  - ### createData

    public static Data createData(Program program, Address addr, DataType newType, int length, boolean stackPointers, DataUtilities.ClearDataMode clearMode) throws CodeUnitInsertionException
    Create data where existing data may already exist.
    Parameters:
      `program` - the program
      `addr` - data address (offcut data address only allowed if clearMode == ClearDataMode.CLEAR_ALL_CONFLICT_DATA)
      `newType` - new data-type being applied
      `length` - data length (used only for Dynamic newDataType which has canSpecifyLength()==true)
      `stackPointers` - see `reconcileAppliedDataType(DataType, DataType, boolean)`
      `clearMode` - see CreateDataMode
    Returns:
      new data created
    Throws:
      `CodeUnitInsertionException` - if data creation failed

  - ### reconcileAppliedDataType

    public static DataType reconcileAppliedDataType(DataType originalDataType, DataType newDataType, boolean stackPointers)
    Determine the final data-type which should be applied based upon a user applied type of newDataType on an existing originalDataType. Pointer conversion is performed when appropriate, otherwise the newDataType is returned unchanged. If newDataType is a FunctionDefinition, or Typedef to a FunctionDefinition, it will either be stacked with the existing pointer if enabled/applicable, or will be converted to a pointer since FunctionDefinitions may only been used in the form of a pointer. Note that originalDataType and newDataType should be actual applied types. (i.e., do not strip typedefs, pointers, arrays, etc.).
    Parameters:
      `originalDataType` - existing data type onto which newDataTye is applied
      `newDataType` - new data-type being applied
      `stackPointers` - If true the following data type transformation will be performed:
      - If newDataType is a default pointer and the originalDataType is a pointer the new pointer will wrap the existing pointer thus increasing is 'depth' (e.g., int * would become int ** when default pointer applied). If the originalDataType is not a pointer the newDataType will be returned unchanged.
      - If the originalDataType is any type of pointer the supplied newDatatype will replace the pointer's base type (e.g., int * would become db * when newDataType is `ByteDataType`).

      If false, only required transformations will be applied, Example: if newDataType is a FunctionDefinitionDataType it will be transformed to a pointer before being applied.

    Returns:
      either a combined pointer data-type or the newDataType specified with any required transformation

  - ### getDataAtLocation

    public static Data getDataAtLocation(ProgramLocation loc)
    Get the data for the given address; if the code unit at the address is an instruction, return null.
    Parameters:
      `loc` - the location. This provides the address and subcomponent within the data at the address.
    Returns:
      the data or null if the code unit at the address is an instruction.

  - ### getDataAtAddress

    public static Data getDataAtAddress(Program program, Address address)
    Get the data for the given address.

    This will return a Data if and only if there is data that starts at the given address.

    Parameters:
      `program` - the program
      `address` - the data address
    Returns:
      the Data that starts at the given address or null if the address is code or offcut

  - ### getMaxAddressOfUndefinedRange

    public static Address getMaxAddressOfUndefinedRange(Program program, Address addr)
    Get the maximum address of an undefined data range starting at addr. Both undefined code units and defined data which have an Undefined data type are included in the range.
    Parameters:
      `program` - the program which will have its code units checked.
      `addr` - the address where this will start checking for Undefined data. This address can be offcut into an Undefined Data.
    Returns:
      end of undefined range or null if addr does not correspond to an undefined location.

  - ### isUndefinedData

    public static boolean isUndefinedData(Program program, Address addr)
    Determine if the specified addr corresponds to an undefined data location where both undefined code units and defined data which has an Undefined data type is considered to be undefined.
    Parameters:
      `program` - the program
      `addr` - the data address
    Returns:
      true if the data is undefined

  - ### getNextNonUndefinedDataAfter

    public static Data getNextNonUndefinedDataAfter(Program program, Address addr, Address maxAddr)
    Get the next defined data that comes after the address indicated by addr and that is no more than the specified maxAddr and that is not a sized undefined data type.
    Parameters:
      `program` - the program whose code units are to be checked to find the next non-undefined data.
      `addr` - start looking for data after this address.
      `maxAddr` - do not look any further than this address.
    Returns:
      the next defined data that isn't a sized undefined data type, or return null if there isn't one.

  - ### findFirstConflictingAddress

    public static Address findFirstConflictingAddress(Program program, Address addr, int length, boolean ignoreUndefinedData)
    Finds the first conflicting address in the given address range.
    Parameters:
      `program` - The program.
      `addr` - The starting address of the range.
      `length` - The length of the range.
      `ignoreUndefinedData` - True if the search should ignore `Undefined` data as a potential conflict, or false if `Undefined` data should trigger conflicts.
    Returns:
      The address of the first conflict in the range, or null if there were no conflicts.

  - ### isUndefinedRange

    public static boolean isUndefinedRange(Program program, Address startAddress, Address endAddress)
    Determine if there is only undefined data from the specified startAddress to the specified endAddress. The start and end addresses must both be in the same defined block of memory.
    Parameters:
      `program` - the program whose code units are to be checked.
      `startAddress` - start looking for undefined data at this address in a defined memory block.
      `endAddress` - do not look any further than this address. This must be greater than or equal to the startAddress and must be in the same memory block as the start address or false is returned.
    Returns:
      true if the range of addresses in a memory block is where only undefined data exists.