BSON Modifying

BSON Modifying#

<bson/mut.h> (header file)#

Contains types and APIs for manipulating bson_doc objects.

Types#

struct bson_mut#

A BSON document mutator.

C++ API:

bson::mutator

Zero-initialized:

A zero-initialized bson_mut has no defined semantics and should not be used.

Header:

bson/mut.h

A bson_mut is created using bson_mutate() or may come from another API that derives a new bson_mut from an existing bson_mut.

Important

The mutator retains a pointer to the object from which it was created. It is essential that the parent object remain in-place while a mutator is in use.

class bson::mutator#

A BSON document mutator.

C API:

bson_mut

Important

The mutator retains a pointer to the object from which it was created. It is essential that the parent object remain in-place while a mutator is in use.

mutator(document&)#
mutator(bson_doc&)#

Creates a new mutator for the given object.

iterator begin() const#
iterator end() const#
iterator find(std::string_view) const#
bson_byte *data() const#
std::uint32_t byte_size() const#

See also

bson_mut &get()#
const bson_mut &get() const#
iterator insert(iterator pos, auto pair)#
iterator insert(iterator pos, bson_iterator::reference elem)#
iterator emplace(
iterator pos,
std::string_view key,
__bson_value_convertible auto val,
)#
C API:

bson_insert()

Invalidation:

All reachable iterators are invalidated

iterator push_back(auto pair)#
iterator push_back(bson_iterator::reference elem)#
iterator emplace_back(std::string_view key, __bson_value_convertible auto val)#
C API:

bson_insert()

Invalidation:

All reachable iterators are invalidated

These are equivalent to insert() or emplace() with the end iterator as the insertion position.

inserted_subdocument insert_subdoc(iterator pos, std::string_view key)#
inserted_subdocument insert_array(iterator pos, std::string_view key)#
mutator push_subdoc(std::string_view key)#
mutator push_array(std::string_view key)#

Insert a new empty child document or array, and obtain a mutator for that child.

Important

The mutator retains a pointer to the object from which it was created. It is essential that the parent object remain in-place while a mutator is in use.

struct inserted_subdocument#
iterator position#
mutator mut#
mutator child(iterator pos)#
iterator parent_iterator() const#
C API:

Important

Regarding child(): The mutator retains a pointer to the object from which it was created. It is essential that the parent object remain in-place while a mutator is in use.

Functions & Macros#

The document iteration/reading APIs detailed in BSON Iteration and BSON Reading also work with bson_mut objects, including:

bson_mut bson_mutate(bson_doc*)#

Obtain a new bson_mut \(M\) mutator for the given document object.

Invalidation:

No iterators are invalidated by this call, but subsequent operations on \(M\) may potentially invalidate them.

Important

The mutator retains a pointer to the object from which it was created. It is essential that the parent object remain in-place while a mutator is in use.

Inserting Data#

[[1]] bson_iterator bson_insert(
bson_mut *m,
__string_convertible key,
__bson_value_convertible value,
)#
[[2]] bson_iterator bson_insert(
bson_mut *m,
bson_iterator pos,
__string_convertible key,
__bson_value_convertible value,
)#

Insert a a value into a BSON document referred-to by m.

Parameters:

  • m – A BSON mutator for the document to be updated.

  • pos – A position at which to perform the insertion. For version [[1]], the default position is bson_end(*m), which will append the value to the end of the document.

  • key – The new element key.

  • value – A value to be inserted.

Returns:

Upon success, returns an iterator that refers to the inserted element. If there is an allocation failure, returns bson_end(*m).

Invalidation:

All reachable iterators are invalidated

Note

This is implemented as a C preprocessor macro

Value Types

The type of the newly inserted value is determined according to the __bson_value_convertible type rules.

bson_mut bson_mut_child(bson_mut *parent, bson_iterator pos)#

Obtain a mutator \(M\) that manipulates a child document element at position pos within parent.

Parameters:

  • parent – An existing mutator that refers to the document that owns pos.

  • pos – An iterator referring to a document or array element within parent.

Invalidation:

No iterators are invalidated by this function, but subsequent operations may invalidate them. Use bson_mut_parent_iterator() to recovery the iterator pos from \(M\).

Important

The mutator retains a pointer to the object from which it was created. It is essential that the parent object remain in-place while a mutator is in use.

bson_iterator bson_mut_parent_iterator(bson_mut m)#

Obtain a bson_iterator that refers to the position of m within a parent document. This can only be called on a bson_mut that was created as a child of another bson_mut.

Parameters:

m – A mutator object that was returned by bson_mut_child(). Calling this with a mutator returned bson_mutate() is undefined behavior.

Invalidation:

No iterators are invalidated.

This is useful to recover an iterator referring to a child document element after mutating that child document, since mutating a child may invalidate iterators in the parent.

Removing Elements#

[[1]] bson_iterator bson_erase(bson_mut *m, bson_iterator pos)#
[[2]] bson_iterator bson_erase(
bson_mut *m,
bson_iterator first,
bson_iterator last,
)#

Erase one or multiple elements within a document m.

Parameters:

  • m – A mutator for the document to be modified.

  • pos – A valid iterator referring to the single element to be erased.

  • first – The first element to be erased.

  • last – The first element to be retained, or the end iterator.

Returns:

  1. The updated iterator referring to the position after pos

  2. The updated iterator referring to the last position

Invalidation:

  1. All reachable iterators are invalidated

  2. bson_erase_range will invalidate all reachable iterators if-and-only-if first is not equal to last.

If first and last are equivalent, then no element will be removed.

Note

This is implemented as a C preprocessor macro

Modifying Elements#

Existing document elements can be modified in-place to a limited extent.

bson_iterator bson_set_key(
bson_mut *mut,
bson_iterator pos,
__string_convertible new_key,
)#

Replace the element key of the element pointed-to by pos.

Parameters:

  • mut – Mutator for the document owning pos

  • pos – A valid iterator pointing to a live element. Must not be an error or end iterator.

  • new_key – The key string to be replaced.

Returns:

The adjusted pos iterator following the modification.

Invalidation:

All reachable iterators are invalidated if-and-only-if new_key is not the same length as bson_key(pos).

bson_iterator bson_relabel_array_elements_at(
bson_mut *doc,
bson_iterator pos,
uint32_t idx,
)#
void bson_relabel_array_elements(bson_mut *doc)#

Relabel elements within a BSON document doc as monotonically increasing decimal integers. bson_relabel_array_elements() is equivalent to bson_relabel_array_elements_at(doc, bson_begin(*doc), 0).

Parameters:

  • doc – The document to be modifed.

  • pos – Iterator referring to the first element to be modified. If equal to bson_end(*doc), then no elements are modified.

  • idx – The integer key to set for pos. All subsequent elements will be relabeled by incrementing this index for each element.

Returns:

Returns the iterator referring to the pos element after the relabelling is complete.

Invalidation:

All reachable iterators are invalidated if-and-only-if the length of any element’s new key is not equal to the length of its existing key. (When in doubt, assume all iterators are invalidated.)

Splicing Ranges#

bson_iterator bson_splice_disjoint_ranges(
bson_mut *m,
bson_iterator pos,
bson_iterator delete_end,
bson_iterator from_begin,
bson_iterator from_end,
)#

Delete elements from m and insert elements from another document into their place.

Parameters:

  • m – The document being modifed.

  • pos – The position at which the splice operation will occur.

  • delete_end – The first element after pos which will not be deleted. If equal to pos, then no elements will be erased.

  • from_begin – The first element to copy into pos

  • from_end – The end of the range from which to copy.

Returns:

Returns the adjusted iterator pointing to the pos element.

Invalidation:

All reachable iterators are invalidated if-and-only-if any elements are deleted or inserted (i.e. pos != delete_end or from_begin != from_end)

Important

If from_begin and from_end are not equal, then from_begin and from_end MUST NOT be elements within m or any elements within its document heirarchy.

Note

delete_end must be reachable from pos, and from_end must be reachable from from_begin.

bson_iterator bson_insert_disjoint_range(
bson_mut *doc,
bson_iterator pos,
bson_iterator from_begin,
bson_iterator from_end,
)#

Copy elements in the range [from_begin, from_end) into the document doc at pos.

Equivalent to bson_splice_disjoint_ranges(doc, pos, pos, from_begin, from_end)

Invalidation:

All reachable iterators are invalidated if-and-only-if from_begin != from_end

Utilities#

struct bson_u32_string#
char buf[11]#

A small string enough to encode a non-negative 32-bit integer with a null terminator.

bson_u32_string bson_u32_string_create(uint32_t i)#

Create a small C string representing the base-10 encoding of the given 32-bit integer i. The string is not dynamically allocated, so no deallocation is necessary. The character array in the returned small string is null-terminated.

Behavioral Notes#

Iterator Invalidation#

A BSON iterator \(I\) is reachable for a bson_doc \(D\) or bson_mut derived from \(D\) if there is any way to obtain that iterator by traversing the document heirarchy. \(I\) may be an iterator at the top level, or may be an iterator within any sub-document of \(D\).

A BSON iterator \(I\) that reachable in a bson_doc \(D\) may be invalidated by certain operations on \(D\) or any sub-document thereof. This is true even if the operation does not cause a reallocation! For this reason, the insertion, erasing, and splicing APIs all return iterators that are adjusted to account for the invalidating operations. Iterator invalidation behaviors are documented under the Invalidation field on the relevant function.

After modifying a subdocument \(D'\) using bson_mut_child(), an iterator referring to \(D'\) can be recovered by using bson_mut_parent_iterator() on the mutator that was created with bson_mut_child().

Contents