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
);
Adds an element to the document, replacing an element with the same name.
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.
isType
template < typename T > bool isType(
const std::string & name
) const;
Returns true when the type of the element equals the TypeId of ElementTrait.
read
void read(
BinaryReader & reader
);
Reads a document of at most MAX_MESSAGE_SIZE_BYTES bytes from the reader.
BSON is little-endian; the reader's byte order is not used, as in write().
Only bounds are checked: every length must fit in the enclosing document, strings and documents must end where their length says, the size is limited to MAX_MESSAGE_SIZE_BYTES and the nesting depth is limited. Throws DataFormatException if a check fails or the data ends early, and NotImplementedException for an unsupported element type.
read
Int32 read(
BinaryReader & reader,
Int32 maxSize
);
Reads a document of at most maxSize bytes and returns its size.
BSON is little-endian; the reader's byte order is not used, as in write().
The checks are those of read(BinaryReader&).
remove
bool remove(
const std::string & name
);
Removes an element from the document.
reserve
void reserve(
std::size_t size
);
Reserves space for elements.
size
[[nodiscard]]
std::size_t size() const noexcept;
Returns the number of elements in the document.
toString
[[nodiscard]]
virtual std::string toString(
int indent = 0
) const;
Returns a String representation of the document.
write
void write(
BinaryWriter & writer
) const;
Writes a document to the writer.
Throws InvalidArgumentException if the document is nested too deeply, an element that should hold a document holds none, or an element name contains a null character, and RangeException for a BSONTimestamp outside 1970-2106.
elements
const LinearContainer & elements() const noexcept;
Returns const reference to elements in insertion order for read-only access by derived classes.