A class that represents a BSON array type document. More...

#include <Array.h>

Inheritance diagram for uma::bson::Array:

Collaboration diagram for uma::bson::Array:

Public Types
typedef std::vector< Element > ::const_iterator	ConstantIterator
	A constant iterator for the elements in the array.

Public Types inherited from uma::bson::Value
enum	Type { Eoo = 0, Double = 1, String = 2, Object = 3, Array = 4, BinData = 5, Undefined = 6, OID = 7, Boolean = 8, Date = 9, Null = 10, RegEx = 11, DbRef = 12, Code = 13, Symbol = 14, CodeWScope = 15, Integer = 16, Timestamp = 17, Long = 18 }

Public Member Functions
	Array ()
	Default constructor. Unlike Document no object id is assigned.

bool	isEmpty () const
	Check to see if the array is empty (has no elements)

size_t	size () const
	Return the total number of fields->(top-level) in this array.

ConstantIterator	begin () const
	Return a constant iterator to the first element in the array.

ConstantIterator	end () const
	Return a constant iterator to the last element in the array.

const Element &	at (const size_t index) const
	Return the element at the specified index in the array as a constant reference.

Element &	at (const size_t index)
	Return the element at the specified index in the array as a reference.

Element &	operator[] (const size_t index)
	Return a reference to the element at the specified index in the array.

const Element &	operator[] (const size_t index) const
	Alias for const.

Array &	add (const Element &element, const int index=-1)
	Adds the specified element to the array.

template<typename DataType >
Array &	add (const DataType &value)
	Add a new element with the specified value to the array.

template<typename DataType >
Array &	operator<< (const DataType &value)
	Alias for add method.

Element	remove (const int index)
	Remove the element at the specified index.

void	toBson (std::ostream &os) const
	Write a BSON representation of the data in this array to the output stream.

void	toJson (std::ostream &os, bool prettyPrint=false) const
	Generate a JSON representation of the data in the array.

Array	clone () const
	Clone the contents of this array.

int32_t	getSize () const
	Return the size of the bson data held in the array.

Value::Type	getType () const
	Returns the datatype for an array as specified in the BSON specification.

Public Member Functions inherited from uma::bson::Value
virtual	~Value ()
	Virtual DTOR for sub-classes.

const std::string &	getTypeName () const
	Returns a standard textual value for this type.

Static Public Member Functions
static Array	fromFile (const std::string &filePath)
	Create a new array instance with the contents of the BSON file at specified path.

static Array	fromBytes (const char *bytes, const int32_t length)
	Create a new array instance with the contents of the `char` array. Can be used to create array instances from MongoDB C/C++ driver functions.

static Array	fromStream (std::istream &is)
	Create a new array instance with the contents read from the specified stream. Usually used to read the BSON data over a network.

static Array	fromJson (std::istream &is)
	Create a new array instance with the JSON data from the specified stream.

Static Public Member Functions inherited from uma::bson::Value
static const std::string &	getTypeName (const Type type)
	Return a descriptive text about the specified type.

Additional Inherited Members
Protected Member Functions inherited from uma::bson::Value
	Value ()

Detailed Description

A class that represents a BSON array type document.

An array stores its elements using sequential numbers as the element/field names. All data is stored as a shared pointer to a PIMPL class to allow efficient pass by value semantics. To properly clone/copy an array use the clone method.

Date: Created 2012/09/06 18:41

Copyright: Copyright © 2012, Sans Pareil Technologies, Inc.

Author: Rakesh

Version

Id:: Array.h 203 2013-02-15 12:23:15Z spt

Member Typedef Documentation

typedef std::vector<Element>::const_iterator uma::bson::Array::ConstantIterator

A constant iterator for the elements in the array.

Constructor & Destructor Documentation

uma::bson::Array::Array ( )

inline

Default constructor. Unlike Document no object id is assigned.

Member Function Documentation

Array& uma::bson::Array::add	(	const Element &	element,
		const int	index = `-1`
	)

inline

Adds the specified element to the array.

Note that any name specified to the element is ignored. Moreover, the name of the element is modified to indciate its index in the array.

Parameters

element	The element to add to the array
index	The index at which to add the element. This enables user defined ordering of the array contents.

Returns: The current array instance to enable method chaining.

template<typename DataType >

Array& uma::bson::Array::add ( const DataType & value )

inline

Add a new element with the specified value to the array.

Template Parameters

DataType The type of value to be added to the array.

Parameters

value The new value to add to the array

Returns: The current array instance to enable method chaining.

const Element& uma::bson::Array::at ( const size_t index ) const

inline

Return the element at the specified index in the array as a constant reference.

Parameters

index The array index from which to retrieve the element.

Returns: The element at the specified index.

Exceptions

std::out_of_range If the specified index is invalid.

Element& uma::bson::Array::at ( const size_t index )

inline

Return the element at the specified index in the array as a reference.

Parameters

index The array index from which to retrieve the element.

Returns: The element at the specified index

Exceptions

std::out_of_range If the specified index is invalid.

ConstantIterator uma::bson::Array::begin ( ) const

inline

Return a constant iterator to the first element in the array.

Since: 2.0

Returns: The iterator to the first element.

Array uma::bson::Array::clone ( ) const

Clone the contents of this array.

This is the recommended way to copy an array. The default copy constructor and assignment operator return array instances that share the internal data. This method returns an array instance with the equivalent but different instances of the internal data.

Warning: This method has not been optimised. The current implementation serialises the array to a BSON stream, and then de-serialises the BSON stream into a new array instance.

Since: 1.3

Returns: An array instance with all the internal data duplicated.

ConstantIterator uma::bson::Array::end ( ) const

inline

Return a constant iterator to the last element in the array.

Since: 2.0

Returns: The iterator to the last element.

static Array uma::bson::Array::fromBytes	(	const char *	bytes,
		const int32_t	length
	)

static

Create a new array instance with the contents of the char array. Can be used to create array instances from MongoDB C/C++ driver functions.

Parameters

bytes	The char array containing the BSON data
length	The total length of the char array

Returns: The array object representing the BSON data.

static Array uma::bson::Array::fromFile ( const std::string & filePath )

static

Create a new array instance with the contents of the BSON file at specified path.

Parameters

filePath The fully qualified name of the file to read.

Returns: The array object representing the BSON data.

static Array uma::bson::Array::fromJson ( std::istream & is )

static

Create a new array instance with the JSON data from the specified stream.

Parameters

is	The input stream to read the JSON data from

Returns: The array object representing the BSON data.

static Array uma::bson::Array::fromStream ( std::istream & is )

static

Create a new array instance with the contents read from the specified stream. Usually used to read the BSON data over a network.

Parameters

is	The input stream to read the BSON data from

Returns: The array object representing the BSON data.

int32_t uma::bson::Array::getSize ( ) const

inlinevirtual

Return the size of the bson data held in the array.

Returns: The size of the bson data array

Implements uma::bson::Value.

Value::Type uma::bson::Array::getType ( ) const

inlinevirtual

Returns the datatype for an array as specified in the BSON specification.

Returns: The type for an array.

Implements uma::bson::Value.

bool uma::bson::Array::isEmpty ( ) const

inline

Check to see if the array is empty (has no elements)

Returns: Return true if there are no child elements.

template<typename DataType >

Array& uma::bson::Array::operator<< ( const DataType & value )

inline

Alias for add method.

Element& uma::bson::Array::operator[] ( const size_t index )

Return a reference to the element at the specified index in the array.

If no element exists at the specified index, an empty element with value uma::bson::Undefined is created and stored at the specified index. A total of index - size() elements will be added to the array.

Parameters

index The index of the element within the array

Returns: The reference to the existing element or newly created one.

const Element& uma::bson::Array::operator[] ( const size_t index ) const

inline

Alias for const.

Element uma::bson::Array::remove ( const int index )

inline

Remove the element at the specified index.

Parameters

index The index of the element to remove from the array.

Returns: A copy of the element that was removed.

Exceptions

Poco::NotFoundException If no element exists at the specified index.

size_t uma::bson::Array::size ( ) const

inline

Return the total number of fields->(top-level) in this array.

Returns: The total number of fields->

void uma::bson::Array::toBson ( std::ostream & os ) const

Write a BSON representation of the data in this array to the output stream.

Parameters

os	The output stream to serialise the BSON data to.

void uma::bson::Array::toJson	(	std::ostream &	os,
		bool	prettyPrint = `false`
	)		const

Generate a JSON representation of the data in the array.

Note that the JSON generated is based closely upon the BSON specification and is not in a "natural" JSON format. The format was chosen to make it easy to re-parse the JSON back into a array.

Parameters

os	The output stream to serialise the JSON data to.
prettyPrint	Indicate whether the output should contain indentation and line breaks for readability.

The documentation for this class was generated from the following file:

/Users/rakesh/projects/opensource/mongoviewer/bson/src/api/uma/bson/Array.h

Public Types

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation