JsonPointer
Date: 2016-12-03

com.fasterxml.jackson.core

## Class JsonPointer

- java.lang.Object
- - com.fasterxml.jackson.core.JsonPointer

-     public class JsonPointer
      extends java.lang.Object

  Implementation of JSON Pointer specification. Pointer instances can be used to locate logical JSON nodes for things like tree traversal (see `TreeNode.at(com.fasterxml.jackson.core.JsonPointer)`). It may be used in future for filtering of streaming JSON content as well (not implemented yet for 2.3).

  Instances are fully immutable and can be shared, cached.

  Since:
    2.3

- - ### Property Summary

    Properties
    Type | Property and Description
    --- | ---
    `boolean` | `mayMatch`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected java.lang.String` | `_asString` We will retain representation of the pointer, as a String, so that `toString()` should be as efficient as possible.
    `protected JsonPointer` | `_head` Reference from currently matching segment (if any) to node before leaf.
    `protected int` | `_matchingElementIndex`
    `protected java.lang.String` | `_matchingPropertyName`
    `protected JsonPointer` | `_nextSegment` Reference to rest of the pointer beyond currently matching segment (if any); null if this pointer refers to the matching segment.
    `protected static JsonPointer` | `EMPTY` Marker instance used to represent segment that matches current node or position (that is, returns true for `matches()`).

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `JsonPointer()` Constructor used for creating "empty" instance, used to represent state that matches current node.
    `protected` | `JsonPointer(java.lang.String fullString, java.lang.String segment, int matchIndex, JsonPointer next)`
    `protected` | `JsonPointer(java.lang.String fullString, java.lang.String segment, JsonPointer next)` Constructor used for creating non-empty Segments

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected JsonPointer` | `_constructHead()`
    `protected JsonPointer` | `_constructHead(int suffixLength, JsonPointer last)`
    `protected static JsonPointer` | `_parseQuotedTail(java.lang.String input, int i)` Method called to parse tail of pointer path, when a potentially escaped character has been seen.
    `protected static JsonPointer` | `_parseTail(java.lang.String input)`
    `JsonPointer` | `append(JsonPointer tail)`
    `static JsonPointer` | `compile(java.lang.String input)` Factory method that parses given input and construct matching pointer instance, if it represents a valid JSON Pointer: if not, a `IllegalArgumentException` is thrown.
    `boolean` | `equals(java.lang.Object o)`
    `int` | `getMatchingIndex()`
    `java.lang.String` | `getMatchingProperty()`
    `int` | `hashCode()`
    `JsonPointer` | `head()` Accessor for getting a pointer instance that is identical to this instance except that the last segment has been dropped.
    `JsonPointer` | `last()` Returns the leaf of current JSON Pointer expression.
    `JsonPointer` | `matchElement(int index)`
    `boolean` | `matches()`
    `boolean` | `matchesElement(int index)` Method that may be called to see if the pointer would match array element (of a JSON Array) with given index.
    `boolean` | `matchesProperty(java.lang.String name)` Method that may be called to see if the pointer would match property (of a JSON Object) with given name.
    `JsonPointer` | `matchProperty(java.lang.String name)`
    `boolean` | `mayMatchElement()`
    `boolean` | `mayMatchProperty()`
    `JsonPointer` | `tail()` Accessor for getting a "sub-pointer", instance where current segment has been removed and pointer includes rest of segments.
    `java.lang.String` | `toString()`
    `static JsonPointer` | `valueOf(java.lang.String input)` Alias for `compile(java.lang.String)`; added to make instances automatically deserializable by Jackson databind.

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

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

- - ### Property Detail

    - #### mayMatch

  - ### Field Detail

    - #### EMPTY

          protected static final JsonPointer EMPTY

      Marker instance used to represent segment that matches current node or position (that is, returns true for `matches()`).

    - #### _nextSegment

          protected final JsonPointer _nextSegment

      Reference to rest of the pointer beyond currently matching segment (if any); null if this pointer refers to the matching segment.

    - #### _head

          protected volatile JsonPointer _head

      Reference from currently matching segment (if any) to node before leaf. Lazily constructed if/as needed.

      NOTE: we'll use `volatile` here assuming that this is unlikely to become a performance bottleneck. If it becomes one we can probably just drop it and things still should work (despite warnings as per JMM regarding visibility (and lack thereof) of unguarded changes).

      Since:
        2.5

    - #### _asString

          protected final java.lang.String _asString

      We will retain representation of the pointer, as a String, so that `toString()` should be as efficient as possible.

    - #### _matchingPropertyName

          protected final java.lang.String _matchingPropertyName

    - #### _matchingElementIndex

          protected final int _matchingElementIndex

  - ### Constructor Detail

    - #### JsonPointer

          protected JsonPointer()

      Constructor used for creating "empty" instance, used to represent state that matches current node.

    - #### JsonPointer

          protected JsonPointer(java.lang.String fullString,
                     java.lang.String segment,
                     JsonPointer next)

      Constructor used for creating non-empty Segments

    - #### JsonPointer

          protected JsonPointer(java.lang.String fullString,
                     java.lang.String segment,
                     int matchIndex,
                     JsonPointer next)

      Since:
        2.5

  - ### Method Detail

    - #### compile

          public static JsonPointer compile(java.lang.String input)
                                     throws java.lang.IllegalArgumentException

      Factory method that parses given input and construct matching pointer instance, if it represents a valid JSON Pointer: if not, a `IllegalArgumentException` is thrown.
      Throws:
        `java.lang.IllegalArgumentException` - Thrown if the input does not present a valid JSON Pointer expression: currently the only such expression is one that does NOT start with a slash ('/').

    - #### valueOf

          public static JsonPointer valueOf(java.lang.String input)

      Alias for `compile(java.lang.String)`; added to make instances automatically deserializable by Jackson databind.

    - #### matches

          public boolean matches()

    - #### getMatchingProperty

          public java.lang.String getMatchingProperty()

    - #### getMatchingIndex

          public int getMatchingIndex()

    - #### mayMatchProperty

          public boolean mayMatchProperty()

    - #### mayMatchElement

          public boolean mayMatchElement()

    - #### last

          public JsonPointer last()

      Returns the leaf of current JSON Pointer expression. Leaf is the last non-null segment of current JSON Pointer.
      Since:
        2.5

    - #### append

          public JsonPointer append(JsonPointer tail)

    - #### matchesProperty

          public boolean matchesProperty(java.lang.String name)

      Method that may be called to see if the pointer would match property (of a JSON Object) with given name.
      Since:
        2.5

    - #### matchProperty

          public JsonPointer matchProperty(java.lang.String name)

    - #### matchesElement

          public boolean matchesElement(int index)

      Method that may be called to see if the pointer would match array element (of a JSON Array) with given index.
      Since:
        2.5

    - #### matchElement

          public JsonPointer matchElement(int index)

      Since:
        2.6

    - #### tail

          public JsonPointer tail()

      Accessor for getting a "sub-pointer", instance where current segment has been removed and pointer includes rest of segments. For matching state, will return null.

    - #### head

          public JsonPointer head()

      Accessor for getting a pointer instance that is identical to this instance except that the last segment has been dropped. For example, for JSON Point "/root/branch/leaf", this method would return pointer "/root/branch" (compared to `tail()` that would return "/branch/leaf"). For leaf
      Since:
        2.5

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Object`

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `java.lang.Object`

    - #### equals

          public boolean equals(java.lang.Object o)

      Overrides:
        `equals` in class `java.lang.Object`

    - #### _parseTail

          protected static JsonPointer _parseTail(java.lang.String input)

    - #### _parseQuotedTail

          protected static JsonPointer _parseQuotedTail(java.lang.String input,
                                     int i)

      Method called to parse tail of pointer path, when a potentially escaped character has been seen.
      Parameters:
        `input` - Full input for the tail being parsed
        `i` - Offset to character after tilde

    - #### _constructHead

          protected JsonPointer _constructHead()

    - #### _constructHead

          protected JsonPointer _constructHead(int suffixLength,
                                   JsonPointer last)