C++ representation of a "BSON" object -- that is, an extended JSON-style object in a binary representation. More...

#include <bsonobj.h>

Inheritance diagram for mongo::BSONObj:

Classes
class	Holder
Public Types
enum	MatchType { Equality = 0, LT = 0x1, LTE = 0x3, GTE = 0x6, GT = 0x4, opIN = 0x8, NE = 0x9, opSIZE = 0x0A, opALL = 0x0B, NIN = 0x0C, opEXISTS = 0x0D, opMOD = 0x0E, opTYPE = 0x0F, opREGEX = 0x10, opOPTIONS = 0x11, opELEM_MATCH = 0x12, opNEAR = 0x13, opWITHIN = 0x14, opMAX_DISTANCE = 0x15 }
typedef BSONObjIterator	iterator
Public Member Functions
	BSONObj (const char *msgdata, bool ifree=false)
	Construct a BSONObj from data in the proper format.
	BSONObj (const Record *r)
	BSONObj ()
	Construct an empty BSONObj -- that is, {}.
bool	isOwned () const
	A BSONObj can use a buffer it "owns" or one it does not.
BSONObj	getOwned () const
BSONObj	copy () const
string	toString (bool isArray=false, bool full=false) const
	Readable representation of a BSON object in an extended JSON-style notation.
void	toString (StringBuilder &s, bool isArray=false, bool full=false) const
string	jsonString (JsonStringFormat format=Strict, int pretty=0) const
	Properly formatted JSON string.
int	addFields (BSONObj &from, set< string > &fields)
	note: addFields always adds _id even if not specified
int	nFields () const
	returns # of top level fields in the object note: iterates to count the fields
int	getFieldNames (set< string > &fields) const
	adds the field names to the fields set.
BSONElement	getFieldDotted (const char *name) const
	return has eoo() true if no match supports "." notation to reach into embedded objects
BSONElement	getFieldDotted (const string &name) const
	return has eoo() true if no match supports "." notation to reach into embedded objects
void	getFieldsDotted (const StringData &name, BSONElementSet &ret) const
	Like getFieldDotted(), but expands multikey arrays and returns all matching objects.
BSONElement	getFieldDottedOrArray (const char *&name) const
	Like getFieldDotted(), but returns first array encountered while traversing the dotted fields of name.
BSONElement	getField (const StringData &name) const
	Get the field of the specified name.
BSONElement	operator[] (const char *field) const
	Get the field of the specified name.
BSONElement	operator[] (const string &field) const
BSONElement	operator[] (int field) const
bool	hasField (const char *name) const
const char *	getStringField (const char *name) const
BSONObj	getObjectField (const char *name) const
int	getIntField (const char *name) const
bool	getBoolField (const char *name) const
BSONObj	extractFieldsUnDotted (BSONObj pattern) const
	sets element field names to empty string If a field in pattern is missing, it is omitted from the returned object.
BSONObj	extractFields (const BSONObj &pattern, bool fillWithNull=false) const
	extract items from object which match a pattern object.
BSONObj	filterFieldsUndotted (const BSONObj &filter, bool inFilter) const
BSONElement	getFieldUsingIndexNames (const char *fieldName, const BSONObj &indexKey) const
const char *	objdata () const
int	objsize () const
bool	isValid ()
	performs a cursory check on the object's size only.
bool	okForStorage () const
bool	isEmpty () const
void	dump () const
string	hexDump () const
	Alternative output format.
int	woCompare (const BSONObj &r, const Ordering &o, bool considerFieldName=true) const
	wo='well ordered'.
int	woCompare (const BSONObj &r, const BSONObj &ordering=BSONObj(), bool considerFieldName=true) const
	wo='well ordered'.
bool	operator< (const BSONObj &other) const
bool	operator<= (const BSONObj &other) const
bool	operator> (const BSONObj &other) const
bool	operator>= (const BSONObj &other) const
int	woSortOrder (const BSONObj &r, const BSONObj &sortKey, bool useDotted=false) const
bool	woEqual (const BSONObj &r) const
	This is "shallow equality" -- ints and doubles won't match.
BSONElement	firstElement () const
bool	hasElement (const char *name) const
bool	getObjectID (BSONElement &e) const
	Get the _id field from the object.
int	hash () const
BSONObj	clientReadable () const
BSONObj	replaceFieldNames (const BSONObj &obj) const
	Return new object with the field names replaced by those in the passed object.
bool	valid () const
	true unless corrupt
string	md5 () const
bool	operator== (const BSONObj &other) const
void	elems (vector< BSONElement > &) const
	add all elements of the object to the specified vector
void	elems (list< BSONElement > &) const
	add all elements of the object to the specified list
template<class T >
void	Vals (vector< T > &) const
	add all values of the object to the specified vector.
template<class T >
void	Vals (list< T > &) const
	add all values of the object to the specified list.
template<class T >
void	vals (vector< T > &) const
	add all values of the object to the specified vector.
template<class T >
void	vals (list< T > &) const
	add all values of the object to the specified list.
BSONObjIterator	begin ()
	use something like this: for( BSONObj::iterator i = myObj.begin(); i.more(); ) { BSONElement e = i.next(); ...
void	appendSelfToBufBuilder (BufBuilder &b) const
Friends
class	BSONObjIterator

Detailed Description

C++ representation of a "BSON" object -- that is, an extended JSON-style object in a binary representation.

See bsonspec.org.

Note that BSONObj's have a smart pointer capability built in -- so you can pass them around by value. The reference counts used to implement this do not use locking, so copying and destroying BSONObj's are not thread-safe operations.

BSON object format:

code <unsigned totalsize>=""> {<byte bsontype>=""><cstring fieldname>=""><Data>}* EOO

totalSize includes itself.

Data: Bool: <byte> EOO: nothing follows Undefined: nothing follows OID: an OID object NumberDouble: <double> NumberInt: <int32> String: <unsigned32 strsizewithnull>=""><cstring> Date: <8bytes> Regex: <cstring regex>=""><cstring options>=""> Object: a nested object, leading with its entire size, which terminates with EOO. Array: same as object DBRef: <strlen> <cstring ns>=""> <oid> DBRef: a database reference: basically a collection name plus an Object ID BinData: <int len>=""> <byte subtype>=""> <byte[len] data> Code: a function (not a closure): same format as String. Symbol: a language symbol (say a python symbol). same format as String. Code With Scope: <total size>=""><String><Object>

Constructor & Destructor Documentation

mongo::BSONObj::BSONObj	(	const char *	msgdata,
		bool	ifree = `false`
	)		`[inline, explicit]`

Construct a BSONObj from data in the proper format.

Parameters:

ifree true if the BSONObj should free() the msgdata when it destructs.

mongo::BSONObj::BSONObj ( ) [inline]

Construct an empty BSONObj -- that is, {}.

Member Function Documentation

BSONObjIterator mongo::BSONObj::begin ( ) [inline]

use something like this: for( BSONObj::iterator i = myObj.begin(); i.more(); ) { BSONElement e = i.next(); ...

}

NOINLINE_DECL BSONObj mongo::BSONObj::copy ( ) const [inline]

Returns:: a new full (and owned) copy of the object.

BSONObj mongo::BSONObj::extractFields	(	const BSONObj &	pattern,
		bool	fillWithNull = `false`
	)		const

extract items from object which match a pattern object.

e.g., if pattern is { x : 1, y : 1 }, builds an object with x and y elements of this object, if they are present. returns elements with original field names

BSONElement mongo::BSONObj::firstElement ( ) const [inline]

Returns:: first field of the object

bool mongo::BSONObj::getBoolField ( const char * name ) const

Returns:: false if not present

BSONElement mongo::BSONObj::getField ( const StringData & name ) const [inline]

Get the field of the specified name.

eoo() is true on the returned element if not found.

BSONElement mongo::BSONObj::getFieldDottedOrArray ( const char *& name ) const

Like getFieldDotted(), but returns first array encountered while traversing the dotted fields of name.

The name variable is updated to represent field names with respect to the returned element.

int mongo::BSONObj::getFieldNames ( set< string > & fields ) const

adds the field names to the fields set.

does NOT clear it (appends).

int mongo::BSONObj::getIntField ( const char * name ) const

Returns:: INT_MIN if not present - does some type conversions

BSONObj mongo::BSONObj::getObjectField ( const char * name ) const [inline]

Returns:: subobject of the given name

bool mongo::BSONObj::getObjectID ( BSONElement & e ) const [inline]

Get the _id field from the object.

For good performance drivers should assure that _id is the first element of the object; however, correct operation is assured regardless.

Returns:: true if found

const char* mongo::BSONObj::getStringField ( const char * name ) const

Returns:: "" if DNE or wrong type

bool mongo::BSONObj::hasElement ( const char * name ) const [inline]

Returns:: true if field exists in the object

bool mongo::BSONObj::hasField ( const char * name ) const [inline]

Returns:: true if field exists

int mongo::BSONObj::hash ( ) const [inline]

Returns:: A hash code for the object

bool mongo::BSONObj::isEmpty ( ) const [inline]

Returns:: true if object is empty -- i.e., {}

bool mongo::BSONObj::isOwned ( ) const [inline]

A BSONObj can use a buffer it "owns" or one it does not.

OWNED CASE If the BSONObj owns the buffer, the buffer can be shared among several BSONObj's (by assignment). In this case the buffer is basically implemented as a shared_ptr. Since BSONObj's are typically immutable, this works well.

UNOWNED CASE A BSONObj can also point to BSON data in some other data structure it does not "own" or free later. For example, in a memory mapped file. In this case, it is important the original data stays in scope for as long as the BSONObj is in use. If you think the original data may go out of scope, call BSONObj::getOwned() to promote your BSONObj to having its own copy.

On a BSONObj assignment, if the source is unowned, both the source and dest will have unowned pointers to the original buffer after the assignment.

If you are not sure about ownership but need the buffer to last as long as the BSONObj, call getOwned(). getOwned() is a no-op if the buffer is already owned. If not already owned, a malloc and memcpy will result.

Most ways to create BSONObj's create 'owned' variants. Unowned versions can be created with: (1) specifying true for the ifree parameter in the constructor (2) calling BSONObjBuilder::done(). Use BSONObjBuilder::obj() to get an owned copy (3) retrieving a subobject retrieves an unowned pointer into the parent BSON object

Returns:: true if this is in owned mode

bool mongo::BSONObj::isValid ( ) [inline]

performs a cursory check on the object's size only.

string mongo::BSONObj::jsonString	(	JsonStringFormat	format = `Strict`,
		int	pretty = `0`
	)		const

Properly formatted JSON string.

Parameters:

pretty if true we try to add some lf's and indentation

string mongo::BSONObj::md5 ( ) const

Returns:: an md5 value for this object.

const char* mongo::BSONObj::objdata ( ) const [inline]

Returns:: the raw data of the object

int mongo::BSONObj::objsize ( ) const [inline]

Returns:: total size of the BSON object in bytes

bool mongo::BSONObj::okForStorage ( ) const

Returns:: if the user is a valid user doc criter: isValid() no . or $ field names

BSONElement mongo::BSONObj::operator[] ( const char * field ) const [inline]

Get the field of the specified name.

eoo() is true on the returned element if not found.

BSONObj mongo::BSONObj::replaceFieldNames ( const BSONObj & obj ) const

Return new object with the field names replaced by those in the passed object.

string mongo::BSONObj::toString	(	bool	isArray = `false`,
		bool	full = `false`
	)		const `[inline]`

Readable representation of a BSON object in an extended JSON-style notation.

This is an abbreviated representation which might be used for logging.

template<class T >

void mongo::BSONObj::Vals ( vector< T > & v ) const

add all values of the object to the specified vector.

If type mismatches, exception. this is most useful when the BSONObj is an array, but can be used with non-arrays too in theory.

example: bo sub = y["subobj"].Obj(); vector<int> myints; sub.Vals(myints);

template<class T >

void mongo::BSONObj::Vals ( list< T > & v ) const

add all values of the object to the specified list.

If type mismatches, exception.

template<class T >

void mongo::BSONObj::vals ( vector< T > & v ) const

add all values of the object to the specified vector.

If type mismatches, skip.

template<class T >

void mongo::BSONObj::vals ( list< T > & v ) const

add all values of the object to the specified list.

If type mismatches, skip.

int mongo::BSONObj::woCompare	(	const BSONObj &	r,
		const Ordering &	o,
		bool	considerFieldName = `true`
	)		const

wo='well ordered'.

fields must be in same order in each object. Ordering is with respect to the signs of the elements and allows ascending / descending key mixing.

Returns:: <0 if l<r. 0 if l==r. >0 if l>r

int mongo::BSONObj::woCompare	(	const BSONObj &	r,
		const BSONObj &	ordering = `BSONObj()`,
		bool	considerFieldName = `true`
	)		const

wo='well ordered'.

fields must be in same order in each object. Ordering is with respect to the signs of the elements and allows ascending / descending key mixing.

Returns:: <0 if l<r. 0 if l==r. >0 if l>r

bool mongo::BSONObj::woEqual ( const BSONObj & r ) const [inline]

This is "shallow equality" -- ints and doubles won't match.

for a deep equality test use woCompare (which is slower).

int mongo::BSONObj::woSortOrder	(	const BSONObj &	r,
		const BSONObj &	sortKey,
		bool	useDotted = `false`
	)		const

Parameters:

useDotted whether to treat sort key fields as possibly dotted and expand into them

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

Classes

Public Types

Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation