Package ghidra.program.util

# Class ProgramLocation

java.lang.Object
ghidra.program.util.ProgramLocation

All Implemented Interfaces:
  `Cloneable`, `Comparable<ProgramLocation>`

Direct Known Subclasses:
  `AssignedVariableLocation`, `CodeUnitLocation`, `DefaultDecompilerLocation`, `DividerLocation`, `FunctionLocation`, `FunctionPurgeFieldLocation`, `InstructionMaskValueFieldLocation`, `ParallelInstructionLocation`, `PcodeFieldLocation`, `RegisterFieldLocation`, `RegisterTransitionFieldLocation`, `SourceMapFieldLocation`, `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 Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected Address`
  `addr`
  `protected Program`
  `program`
  `protected Address`
  `refAddr`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ProgramLocation()`
  Default constructor required for restoring a program location from XML.
  `ProgramLocation(Program program, Address addr)`
  Construct a new ProgramLocation for the given address.
  `ProgramLocation(Program program, Address addr, int[] componentPath, Address refAddr, int row, int col, int charOffset)`
  Construct a new ProgramLocation for the given address.
  `ProgramLocation(Program program, Address addr, int row, int col, int charOffset)`
  Construct a new ProgramLocation for the given address.
  `ProgramLocation(Program program, Address addr, Address refAddr)`
  Construct a new ProgramLocation for the given address.
  `ProgramLocation(Program program, Address addr, Address byteAddr, int[] componentPath, Address refAddr, int row, int col, int charOffset)`
  Construct a new ProgramLocation.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected final Object`
  `clone()`
  `protected static int`
  `compareAddr(Address addr1, Address addr2)`
  `int`
  `compareTo(ProgramLocation other)`
  `boolean`
  `equals(Object obj)`
  `Address`
  `getAddress()`
  Returns the address associated with this location.
  `Address`
  `getByteAddress()`
  Returns the byte level address associated with this location.
  `int`
  `getCharOffset()`
  Returns the character offset in the display item at the (row,col).
  `int`
  `getColumn()`
  Returns the column index of the display piece represented by this location.
  `int[]`
  `getComponentPath()`
  Returns the componentPath for the `code unit`.
  `static ProgramLocation`
  `getLocation(Program program, SaveState saveState)`
  Get the program location for the given program and save state object.
  `Program`
  `getProgram()`
  Returns the program associated with this location.
  `Address`
  `getRefAddress()`
  Returns the "referred to" address if the location is over an address in some field.
  `int`
  `getRow()`
  Returns the row within the program location.
  `static ProgramLocation`
  `getTranslatedCopy(ProgramLocation loc, Program program, Address translatedAddress)`
  Create a new translated copy of the specified `ProgramLocation` using the specified `program`
  `int`
  `hashCode()`
  `boolean`
  `isValid(Program testProgram)`
  Returns true if this location represents a valid location in the given program.
  `void`
  `restoreState(Program newProgram, SaveState obj)`
  Restore this program location using the given program and save state object.
  `void`
  `saveState(SaveState obj)`
  Save this program location to the given save state object.
  `String`
  `toString()`

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

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

- ## Field Details

  - ### program

    protected Program program

  - ### addr

    protected Address addr

  - ### refAddr

    protected Address refAddr

- ## 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 newProgram, SaveState obj)
    Restore this program location using the given program and save state object.
    Parameters:
      `newProgram` - 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