BSONElement represents an "element" in a BSONObj. More...

#include <bsonelement.h>

Public Member Functions
std::string	String () const
	These functions, which start with a capital letter, throw a UserException if the element is not of the required type. More...

Date_t	Date () const

double	Number () const

double	Double () const

long long	Long () const

int	Int () const

bool	Bool () const

std::vector< BSONElement >	Array () const

mongo::OID	OID () const

void	Null () const

void	OK () const

BSONObj	Obj () const

void	Val (Date_t &v) const
	populate v with the value of the element. More...

void	Val (long long &v) const

void	Val (bool &v) const

void	Val (BSONObj &v) const

void	Val (mongo::OID &v) const

void	Val (int &v) const

void	Val (double &v) const

void	Val (std::string &v) const

bool	ok () const
	Use ok() to check if a value is assigned: if( myObj["foo"].ok() ) ...

std::string	toString (bool includeFieldName=true, bool full=false) const

void	toString (StringBuilder &s, bool includeFieldName=true, bool full=false, int depth=0) const

std::string	jsonString (JsonStringFormat format, bool includeFieldNames=true, int pretty=0) const

	operator std::string () const

BSONType	type () const
	Returns the type of the element.

BSONElement	operator[] (const std::string &field) const
	retrieve a field within this element throws exception if *this is not an embedded object

int	canonicalType () const
	See canonicalizeBSONType in bsontypes.h.

bool	eoo () const
	Indicates if it is the end-of-object element, which is present at the end of every BSON object.

int	size (int maxLen) const
	Size of the element. More...

int	size () const

BSONObj	wrap () const
	Wrap this element up as a singleton object. More...

BSONObj	wrap (const StringData &newName) const
	Wrap this element up as a singleton object with a new name. More...

const char *	fieldName () const
	field name of the element. More...

int	fieldNameSize () const

const char *	value () const
	raw data of the element's value (so be careful). More...

int	valuesize () const
	size in bytes of the element's value (when applicable). More...

bool	isBoolean () const

bool	boolean () const

bool	booleanSafe () const

Date_t	date () const
	Retrieve a java style date value from the element. More...

bool	trueValue () const
	Convert the value to boolean, regardless of its type, in a javascript-like fashion (i.e., treats zero and null and eoo as false).

bool	isSimpleType () const
	True if number, string, bool, date, OID.

bool	isNumber () const
	True if element is of a numeric type. More...

double	_numberDouble () const
	Return double value for this field. More...

int	_numberInt () const
	Return int value for this field. More...

long long	_numberLong () const
	Return long long value for this field. More...

int	numberInt () const
	Retrieve int value for the element safely. More...

long long	numberLong () const
	Retrieve long value for the element safely. More...

long long	safeNumberLong () const
	Like numberLong() but with well-defined behavior for doubles that are NaNs, or too large/small to be represented as long longs. More...

double	numberDouble () const
	Retrieve the numeric value of the element. More...

double	number () const
	Retrieve the numeric value of the element. More...

const mongo::OID &	__oid () const
	Retrieve the object ID stored in the object. More...

bool	isNull () const
	True if element is null. More...

int	valuestrsize () const
	Size (length) of a string element. More...

int	objsize () const

const char *	valuestr () const
	Get a string's value. More...

const char *	valuestrsafe () const
	Get the string value of the element. More...

std::string	str () const
	Get the string value of the element. More...

const char *	codeWScopeCode () const
	Get javascript code of a CodeWScope data element. More...

int	codeWScopeCodeLen () const
	Get length of the code part of the CodeWScope object This INCLUDES the null char at the end.

const char *	codeWScopeScopeDataUnsafe () const
	Get the scope SavedContext of a CodeWScope data element. More...

const char *	codeWScopeScopeData () const

BSONObj	embeddedObject () const
	Get the embedded object this element holds. More...

BSONObj	embeddedObjectUserCheck () const

BSONObj	codeWScopeObject () const

const char *	binData (int &len) const
	Get raw binary data. More...

const char *	binDataClean (int &len) const
	Get binary data. More...

BinDataType	binDataType () const

const char *	regex () const
	Retrieve the regex string for a Regex element.

const char *	regexFlags () const
	Retrieve the regex flags (options) for a Regex element.

bool	valuesEqual (const BSONElement &r) const
	like operator== but doesn't check the fieldname, just the value.

bool	operator== (const BSONElement &r) const
	Returns true if elements are equal. More...

bool	operator!= (const BSONElement &r) const
	Returns true if elements are unequal. More...

int	woCompare (const BSONElement &e, bool considerFieldName=true) const
	Well ordered comparison. More...

const char *	rawdata () const

int	getGtLtOp (int def=0) const
	0 == Equality, just not defined yet

	BSONElement ()
	Constructs an empty element.

void	validate () const
	Check that data is internally consistent. More...

bool	mayEncapsulate () const
	True if this element may contain subobjects. More...

bool	isABSONObj () const
	True if this element can be a BSONObj.

Date_t	timestampTime () const

unsigned int	timestampInc () const

const char *	dbrefNS () const

const mongo::OID &	dbrefOID () const

bool	operator< (const BSONElement &other) const
	this does not use fieldName in the comparison, just the value

	BSONElement (const char *d, int maxLen)

	BSONElement (const char *d)

std::string	_asCode () const

OpTime	_opTime () const

template<typename T >
bool	coerce (T *out) const

template<>
bool	coerce (int *out) const

template<>
bool	coerce (double *out) const

template<>
bool	coerce (bool *out) const

Friends
class	BSONObjIterator

class	BSONObj

Detailed Description

BSONElement represents an "element" in a BSONObj.

So for the object { a : 3, b : "abc" }, 'a : 3' is the first element (key+value).

The BSONElement object points into the BSONObj's data. Thus the BSONObj must stay in scope for the life of the BSONElement.

internals: <type><fieldName>

-----— size() ---------— -fieldNameSize- value() type()

Member Function Documentation

const mongo::OID& mongo::BSONElement::__oid ( ) const

inline

Retrieve the object ID stored in the object.

You must ensure the element is of type jstOID first.

double mongo::BSONElement::_numberDouble ( ) const

inline

Return double value for this field.

MUST be NumberDouble type.

int mongo::BSONElement::_numberInt ( ) const

inline

Return int value for this field.

MUST be NumberInt type.

long long mongo::BSONElement::_numberLong ( ) const

inline

Return long long value for this field.

MUST be NumberLong type.

const char* mongo::BSONElement::binData ( int & len ) const

inline

Get raw binary data.

Element must be of type BinData. Doesn't handle type 2 specially

const char* mongo::BSONElement::binDataClean ( int & len ) const

inline

Get binary data.

Element must be of type BinData. Handles type 2

bool mongo::BSONElement::boolean ( ) const

inline

Returns: value of a boolean element. You must assure element is a boolean before calling.

const char* mongo::BSONElement::codeWScopeCode ( ) const

inline

Get javascript code of a CodeWScope data element.

const char* mongo::BSONElement::codeWScopeScopeDataUnsafe ( ) const

inline

Get the scope SavedContext of a CodeWScope data element.

This function is DEPRECATED, since it can error if there are null chars in the codeWScopeCode. However, some existing indexes may be based on an incorrect ordering derived from this function, so it may still need to be used in certain cases.

Date_t mongo::BSONElement::date ( ) const

inline

Retrieve a java style date value from the element.

Ensure element is of type Date before calling.

See Also: Bool(), trueValue()

BSONObj mongo::BSONElement::embeddedObject ( ) const

inline

Get the embedded object this element holds.

const char* mongo::BSONElement::fieldName ( ) const

inline

field name of the element.

e.g., for name : "Joe" "name" is the fieldname

bool mongo::BSONElement::isNull ( ) const

inline

True if element is null.

bool mongo::BSONElement::isNumber ( ) const

inline

True if element is of a numeric type.

Returns: true if element is of a numeric type.

bool mongo::BSONElement::mayEncapsulate ( ) const

inline

True if this element may contain subobjects.

double mongo::BSONElement::number ( ) const

inline

Retrieve the numeric value of the element.

If not of a numeric type, returns 0. Note: casts to double, data loss may occur with large (>52 bit) NumberLong values.

double mongo::BSONElement::numberDouble ( ) const

inline

Retrieve the numeric value of the element.

If not of a numeric type, returns 0. Note: casts to double, data loss may occur with large (>52 bit) NumberLong values.

int mongo::BSONElement::numberInt ( ) const

inline

Retrieve int value for the element safely.

Zero returned if not a number.

Zero returned if not a number. Converted to int if another numeric type.

long long mongo::BSONElement::numberLong ( ) const

inline

Retrieve long value for the element safely.

Zero returned if not a number. Behavior is not defined for double values that are NaNs, or too large/small to be represented by long longs

Zero returned if not a number.

BSONObj mongo::BSONElement::Obj ( ) const

inline

Returns: the embedded object associated with this field. Note the returned object is a reference to within the parent bson object. If that object is out of scope, this pointer will no longer be valid. Call getOwned() on the returned BSONObj if you need your own copy. throws UserException if the element is not of type object.

bool mongo::BSONElement::operator!= ( const BSONElement & r ) const

inline

Returns true if elements are unequal.

bool mongo::BSONElement::operator== ( const BSONElement & r ) const

inline

Returns true if elements are equal.

long long mongo::BSONElement::safeNumberLong ( ) const

inline

Like numberLong() but with well-defined behavior for doubles that are NaNs, or too large/small to be represented as long longs.

NaNs -> 0 very large doubles -> LLONG_MAX very small doubles -> LLONG_MIN

int mongo::BSONElement::size ( int maxLen ) const

inline

Size of the element.

Parameters

maxLen If maxLen is specified, don't scan more than maxLen bytes to calculate size.

std::string mongo::BSONElement::str ( ) const

inline

Get the string value of the element.

If not a string returns "".

std::string mongo::BSONElement::String ( ) const

inline

These functions, which start with a capital letter, throw a UserException if the element is not of the required type.

Example:

std::string foo = obj["foo"].String(); // std::exception if not a std::string type or DNE

void mongo::BSONElement::Val ( Date_t & v ) const

inline

populate v with the value of the element.

If type does not match, throw exception. useful in templates – see also BSONObj::Vals().

void mongo::BSONElement::validate ( ) const

inline

Check that data is internally consistent.

const char* mongo::BSONElement::value ( ) const

inline

raw data of the element's value (so be careful).

int mongo::BSONElement::valuesize ( ) const

inline

size in bytes of the element's value (when applicable).

const char* mongo::BSONElement::valuestr ( ) const

inline

Get a string's value.

Also gives you start of the real data for an embedded object. You must assure data is of an appropriate type first – see also valuestrsafe().

const char* mongo::BSONElement::valuestrsafe ( ) const

inline

Get the string value of the element.

If not a string returns "".

int mongo::BSONElement::valuestrsize ( ) const

inline

Size (length) of a string element.

You must assure of type String first.

Returns: string size including terminating null

int mongo::BSONElement::woCompare	(	const BSONElement &	e,
		bool	considerFieldName = `true`
	)		const

inline

Well ordered comparison.

Returns: <0: l<r. 0:l==r. >0:l>r order by type, field name, and field value. If considerFieldName is true, pay attention to the field name.

BSONObj mongo::BSONElement::wrap ( ) const

inline

Wrap this element up as a singleton object.

BSONObj mongo::BSONElement::wrap ( const StringData & newName ) const

inline

Wrap this element up as a singleton object with a new name.

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

Public Member Functions

Friends

Detailed Description

Member Function Documentation