bson::BSONObjBuilder Class Reference

Utility for creating a BSONObj. More...

#include <bsonobjbuilder.h>

Inheritance diagram for bson::BSONObjBuilder:

Classes
struct	ForceExplicitString

Public Member Functions
	BSONObjBuilder (int initsize=512)
	BSONObjBuilder (BufBuilder &baseBuilder)
	BSONObjBuilder (const BSONSizeTracker &tracker)
void	reset ()
void	abandon ()
	Make it look as if "done" has been called, so that our destructor is a no-op.
bool	isEmpty () const
BSONObjBuilder &	appendElements (BSONObj x)
	add all the fields from the object specified to this object
BSONObjBuilder &	appendElementsWithoutName (BSONObj x)
BSONObjBuilder &	appendElementsUnique (BSONObj x)
	add all the fields from the object specified to this object if they don't exist already
BSONObjBuilder &	append (const BSONElement &e)
	append element to the object we are building
BSONObjBuilder &	appendAs (const BSONElement &e, const StringData &fieldName)
	append an element but with a new name
BSONObjBuilder &	append (const StringData &fieldName, BSONObj subObj)
	add a subobject as a member
BSONObjBuilder &	appendEx (const BSONElement &element, const BSONObjBuilderOption &option)
	append element with builder options
BSONObjBuilder &	appendEx (const StringData &fieldName, const BSONElement &element, const BSONObjBuilderOption &option)
	append element with builder options
BSONObjBuilder &	appendEx (const BSONObj &object, const BSONObjBuilderOption &option)
	append element with builder options
BSONObjBuilder &	appendEx (const StringData &fieldName, const BSONObj &subObject, const BSONObjBuilderOption &option)
	append element with builder options
BSONObjBuilder &	appendObject (const StringData &fieldName, const char *objdata, int size=0)
	add a subobject as a member
BufBuilder &	subobjStart (const StringData &fieldName)
	add header for a new subobject and return bufbuilder for writing to the subobject's body
BSONObjBuilder &	appendArray (const StringData &fieldName, const BSONObj &subObj)
	add a subobject as a member with type Array.
BSONObjBuilder &	append (const StringData &fieldName, BSONArray arr)
BufBuilder &	subarrayStart (const StringData &fieldName)
	add header for a new subarray and return bufbuilder for writing to the subarray's body
BSONObjBuilder &	appendBool (const StringData &fieldName, int val)
	Append a boolean element.
BSONObjBuilder &	append (const StringData &fieldName, bool val)
	Append a boolean element.
BSONObjBuilder &	append (const StringData &fieldName, int n)
	Append a 32 bit integer element.
BSONObjBuilder &	append (const StringData &fieldName, unsigned n)
	Append a 32 bit unsigned element - cast to a signed int.
BSONObjBuilder &	append (const StringData &fieldName, long long n)
	Append a NumberLong.
BSONObjBuilder &	appendIntOrLL (const StringData &fieldName, long long n)
	appends a number.
BSONObjBuilder &	appendNumber (const StringData &fieldName, int n)
	appendNumber is a series of method for appending the smallest sensible type.
BSONObjBuilder &	appendNumber (const StringData &fieldName, double d)
BSONObjBuilder &	appendNumber (const StringData &fieldName, size_t n)
BSONObjBuilder &	appendNumber (const StringData &fieldName, long long l)
BSONObjBuilder &	append (const StringData &fieldName, double n)
	Append a double element.
BSONObjBuilder &	append (const StringData &fieldName, const bsonDecimal &decimal)
bool	appendDecimal (const StringData &fieldName, const StringData &strDecimal, int precision, int scale)
bool	appendDecimal (const StringData &fieldName, const StringData &strDecimal)
bool	appendAsNumber (const StringData &fieldName, const StringData &data)
	tries to append the data as a number
BSONObjBuilder &	appendOID (const StringData &fieldName, OID *oid=0, bool generateIfBlank=false)
	Append a BSON Object ID (OID type).
BSONObjBuilder &	append (const StringData &fieldName, OID oid)
	Append a BSON Object ID.
BSONObjBuilder &	genOID ()
	Generate and assign an object id for the _id field.
BSONObjBuilder &	appendTimeT (const StringData &fieldName, time_t dt)
	Append a time_t date.
BSONObjBuilder &	appendDate (const StringData &fieldName, Date_t dt)
	Append a date.
BSONObjBuilder &	append (const StringData &fieldName, Date_t dt)
BSONObjBuilder &	appendRegex (const StringData &fieldName, const StringData &regex, const StringData &options="")
	Append a regular expression value.
BSONObjBuilder &	appendCode (const StringData &fieldName, const StringData &code)
BSONObjBuilder &	append (const StringData &fieldName, const char *str, int sz)
	Append a string element.
BSONObjBuilder &	appendStrWithNoTerminating (const StringData &fieldName, const char *str, int sz)
	Append a string element.
BSONObjBuilder &	append (const StringData &fieldName, const char *str)
	Append a string element.
BSONObjBuilder &	append (const StringData &fieldName, const string &str)
	Append a string element.
BSONObjBuilder &	append (const StringData &fieldName, const StringData &str)
	Append a string element.
BSONObjBuilder &	appendSymbol (const StringData &fieldName, const StringData &symbol)
BSONObjBuilder &	appendNull (const StringData &fieldName)
	Append a Null element to the object.
BSONObjBuilder &	appendMinKey (const StringData &fieldName)
BSONObjBuilder &	appendUndefined (const StringData &fieldName)
	Append a Undefined element to the object.
BSONObjBuilder &	appendMaxKey (const StringData &fieldName)
BSONObjBuilder &	appendTimestamp (const StringData &fieldName)
BSONObjBuilder &	appendTimestamp (const StringData &fieldName, long long val)
	Alternative way to store an OpTime in BSON.
BSONObjBuilder &	appendTimestamp (const StringData &fieldName, long long time, unsigned int inc)
	Append a timestamp value to a bson.
BSONObjBuilder &	appendDBRef (const StringData &fieldName, const StringData &ns, const OID &oid)
BSONObjBuilder &	appendBinData (const StringData &fieldName, int len, BinDataType type, const char *data)
	Append a binary data element.
BSONObjBuilder &	appendBinData (const StringData &fieldName, int len, BinDataType type, const unsigned char *data)
BSONObjBuilder &	appendBinDataArrayDeprecated (const char *fieldName, const char *data, int len)
	Subtype 2 is deprecated.
BSONObjBuilder &	appendCodeWScope (const StringData &fieldName, const StringData &code, const BSONObj &scope)
	Append to the BSON object a field of type CodeWScope.
void	appendWhere (const StringData &code, const BSONObj &scope)
void	appendMinForType (const StringData &fieldName, int type)
	these are the min/max when comparing, not strict min/max elements for a given type
void	appendMaxForType (const StringData &fieldName, int type)
template<class T >
BSONObjBuilder &	append (const StringData &fieldName, const vector< T > &vals)
	Append an array of values.
template<class T >
BSONObjBuilder &	append (const StringData &fieldName, const list< T > &vals)
template<class T >
BSONObjBuilder &	append (const StringData &fieldName, const set< T > &vals)
	Append a set of values.
BSONObj	obj ()
	destructive The returned BSONObj will free the buffer when it is finished.
BSONObj	done ()
	Fetch the object we have built.
void	doneFast ()
BSONObj	asTempObj ()
	Peek at what is in the builder, but leave the builder ready for more appends.
char *	decouple (int &l)
void	decouple ()
void	appendKeys (const BSONObj &keyPattern, const BSONObj &values)
BSONObjBuilderValueStream &	operator<< (const char *name)
	Stream oriented way to add field names and values.
BSONObjBuilder &	operator<< (GENOIDLabeler)
	Stream oriented way to add field names and values.
BSONObjBuilderValueStream &	operator<< (const ForceExplicitString &name)
	Stream oriented way to add field names and values.
Labeler	operator<< (const Labeler::Label &l)
template<typename T >
BSONObjBuilderValueStream &	operator<< (const BSONField< T > &f)
template<typename T >
BSONObjBuilder &	operator<< (const BSONFieldValue< T > &v)
bool	owned () const
BSONObjIterator	iterator () const
bool	hasField (const StringData &name) const
int	len () const
BufBuilder &	bb ()

Static Public Member Functions
static string	numStr (int i)

Detailed Description

Utility for creating a BSONObj.

See also the BSON() and BSON_ARRAY() macros.

Constructor & Destructor Documentation

bson::BSONObjBuilder::BSONObjBuilder ( int  initsize = 512 )

inline

Parameters

initsize

this is just a hint as to the final size of the object

bson::BSONObjBuilder::BSONObjBuilder ( BufBuilder &  baseBuilder )

inline

Parameters

baseBuilder

construct a BSONObjBuilder using an existing BufBuilder This is for more efficient adding of subobjects/arrays. See docs for subobjStart for example.

Member Function Documentation

void bson::BSONObjBuilder::abandon ( )

inline

Make it look as if "done" has been called, so that our destructor is a no-op.

Do this if you know that you don't care about the contents of the builder you are destroying.

Note that it is invalid to call any method other than the destructor after invoking this method.

BSONObjBuilder& bson::BSONObjBuilder::append ( const StringData &  fieldName, unsigned  n  )

inline

Append a 32 bit unsigned element - cast to a signed int.

BSONObjBuilder& bson::BSONObjBuilder::append ( const StringData &  fieldName, OID  oid  )

inline

Append a BSON Object ID.

Parameters

fieldName

Field name, e.g., "_id".

Returns

the builder object

BSONObjBuilder& bson::BSONObjBuilder::append ( const StringData &  fieldName, const char *  str, int  sz  )

inline

Append a string element.

Parameters

sz	size includes terminating null character

template<class T >

BSONObjBuilder & bson::BSONObjBuilder::append ( const StringData &  fieldName, const vector< T > &  vals  )

inline

Append an array of values.

template<class T >

BSONObjBuilder & bson::BSONObjBuilder::append ( const StringData &  fieldName, const set< T > &  vals  )

inline

Append a set of values.

BSONObjBuilder& bson::BSONObjBuilder::appendArray ( const StringData &  fieldName, const BSONObj &  subObj  )

inline

add a subobject as a member with type Array.

Thus arr object should have "0", "1", ... style fields in it.

bool bson::BSONObjBuilder::appendAsNumber	(	const StringData &	fieldName,
		const StringData &	data
	)

tries to append the data as a number

Returns

true if the data was able to be converted to a number

BSONObjBuilder& bson::BSONObjBuilder::appendBinData ( const StringData &  fieldName, int  len, BinDataType  type, const char *  data  )

inline

Append a binary data element.

Parameters

fieldName	name of the field
len	length of the binary data in bytes
subtype	subtype information for the data.

See Also

enum BinDataType in bsontypes.h. Use BinDataGeneral if you don't care about the type.

Parameters

data	the byte array

BSONObjBuilder& bson::BSONObjBuilder::appendBinDataArrayDeprecated ( const char *  fieldName, const char *  data, int  len  )

inline

Subtype 2 is deprecated.

Append a BSON bindata bytearray element.

Parameters

data	a byte array
len	the length of data

BSONObjBuilder& bson::BSONObjBuilder::appendCodeWScope ( const StringData &  fieldName, const StringData &  code, const BSONObj &  scope  )

inline

Append to the BSON object a field of type CodeWScope.

This is a js code fragment accompanied by some scope that goes with it.

BSONObjBuilder& bson::BSONObjBuilder::appendDate ( const StringData &  fieldName, Date_t  dt  )

inline

Append a date.

Parameters

dt	a Java-style 64 bit date value, that is the number of milliseconds since January 1, 1970, 00:00:00 GMT

BSONObjBuilder& bson::BSONObjBuilder::appendIntOrLL ( const StringData &  fieldName, long long  n  )

inline

appends a number.

if n < max(int)/2 then uses int, otherwise long long

BSONObjBuilder& bson::BSONObjBuilder::appendNumber ( const StringData &  fieldName, int  n  )

inline

appendNumber is a series of method for appending the smallest sensible type.

mostly for JS

BSONObjBuilder& bson::BSONObjBuilder::appendOID ( const StringData &  fieldName, OID *  oid = 0, bool  generateIfBlank = false  )

inline

Append a BSON Object ID (OID type).

Deprecated:

Generally, it is preferred to use the append append(name, oid) method for this.

BSONObjBuilder& bson::BSONObjBuilder::appendRegex ( const StringData &  fieldName, const StringData &  regex, const StringData &  options = ""  )

inline

Append a regular expression value.

Parameters

regex	the regular expression pattern
regex	options such as "i" or "g"

BSONObjBuilder& bson::BSONObjBuilder::appendStrWithNoTerminating ( const StringData &  fieldName, const char *  str, int  sz  )

inline

Append a string element.

Parameters

sz	size does not include terminating null character

BSONObjBuilder& bson::BSONObjBuilder::appendTimestamp ( const StringData &  fieldName, long long  val  )

inline

Alternative way to store an OpTime in BSON.

Pass the OpTime as a Date, as follow:

BSONObjBuilder b; OpTime optime(100, 0); b.appendTimestamp("field", optime.asDate());

This captures both the secs and inc fields.

BSONObjBuilder& bson::BSONObjBuilder::appendTimestamp	(	const StringData &	fieldName,
		long long	time,
		unsigned int	inc
	)

Append a timestamp value to a bson.

Parameters

b	the bson to append to.
fieldName	the key for the timestampe value.
time	milliseconds since epoch(but stored in seconds).
inc	microseconds in range of [0us, 999999us].

Returns

the current instance of BSONObjBuilder.

BSONObjBuilder& bson::BSONObjBuilder::appendTimeT ( const StringData &  fieldName, time_t  dt  )

inline

Append a time_t date.

Parameters

dt	a C-style 32 bit date value, that is the number of seconds since January 1, 1970, 00:00:00 GMT

BSONObj bson::BSONObjBuilder::asTempObj ( )

inline

Peek at what is in the builder, but leave the builder ready for more appends.

The returned object is only valid until the next modification or destruction of the builder. Intended use case: append a field if not already there.

BSONObj bson::BSONObjBuilder::done ( )

inline

Fetch the object we have built.

BSONObjBuilder still frees the object when the builder goes out of scope – very important to keep in mind. Use obj() if you would like the BSONObj to last longer than the builder.

BSONObjBuilder& bson::BSONObjBuilder::genOID ( )

inline

Generate and assign an object id for the _id field.

_id should be the first element in the object for good performance.

BSONObj bson::BSONObjBuilder::obj ( )

inline

destructive The returned BSONObj will free the buffer when it is finished.

Returns

owned BSONObj

BSONObjBuilderValueStream& bson::BSONObjBuilder::operator<< ( const char *  name )

inline

Stream oriented way to add field names and values.

BSONObjBuilder& bson::BSONObjBuilder::operator<< ( GENOIDLabeler  )

inline

Stream oriented way to add field names and values.

BSONObjBuilderValueStream& bson::BSONObjBuilder::operator<< ( const ForceExplicitString &  name )

inline

Stream oriented way to add field names and values.

bool bson::BSONObjBuilder::owned ( ) const

inline

Returns

true if we are using our own bufbuilder, and not an alternate that was given to us in our constructor

BufBuilder& bson::BSONObjBuilder::subobjStart ( const StringData &  fieldName )

inline

add header for a new subobject and return bufbuilder for writing to the subobject's body

example:

BSONObjBuilder b; BSONObjBuilder sub (b.subobjStart("fieldName")); // use sub sub.done() // use b and convert to object

---

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

• bsonobjbuilder.h