Class: RecordElementPointer

x2node-pointers~ RecordElementPointer

Record element pointer, which is an implementation of RFC 6901 JSON Pointer.

new RecordElementPointer(parent, pointerToken, propDesc, propPath, collectionElement [, collectionElementIndex], childrenContainer)

Note: The constructor is not accessible from the client code. Prointer instances are created using module's parse() function.
Parameters:
Name Type Argument Description
parent module:x2node-pointers~RecordElementPointer <nullable>
Parent pointer, or null for the root pointer.
pointerToken string <nullable>
Pointer token (no dash, no tilda escapes), or null if root pointer.
propDesc module:x2node-records~PropertyDescriptor <nullable>
Descriptor of the property, at which the pointer points, or null for the root pointer.
propPath string Path to the property, at which the pointer points, or empty string for the root pointer.
collectionElement boolean true if the pointer is for an array or map element.
collectionElementIndex string | number <optional>
If collection element pointer, this collection element index.
childrenContainer module:x2node-records~PropertiesContainer <nullable>
Child properties container, if applicable.

Members


<readonly> collectionElement :boolean

true if the pointer is for an array or map element.
Type:
  • boolean

<readonly> collectionElementIndex :number|string

For a collection element pointer (collectionElement is true), the element index, which, for an array element, is a number or a dash ("-") and for a map element—the map key string.
Type:
  • number | string

<readonly, nullable> parent :module:x2node-pointers~RecordElementPointer

Pointer for the parent record element, or null if root pointer.
Type:

<readonly, nullable> propDesc :module:x2node-records~PropertyDescriptor

Descriptor of the property, at which the pointer points, or null if root pointer.
Type:

<readonly> propPath :string

Path of the property, at which the pointer points, or empty string if root pointer.
Type:
  • string

Methods


addValue(record, value)

Add value to the property, at which the pointer points. If the pointer points at an array element, the value is inserted into the array at the specified by the pointer location. In all other cases, any existing value is simply replaced.

Note, that the method is not allowed on the root pointer.

Parameters:
Name Type Description
record Object The record.
value * The value to add. May not be undefined (use removeValue() method to delete optional property values). A null is not allowed for nested object array and map elements. The method does not validate the value in any other way beyond that.
Throws:
Returns:
The previous value as if getValue() was called for the pointer before modifying the record.
Type
*

createChildPointer(pointerToken)

Create immediate child pointer of this pointer. This is faster than parsing the pointer from string notation as it does not have to re-parse the prefix.
Parameters:
Name Type Description
pointerToken string Token to append to the pointer to form the child pointer (without the leading slash).
Throws:
If resulting pointer would be invalid.
Type
module:x2node-common.X2UsageError
Returns:
Child pointer.
Type
module:x2node-pointers~RecordElementPointer

getValue(record [, traceFunc])

Get value of the property, at which the pointer points.
Parameters:
Name Type Argument Description
record Object The record, from which to get the value. Must match the pointer's record type.
traceFunc module:x2node-pointers~RecordElementPointer~traceCallback <optional>
Optional trace callback called for every prefix pointer starting from the root pointer and ending with this pointer.
Throws:
If the property cannot be reached.
Type
module:x2node-common.X2DataError
Returns:
The property value, or null if no value. For absent array and map elements returns undefined.
Type
*

isChildOf(otherPtr)

Tell if this pointer points to a child of the specified other pointer (that is the other pointer is a "proper prefix" of this pointer).
Parameters:
Name Type Description
otherPtr module:x2node-pointers~RecordElementPointer The other pointer.
Returns:
true if child.
Type
boolean

isRoot()

Tell if the pointer is the root pointer. Equivalent for checking if parent is null.
Returns:
true If root pointer.
Type
boolean

removeValue(record)

Erase the property, at which the pointer points. If the pointer points at an array element, the element is deleted from the array.

Note, that the method is not allowed on the root pointer. Also, not allowed for a dash array element pointer.

Parameters:
Name Type Description
record Object The record.
Throws:
Returns:
The previous value as if getValue() was called for the pointer before modifying the record.
Type
*

replaceValue(record, value)

Replace value of the property, at which the pointer points.

Note, that the method is not allowed on the root pointer. Also, not allowed for a dash array element pointer.

Parameters:
Name Type Description
record Object The record.
value * The value to set. May not be undefined (use removeValue() method to delete optional property values). A null is not allowed for nested object array and map elements. The method does not validate the value in any other way beyond that.
Throws:
Returns:
The previous value as if getValue() was called for the pointer before modifying the record.
Type
*

toString()

Get string representation of the pointer in the RFC 6901 format.
Returns:
The pointer string (empty string for the root pointer).
Type
string

Type Definitions


traceCallback(prefixPtr, value, prefixDepth)

Callback for the trace method.
Parameters:
Name Type Description
prefixPtr module:x2node-pointers~RecordElementPointer The pointer representing the current pointer prefix. During a trace call, the callback is first called with the root pointer as the prefixPtr and last called with the actual pointer being traced (the leaf pointer).
value * The value at the current prefixPtr in the record.
prefixDepth number Current prefix depth. For the leaf pointer it is zero, one for the immediate parent pointer, and so on.