Package ghidra.program.util

Class ProgramLocation

java.lang.Object
ghidra.program.util.ProgramLocation
All Implemented Interfaces:
Cloneable, Comparable<ProgramLocation>
Direct Known Subclasses:
AssignedVariableLocation, CodeUnitLocation, DecompilerLocation, DividerLocation, FunctionLocation, FunctionPurgeFieldLocation, InstructionMaskValueFieldLocation, ParallelInstructionLocation, PcodeFieldLocation, RegisterFieldLocation, RegisterTransitionFieldLocation, StackDepthFieldLocation
public class ProgramLocation extends Object implements Cloneable, Comparable<ProgramLocation>
ProgramLocation provides information about a location in a program in the most generic way.

ProgramLocations refer to a specific location in a program and can be specified down to an address, a field at that address, and within that field, a row, col, and character offset. The field is not recorded directly, but by the subclass of the ProgramLocation. The "cursor position" within a field is specified by three variables: row, col, and character offset. The row is literally the row (line #) the cursor is on within the field, the column represents the display item on that row (For example, in the bytes field the column will represent which "byte" the cursor is on. Most fields only have one column item per row.) And finally, the character offset is the character position within the display item specified by the row and column. Simple fields like the address field and Mnemonic field will always have a row and column of 0.

  • Field Details

  • Constructor Details

    • ProgramLocation

      public ProgramLocation(Program program, Address addr, Address byteAddr, int[] componentPath, Address refAddr, int row, int col, int charOffset)
      Construct a new ProgramLocation.
      Parameters:
      program - the program of the location
      addr - address of the location; cannot be null; This could be a code unit minimum address where the byteAddr is within the code unit.
      byteAddr - address of the location; cannot be null
      componentPath - array of indexes for each nested data component; the data index is the data component's index within its parent; may be null
      refAddr - the "referred to" address if the location is over a reference; may be null
      row - the row within the field.
      col - the display item index on the given row. (Note most fields only have one display item per row)
      charOffset - the character offset within the display item.
      Throws:
      NullPointerException - if addr or program is null

    • ProgramLocation

      public ProgramLocation(Program program, Address addr, int[] componentPath, Address refAddr, int row, int col, int charOffset)
      Construct a new ProgramLocation for the given address. The address will be adjusted to the beginning of the code unit containing that address (if it exists). The original address can be retrieved using the getByteAddress()" method.
      Parameters:
      program - the program associated with this program location (also used to obtain a code-unit-aligned address)
      addr - address of the location; cannot be null
      componentPath - array of indexes for each nested data component; the index is the data component's index within its parent; may be null
      refAddr - the "referred to" address if the location is over a reference; may be null
      row - the row within the field.
      col - the display item index on the given row. (Note most fields only have one display item per row)
      charOffset - the character offset within the display item.
      Throws:
      NullPointerException - if addr or program is null

    • ProgramLocation

      public ProgramLocation(Program program, Address addr)
      Construct a new ProgramLocation for the given address. The address will be adjusted to the beginning of the code unit containing that address (if it exists). The original address can be retrieved using the getByteAddress() method.
      Parameters:
      program - the program associated with this program location (also used to obtain a code-unit-aligned address)
      addr - address for the location
      Throws:
      NullPointerException - if addr or program is null

    • ProgramLocation

      public ProgramLocation(Program program, Address addr, int row, int col, int charOffset)
      Construct a new ProgramLocation for the given address. The address will be adjusted to the beginning of the code unit containing that address (if it exists). The original address can be retrieved using the getByteAddress() method.
      Parameters:
      program - the program associated with this program location (also used to obtain a code-unit-aligned address)
      addr - address for the location
      row - the row within the field.
      col - the display item index on the given row. (Note most fields only have one display item per row)
      charOffset - the character offset within the display item.
      Throws:
      NullPointerException - if addr or program is null

    • ProgramLocation

      public ProgramLocation(Program program, Address addr, Address refAddr)
      Construct a new ProgramLocation for the given address. The address will be adjusted to the beginning of the code unit containing that address (if it exists). The original address can be retrieved using the getByteAddress() method.
      Parameters:
      program - the program associated with this program location (also used to obtain a code-unit-aligned address)
      addr - address for the location
      refAddr - the "referred to" address if the location is over a reference
      Throws:
      NullPointerException - if addr or program is null

    • ProgramLocation

      public ProgramLocation()
      Default constructor required for restoring a program location from XML.

  • Method Details

    • getComponentPath

      public int[] getComponentPath()
      Returns the componentPath for the code unit. Null will be returned if the object is an Instruction or a top-level Data object.
      Returns:
      the path.

    • getProgram

      public Program getProgram()
      Returns the program associated with this location.
      Returns:
      the program.

    • getAddress

      public Address getAddress()
      Returns the address associated with this location.

      Note: this may not be the same as the byte address. For example, in a code unit location this may be the minimum address of the code unit that contains the byte address.

      Returns:
      the address.

    • getByteAddress

      public Address getByteAddress()
      Returns the byte level address associated with this location.
      Returns:
      the byte address.

    • getRefAddress

      public Address getRefAddress()
      Returns the "referred to" address if the location is over an address in some field.
      Returns:
      the address.

    • saveState

      public void saveState(SaveState obj)
      Save this program location to the given save state object.
      Parameters:
      obj - the save state object for saving the location

    • restoreState

      public void restoreState(Program program1, SaveState obj)
      Restore this program location using the given program and save state object.
      Parameters:
      program1 - program to restore from
      obj - the save state to restore from

    • getLocation

      public static ProgramLocation getLocation(Program program, SaveState saveState)
      Get the program location for the given program and save state object.
      Parameters:
      program - the program for the location
      saveState - the state to restore
      Returns:
      the restored program location

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object

    • compareTo

      public int compareTo(ProgramLocation other)
      Specified by:
      compareTo in interface Comparable<ProgramLocation>

    • compareAddr

      protected static int compareAddr(Address addr1, Address addr2)

    • isValid

      public boolean isValid(Program testProgram)
      Returns true if this location represents a valid location in the given program.
      Parameters:
      testProgram - the program to test if this location is valid.
      Returns:
      true if this location represents a valid location in the given program.

    • getRow

      public int getRow()
      Returns the row within the program location.
      Returns:
      the row within the program location.

    • getColumn

      public int getColumn()
      Returns the column index of the display piece represented by this location. For most locations, there is only one display item per row, in which case this value will be 0.
      Returns:
      the column.

    • getCharOffset

      public int getCharOffset()
      Returns the character offset in the display item at the (row,col).
      Returns:
      the character offset in the display item at the (row,col).

    • clone

      protected final Object clone() throws CloneNotSupportedException
      Overrides:
      clone in class Object
      Throws:
      CloneNotSupportedException

    • getTranslatedCopy

      public static ProgramLocation getTranslatedCopy(ProgramLocation loc, Program program, Address translatedAddress)
      Create a new translated copy of the specified ProgramLocation using the specified program
      Parameters:
      loc - original program location
      program - updated program
      translatedAddress - original loc address translated for using within specified program
      Returns:
      translated program location