Class Poco::MongoDB::Document

Library: MongoDB
Package: MongoDB
Header: Poco/MongoDB/Document.h

Description

Represents a MongoDB (BSON) document.

THREAD SAFETY: This class is NOT thread-safe. Document instances must not be accessed concurrently from multiple threads without external synchronization. Concurrent modifications to the element list will cause undefined behavior.

Each thread should use its own Document instances.

Inheritance

Known Derived Classes: Array, OpMsgCursor

Member Summary

Member Functions: add, addElement, addNewArray, addNewDocument, clear, elementNames, elements, empty, exists, get, getInteger, isType, read, remove, reserve, size, toString, write

Types Aliases

LinearContainer

using LinearContainer = std::vector < Element::Ptr >;

Ptr

using Ptr = SharedPtr < Document >;

Vector

using Vector = std::vector < Document::Ptr >;

Constructors

Document

Document();

Creates an empty Document.

Destructor

~Document

virtual ~Document();

Destroys the Document.

Member Functions

add

template < typename T > Document & add(
const std::string & name,
T value
);

Creates an element with the given name and value and adds it to the document.

The active document is returned to allow chaining of the add methods.

add

template < typename T > typename std::enable_if < ! std::is_same < typename std::decay < T >::type, const char * >::value, Document & >::type add(
std::string && name,
T value
);

Creates an element with the given name (moved) and value and adds it to the document. Move semantics for efficiency. Disabled for const char* to avoid ambiguity.

The active document is returned to allow chaining of the add methods.

add

Document & add(
const std::string & name,
const char * value
);

Creates an element with the given name and value and adds it to the document.

The active document is returned to allow chaining of the add methods.

addElement

Document & addElement(
Element::Ptr element
);

Add an element to the document.

The active document is returned to allow chaining of the add methods.

addNewArray

Array & addNewArray(
const std::string & name
);

Create a new array and add it to this document. Method returns a reference to the new array.

addNewDocument

Document & addNewDocument(
const std::string & name
);

Create a new document and add it to this document. Unlike the other add methods, this method returns a reference to the new document.

clear

void clear() noexcept;

Removes all elements from the document.

elementNames

void elementNames(
std::vector < std::string > & keys
) const;

Puts all element names into std::vector.

empty

[[nodiscard]]
bool empty() const noexcept;

Returns true if the document doesn't contain any documents.

exists

[[nodiscard]]
bool exists(
const std::string & name
) const noexcept;

Returns true if the document has an element with the given name.

get

template < typename T > const T & get(
const std::string & name
) const;

Returns the element with the given name and tries to convert it to the template type. When the element is not found, a NotFoundException will be thrown. When the element can't be converted a BadCastException will be thrown.

get

template < typename T > T get(
const std::string & name,
const T & def
) const;

Returns the element with the given name and tries to convert it to the template type. When the element is not found, or has the wrong type, the def argument will be returned.

get

[[nodiscard]]
Element::Ptr get(
const std::string & name
) const;

Returns the element with the given name. An empty element will be returned when the element is not found.

getInteger

[[nodiscard]]
Int64 getInteger(
const std::string & name
) const;

Returns an integer. Useful when MongoDB returns Int32, Int64 or double for a number (count for example). This method will always return an Int64. When the element is not found, a Poco::NotFoundException will be thrown.