Package ghidra.trace.model.target.path

# Class KeyPath

java.lang.Object
ghidra.trace.model.target.path.KeyPath

All Implemented Interfaces:
  `Comparable<KeyPath>`, `Iterable<String>`

public final class KeyPath extends Object implements Comparable<KeyPath>, Iterable<String>
An immutable path of keys leading from one object (usually the root) object to another

Often, the source is the root. These are often taken as a parameter when searching for values. In essence, they simply wrap a list of string keys, but it provides convenience methods, sensible comparison, and better typing.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static enum`
  `KeyPath.KeyComparator`
  Comparators for keys, i.e., strings in a path
  `static enum`
  `KeyPath.PathComparator`
  Comparators for paths
  `static class`
  `KeyPath.PathParser`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final KeyPath`
  `ROOT`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `int`
  `compareTo(KeyPath that)`
  `boolean`
  `containsWildcard()`
  `int`
  `countWildcards()`
  `boolean`
  `equals(Object obj)`
  `KeyPath`
  `extend(KeyPath sub)`
  Create a new path by appending the given list of keys
  `KeyPath`
  `extend(String... subKeys)`
  Create a new path by appending the given keys
  `int`
  `hashCode()`
  `String`
  `index()`
  Get the final index of this path
  `KeyPath`
  `index(long index)`
  Create a new path by appending the given element index
  `KeyPath`
  `index(String index)`
  Create a new path by appending the given element index
  `boolean`
  `isAncestor(KeyPath successor)`
  Check if this path is an ancestor of the given path
  `static boolean`
  `isIndex(String key)`
  Check if the given key is a bracketed index
  `static boolean`
  `isName(String key)`
  Check if the given key is an attribute name, i.e., not an index
  `boolean`
  `isRoot()`
  Assuming the source is the root, check if this path refers to that root
  `Iterator<String>`
  `iterator()`
  `String`
  `key()`
  Get the final key of this path
  `String`
  `key(int i)`
  `KeyPath`
  `key(String name)`
  Create a new path by appending the given key
  `static String`
  `makeIndex(long i)`
  Encode the given index in decimal, without brackets
  `static String`
  `makeKey(String index)`
  Encode the given index as a key
  `static KeyPath`
  `of(String... keys)`
  Create a path from the given keys
  `static KeyPath`
  `of(List<String> keyList)`
  Create a path from the given list of keys
  `static KeyPath`
  `of(Stream<String> keyStream)`
  `KeyPath`
  `parent()`
  Create a new path by removing the final key
  `KeyPath`
  `parent(int n)`
  Create a new path by removing the final `n` keys
  `static KeyPath`
  `parse(String path)`
  Parse a path from the given string
  `static String`
  `parseIfIndex(String key)`
  If an index, parse it, otherwise just return the key
  `static String`
  `parseIndex(String key)`
  Parse an index value from a key
  `KeyPath`
  `relativize(KeyPath successor)`
  Assuming this is an ancestor of the given successor, compute the relative path from here to there
  `int`
  `size()`
  `Stream<KeyPath>`
  `streamMatchingAncestry(PathFilter filter)`
  Stream, starting with the longer paths, paths that match the given predicates
  `List<String>`
  `toList()`
  Get the (immutable) list of keys from source to destination
  `String`
  `toString()`

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

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

  ### Methods inherited from interface java.lang.Iterable

  `forEach, spliterator`

- ## Field Details

  - ### ROOT

    public static final KeyPath ROOT

- ## Method Details

  - ### makeIndex

    public static String makeIndex(long i)
    Encode the given index in decimal, without brackets
    Parameters:
      `i` - the numeric index
    Returns:
      the encoded index

  - ### isIndex

    public static boolean isIndex(String key)
    Check if the given key is a bracketed index
    Parameters:
      `key` - the key to check
    Returns:
      true if it is an index

  - ### isName

    public static boolean isName(String key)
    Check if the given key is an attribute name, i.e., not an index
    Parameters:
      `key` - the key to check
    Returns:
      true if it is an attribute name

  - ### parseIndex

    public static String parseIndex(String key)
    Parse an index value from a key

    Where key is the form `[index]`, this merely returns `index`.

    Parameters:
      `key` - the key
    Returns:
      the index
    Throws:
      `IllegalArgumentException` - if key is not of the required form

  - ### parseIfIndex

    public static String parseIfIndex(String key)
    If an index, parse it, otherwise just return the key
    Parameters:
      `key` - the key
    Returns:
      the index or key

  - ### makeKey

    public static String makeKey(String index)
    Encode the given index as a key

    When indexing elements, no brackets are needed. The brackets become necessary when used as a key, e.g., when specifying an index within a path, or as keys in a map of all children.

    Parameters:
      `index` - the index
    Returns:
      the key, specifying an element.

  - ### of

    public static KeyPath of(List<String> keyList)
    Create a path from the given list of keys
    Parameters:
      `keyList` - the list of keys from source to destination
    Returns:
      the path

  - ### of

    public static KeyPath of(Stream<String> keyStream)

  - ### of

    public static KeyPath of(String... keys)
    Create a path from the given keys
    Parameters:
      `keys` - the keys from source to destination
    Returns:
      the path

  - ### parse

    public static KeyPath parse(String path)
    Parse a path from the given string
    Parameters:
      `path` - the dot-separated keys from source to destination
    Returns:
      the path

  - ### hashCode

    public int hashCode()
    Overrides:
      `hashCode` in class `Object`

  - ### compareTo

    public int compareTo(KeyPath that)
    Specified by:
      `compareTo` in interface `Comparable<KeyPath>`

  - ### equals

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

  - ### size

    public int size()

  - ### iterator

    public Iterator<String> iterator()
    Specified by:
      `iterator` in interface `Iterable<String>`

  - ### key

    public String key(int i)

  - ### toList

    public List<String> toList()
    Get the (immutable) list of keys from source to destination
    Returns:
      the key list

  - ### containsWildcard

    public boolean containsWildcard()

  - ### countWildcards

    public int countWildcards()

  - ### isRoot

    public boolean isRoot()
    Assuming the source is the root, check if this path refers to that root
    Returns:
      true if the path is empty, false otherwise

  - ### key

    public KeyPath key(String name)
    Create a new path by appending the given key

    For example, if this path is "`Processes[2]`" and `name` takes the value "`Threads`", the result will be "`Processes[2].Threads`".

    Parameters:
      `name` - the new final key
    Returns:
      the resulting path

  - ### key

    public String key()
    Get the final key of this path
    Returns:
      the final key

  - ### index

    public KeyPath index(long index)
    Create a new path by appending the given element index

    For example, if this path is "`Processes`" and `index` takes the value 2, the result will be "`Processes[2]`".

    Parameters:
      `index` - the new final index
    Returns:
      the resulting path

  - ### index

    public KeyPath index(String index)
    Create a new path by appending the given element index

    This does the same as `key(String)` but uses brackets instead. For example, if this path is "`Processes[2].Threads[0].Registers`" and `index` takes the value "`RAX`", the result will be "`Processes[2].Threads[0].Registers[RAX]"`.

    Parameters:
      `index` - the new final index
    Returns:
      the resulting path

  - ### index

    public String index()
    Get the final index of this path
    Returns:
      the final index
    Throws:
      `IllegalArgumentException` - if the final key is not an index, i.e., in brackets

  - ### toString

    public String toString()

    Gives the dot-joined path

    Overrides:
      `toString` in class `Object`

  - ### parent

    public KeyPath parent()
    Create a new path by removing the final key
    Returns:
      the resulting path, or null if this path is empty

  - ### parent

    public KeyPath parent(int n)
    Create a new path by removing the final `n` keys
    Parameters:
      `n` - the number of keys to remove
    Returns:
      the resulting path, or null if fewer than 0 keys would remain

  - ### extend

    public KeyPath extend(KeyPath sub)
    Create a new path by appending the given list of keys

    For example, if this path is "`Processes[2]`" and `sub` takes the value "`Threads[0]`", the result will be "`Processes[2].Threads[0]`".

    Parameters:
      `sub` - the path to append
    Returns:
      the resulting path

  - ### extend

    public KeyPath extend(String... subKeys)
    Create a new path by appending the given keys
    Parameters:
      `subKeys` - the keys to append
    Returns:
      the resulting path
    See Also:
      - `extend(KeyPath)`

  - ### streamMatchingAncestry

    public Stream<KeyPath> streamMatchingAncestry(PathFilter filter)
    Stream, starting with the longer paths, paths that match the given predicates
    Parameters:
      `filter` - the predicates to filter the ancestor paths
    Returns:
      the stream of matching paths, longest to shortest

  - ### isAncestor

    public boolean isAncestor(KeyPath successor)
    Check if this path is an ancestor of the given path

    Equivalently, check if the given path is a successor of this path. A path is considered an ancestor of itself. To check for a strict ancestor, use `this.isAncestor(that) && !this.equals(that)`.

    Parameters:
      `successor` - the supposed successor to this path
    Returns:
      true if the given path is in fact a successor

  - ### relativize

    public KeyPath relativize(KeyPath successor)
    Assuming this is an ancestor of the given successor, compute the relative path from here to there
    Parameters:
      `successor` - the successor
    Returns:
      the relative path