| Home | Libraries | People | FAQ | More

###### value::set_at_pointer (1 of 3 overloads)

Set an element via JSON Pointer.

###### Synopsis

    value*
    set_at_pointer(
        string_view sv,
        value_ref ref,
        error_code& ec,
        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.

###### Parameters

Name | Description
--- | ---
`sv` | JSON Pointer string.
`ref` | The value to assign to pointed element.
`ec` | Set to the error, if any occurred.
`opts` | The options for the algorithm.

###### Return Value

Pointer to the element identified by `ptr`.

###### See Also

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