value::try_set_at_pointer

## `value::try_set_at_pointer`

Set an element via JSON Pointer.

### Synopsis

    boost::system::result< value & >
    try_set_at_pointer(
        string_view sv,
        value_ref ref,
        set_pointer_options const& opts = {});

### Description

This function is used to insert or assign to a potentially nested element of the value using a JSON Pointer string. The function may create intermediate elements corresponding to pointer segments.

The particular conditions when and what kind of intermediate element is created is governed by the `ptr` parameter.

Each pointer token is considered in sequence. For each token

- if the containing value is an `object`, then a new `null` element is created with key equal to unescaped token string; otherwise

- if the containing value is an `array`, and the token represents a past-the-end marker, then a `null` element is appended to the array; otherwise

- if the containing value is an `array`, and the token represents a number, then if the difference between the number and array’s size is smaller than `opts.max_created_elements`, then the size of the array is increased, so that the number can reference an element in the array; otherwise

- if the containing value is of different `kind` and `opts.replace_any_scalar` is `true`, or the value is `null`, then

  - if `opts.create_arrays` is `true` and the token either represents past-the-end marker or a number, then the value is replaced with an empty array and the token is considered again; otherwise

  - if `opts.create_objects` is `true`, then the value is replaced with an empty object and the token is considered again; otherwise

- an error is produced.

### Complexity

Linear in the sum of size of `ptr`, size of underlying array, object, or string and `opts.max_created_elements`.

### Exception Safety

Basic guarantee. Calls to `memory_resource::allocate` may throw.

### Return Value

`boost::system::result` containing either a reference to the element identified by `ptr` or a corresponding `error_code`.

### Parameters

Name | Description
--- | ---
`sv` | JSON Pointer string.
`ref` | The value to assign to pointed element.
`opts` | The options for the algorithm.

### See Also

`set_pointer_options`, RFC 6901 - JavaScript Object Notation (JSON) Pointer.

Edit this page