JsPath (json-values 11.5.0 API)

java.lang.Object
- jsonvalues.JsPath

All Implemented Interfaces:: Comparable<JsPath>

public final class JsPath
extends Object
implements Comparable<JsPath>

 Represents the full path location of an element in a json. It's a list of Position. Exists
 two different ways to create a JsPath:
 - From a path-like string using the static factory method path(String), where the path
 follows the Json Pointer specification RFC 6901.
 In order to be able to use paths to put data in a Json, keys which name are numbers have to
 to be single-quoted:
 
 a={"0": true}
 b=[false]
 
 According to the rfc 6901:
 the pointer /0 points to true in a, and to false in b.
 In json-values it's slightly different:
 /0 points to false in b, and /'0' points to true in a.
 It's necessary to make that distinction because otherwise, there are scenarios when there is no way
 to know if the user wants to insert an array or an object:
  <script>
 JsObj obj = empty.put("/a/0/0",true)
 obj = {"a":[[true]]}       //valid result according to the rfc and json-values
 obj = {"a":{"0":{"0":true} //valid result according to the rfc
  <script>
 - By the API, using the methods fromKey(String) and fromIndex(int) to create
 a JsPath and then the methods index(int) and key(String) to append keys or indexes:
  <script>
 JsPath a = JsPath.fromKey("a").index(0).key("b") =  /a/0/b
 JsPath b = JsPath.fromIndex(0).key("a").index(0) =  /0/a/0
  <script>
 For example, given the following Json object:
 {
 "a": { "x":[ {"c": [1,2, { "": { "1" : true, " ": false, "'": 4} }]} ]}}
 "1": null,
 "": ""
 }
 / = ""                      //an empty string is a valid name for a key
 /'1' = null                 //numeric keys have to be single-quoted
 /a/x/0/c/0 = 1
 /a/x/0/c/1 = 2
 /a/x/0/c/2//'1' = true      // single quotes are only mandatory when the key is a number
 according to the rfc, # at the beginning indicates that the path is a fragment of an url and
 therefore the keys have to be url-encoded:
 #/a/x/0/c/2//+" = false     // + is url-decoded to the white-space
 #/a/x/0/c/2//%27" = 4       // %27 is url-decoded to '
 and using the API:
  <script>
 fromKey("") = ""
 fromKey("1") = null
 fromKey("a").key("x").index(0).key("c").index(0) = 1
 fromKey("a").key("x").index(0).key("c").index(1) = 2
 fromKey("a").key("x").index(0).key("c").index(2).key("").key("1") = true
 fromKey("a").key("x").index(0).key("c").index(2).key("").key(" ") = false
 fromKey("a").key("x").index(0).key("c").index(2).key("").key("'") = 4
  <script>

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`JsPath`	`append(JsPath path)` Creates a new JsPath appending the given path to this path.
`int`	`compareTo(JsPath that)` Compares this path with another given as a parameter by comparing in order each of their positions, one by one, until a result different from zero is returned or all the positions of any path are consumed.
`JsPath`	`dec()` Returns a new path decrementing the last index by one, throwing an UserError if the last Position is not an index
`static JsPath`	`empty()` Returns the singleton empty path.
`boolean`	`endsWith(JsPath path)` returns true if this path ends with the given path.
`boolean`	`equals(Object that)` Indicates whether some other object is "equal to" this path
`static JsPath`	`fromIndex(int i)` returns a path from an index
`static JsPath`	`fromKey(String key)` returns a path from a key
`int`	`hashCode()` Returns the hashcode of this path
`Position`	`head()` Returns the head of this path if it's not empty, throwing an exception otherwise.
`JsPath`	`inc()` Returns a new path incrementing the last index by one, throwing an UserError if the last Position is not an index
`JsPath`	`index(int i)` Returns a new path appending an index with the given value to the back of this path.
`JsPath`	`init()` Returns a new path without the last Position of this path.
`boolean`	`isEmpty()` Returns true if the path is empty.
`JsPath`	`key(String key)` creates a new JsPath appending the key to `this` JsPath.
`Position`	`last()` returns the last position `this` JsPath if it's not empty or an exception otherwise.
`JsPath`	`mapKeys(UnaryOperator<String> map)` Creates a new JsPath applying the given map function to every key of this path.
`static JsPath`	`path(String path)`
`JsPath`	`prepend(JsPath path)` Creates a new JsPath prepending the given path to this path.
`int`	`size()` Returns the number of Position (keys and indexes) of `this` JsPath
`boolean`	`startsWith(JsPath path)` returns true if this path starts with the given path.
`Stream<Position>`	`stream()` Returns a sequential `Stream` of Positions with this path as its source.
`JsPath`	`tail()` Returns a JsPath without the head of this JsPath
`String`	`toString()` Returns a string representation of this path following the format defined in the RFC 6901 with the exception that keys which names are numbers are single-quoted.

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Method Detail
  - empty
```
public static JsPath empty()
```
    Returns the singleton empty path.
    
    Returns:
    
    the singleton empty path
  - fromIndex
```
public static JsPath fromIndex(int i)
```
    returns a path from an index
    
    Parameters:
    
    i - the index
    
    Returns:
    
    a new JsPath
  - path
```
public static JsPath path(String path)
```
  - fromKey
```
public static JsPath fromKey(String key)
```
    returns a path from a key
    
    Parameters:
    
    key - the name of the key
    
    Returns:
    
    a new JsPath
  - key
```
public JsPath key(String key)
```
    creates a new JsPath appending the key to this JsPath.
    
    Parameters:
    
    key - the key name to be appended in raw, without encoding nor single-quoting like in path(String) )}
    
    Returns:
    
    a JsPath with the key appended to the back
  - compareTo
```
public int compareTo(JsPath that)
```
    Compares this path with another given as a parameter by comparing in order each of their positions, one by one, until a result different from zero is returned or all the positions of any path are consumed.
    
    Specified by:
    
    compareTo in interface Comparable<JsPath>
    
    Parameters:
    
    that - the given path
    
    Returns:
    
    1 if this is greater than that, -1 if this is lower than that, 0 otherwise
    
    See Also:
    
    index.compareTo(position), key.compareTo(position)
  - head
```
public Position head()
```
    Returns the head of this path if it's not empty, throwing an exception otherwise.
    
    Returns:
    
    the head of the path witch is an object of type Position representing and Index or a Key
    
    Throws:
    
    UserError - if the path is empty
  - stream
```
public Stream<Position> stream()
```
    Returns a sequential Stream of Positions with this path as its source.
    
    Returns:
    
    stream of Positions of this path
  - inc
```
public JsPath inc()
```
    Returns a new path incrementing the last index by one, throwing an UserError if the last Position is not an index
    
    Returns:
    
    a new JsPath with the last index incremented by one
    
    Throws:
    
    UserError - if the last position is not an Index
  - last
```
public Position last()
```
    returns the last position this JsPath if it's not empty or an exception otherwise.
    
    Returns:
    
    the last position the JsPath witch is an object of type Position representing and Index or a Key
    
    Throws:
    
    UserError - if the JsPath is empty
  - index
```
public JsPath index(int i)
```
    Returns a new path appending an index with the given value to the back of this path.
    
    Parameters:
    
    i - the value of the index to be appended
    
    Returns:
    
    a new JsPath with the Index appended to the back
  - init
```
public JsPath init()
```
    Returns a new path without the last Position of this path.
    
    Returns:
    
    a new JsPath without the last Position of this JsPath
    
    Throws:
    
    UserError - if the JsPath is empty
  - isEmpty
```
public boolean isEmpty()
```
    Returns true if the path is empty. An empty path represents the empty key
    
    Returns:
    
    true if this path is empty, false otherwise
  - dec
```
public JsPath dec()
```
    Returns a new path decrementing the last index by one, throwing an UserError if the last Position is not an index
    
    Returns:
    
    a new JsPath with the last index decremented by one
    
    Throws:
    
    UserError - if the last position is not an Index
  - size
```
public int size()
```
    Returns the number of Position (keys and indexes) of this JsPath
    
    Returns:
    
    the number of Position (keys and indexes) of this JsPath
  - tail
```
public JsPath tail()
```
    Returns a JsPath without the head of this JsPath
    
    Returns:
    
    a JsPath without the head of this JsPath
    
    Throws:
    
    UserError - if the JsPath is empty
  - mapKeys
```
public JsPath mapKeys(UnaryOperator<String> map)
```
    Creates a new JsPath applying the given map function to every key of this path.
    
    Parameters:
    
    map - the given map function
    
    Returns:
    
    a new JsPath with all its Keys mapped with the given function
  - append
```
public JsPath append(JsPath path)
```
    Creates a new JsPath appending the given path to this path.
    
    Parameters:
    
    path - the given JsPath to be appended
    
    Returns:
    
    a new JsPath with the given JsPath appended to this JsPath
  - prepend
```
public JsPath prepend(JsPath path)
```
    Creates a new JsPath prepending the given path to this path.
    
    Parameters:
    
    path - the given path to be prepended
    
    Returns:
    
    a new JsPath with the given JsPath prepended to this JsPath
  - startsWith
```
public boolean startsWith(JsPath path)
```
    returns true if this path starts with the given path. If the given path is JsPath.empty(), it always returns true
    
    Parameters:
    
    path - the given path
    
    Returns:
    
    true if this JsPath starts with the given JsPath
  - endsWith
```
public boolean endsWith(JsPath path)
```
    returns true if this path ends with the given path. If the given path is JsPath.empty(), it always returns true
    
    Parameters:
    
    path - the given path
    
    Returns:
    
    true if this JsPath ends with the given JsPath
  - hashCode
```
public int hashCode()
```
    Returns the hashcode of this path
    
    Overrides:
    
    hashCode in class Object
    
    Returns:
    
    hashcode of this JsPath
  - equals
```
public boolean equals(Object that)
```
    Indicates whether some other object is "equal to" this path
    
    Overrides:
    
    equals in class Object
    
    Parameters:
    
    that - the reference object with which to compare.
    
    Returns:
    
    true if that is a JsPath which represents the same location as this JsPath
  - toString
```
public String toString()
```
    Returns a string representation of this path following the format defined in the RFC 6901 with the exception that keys which names are numbers are single-quoted. Example: /a/b/0/'1'/
    
    Overrides:
    
    toString in class Object
    
    Returns:
    
    a string representation of this JsPath following the RFC 6901

Class JsPath

Method Summary

Methods inherited from class java.lang.Object

Method Detail

empty

fromIndex

path

fromKey

key

compareTo

head

stream

inc

last

index

init

isEmpty

dec

size

tail

mapKeys

append

prepend

startsWith

endsWith

hashCode

equals

toString