Package com.saxonica.xsltextn.pedigree

## Class Pedigree

- java.lang.Object
- - com.saxonica.xsltextn.pedigree.Pedigree

-     public class Pedigree
      extends java.lang.Object

  A `Pedigree` is transient information relating to a map or array indicating the route by which it was reached; it thus compensates for the absence of parent pointers in a JSON-like tree, by allowing the steps used to reach a map or array in such a structure to be retraced.

  A map or array that has a `Pedigree` is represented by a `PedigreeValue`, which is a combination of the map/array and the `Pedigree`. The `Pedigree` holds a reference to the "container" `PedigreeValue` from which this map or array was reached, and the key or index value within that container.

  Note that maps and arrays have no externally visible identity. It is not meaningful to ask whether the same map can be reached by two different routes, because there is no way to establish "sameness".

  A map or array will have a `Pedigree` if it is found by downwards selection from a map or array that itself has a `Pedigree`, or if it was explicitly created with a `Pedigree`.

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static Pedigree` | `PEDIGREE_ROOT` | An empty `Pedigree`: that is, the `Pedigree` of a map or array that was created as the root of a pedigree tree.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `Pedigree​(PedigreeValue container, int index)` | Create a pedigree for a map or array obtained by selection from an array, using an index value as a subscript into the array
    `Pedigree​(PedigreeValue container, AtomicValue key)` | Create a pedigree for a map or array obtained by selection from a map, using a key value

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `PedigreeValue` | `getContainer()` | Get the containing map or array
    `int` | `getIndex()` | Get the index if this item was obtained by selection from an array
    `AtomicValue` | `getKey()` | Get the key if this item was obtained by selection from a map
    `GroundedValue` | `makePedigreeValue​(GroundedValue value)` | Make a map or array that combines a supplied map or array with this pedigree

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

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

- - ### Field Detail

    - #### PEDIGREE_ROOT

          public static final Pedigree PEDIGREE_ROOT

      An empty `Pedigree`: that is, the `Pedigree` of a map or array that was created as the root of a pedigree tree.

  - ### Constructor Detail

    - #### Pedigree

          public Pedigree​(PedigreeValue container,
                          AtomicValue key)

      Create a pedigree for a map or array obtained by selection from a map, using a key value
      Parameters:
        `container` - the containing map
        `key` - the key value used to select an entry in the containing map

    - #### Pedigree

          public Pedigree​(PedigreeValue container,
                          int index)

      Create a pedigree for a map or array obtained by selection from an array, using an index value as a subscript into the array
      Parameters:
        `container` - the containing map
        `index` - the zero-based index value used to select a member of the containing array

  - ### Method Detail

    - #### getContainer

          public PedigreeValue getContainer()

      Get the containing map or array
      Returns:
        the containing map or array

    - #### getIndex

          public int getIndex()

      Get the index if this item was obtained by selection from an array
      Returns:
        the zero-based index if this item was obtained by selection from an array, otherwise -1.

    - #### getKey

          public AtomicValue getKey()

      Get the key if this item was obtained by selection from a map
      Returns:
        the key if this item was obtained by selection from a map, otherwise null.

    - #### makePedigreeValue

          public GroundedValue makePedigreeValue​(GroundedValue value)

      Make a map or array that combines a supplied map or array with this pedigree
      Parameters:
        `value` - the supplied value
      Returns:
        if the supplied value is a map or array, returns a map or array augmented with this pedigree. Otherwise, returns the supplied value unchanged.