MongoDB  2.6.0
Public Member Functions | Static Public Member Functions | List of all members
mongo::BSONObjBuilder Class Reference

Utility for creating a BSONObj. More...

#include <bsonobjbuilder.h>

Inheritance diagram for mongo::BSONObjBuilder:
mongo::BSONBuilderBase

Public Member Functions

 BSONObjBuilder (int initsize=512)
 
 BSONObjBuilder (BufBuilder &baseBuilder)
 
 BSONObjBuilder (const BSONSizeTracker &tracker)
 
BSONObjBuilderappendElements (BSONObj x)
 add all the fields from the object specified to this object
 
BSONObjBuilderappendElementsUnique (BSONObj x)
 add all the fields from the object specified to this object if they don't exist already
 
BSONObjBuilderappend (const BSONElement &e)
 append element to the object we are building
 
BSONObjBuilderappendAs (const BSONElement &e, const StringData &fieldName)
 append an element but with a new name
 
BSONObjBuilderappend (const StringData &fieldName, BSONObj subObj)
 add a subobject as a member
 
BSONObjBuilderappendObject (const StringData &fieldName, const char *objdata, int size=0)
 add a subobject as a member
 
BufBuildersubobjStart (const StringData &fieldName)
 add header for a new subobject and return bufbuilder for writing to the subobject's body More...
 
BSONObjBuilderappendArray (const StringData &fieldName, const BSONObj &subObj)
 add a subobject as a member with type Array. More...
 
BSONObjBuilderappend (const StringData &fieldName, BSONArray arr)
 
BufBuildersubarrayStart (const StringData &fieldName)
 add header for a new subarray and return bufbuilder for writing to the subarray's body
 
BSONObjBuilderappendBool (const StringData &fieldName, int val)
 Append a boolean element.
 
BSONObjBuilderappend (const StringData &fieldName, bool val)
 Append a boolean element.
 
BSONObjBuilderappend (const StringData &fieldName, int n)
 Append a 32 bit integer element.
 
BSONObjBuilderappend (const StringData &fieldName, unsigned n)
 Append a 32 bit unsigned element - cast to a signed int. More...
 
BSONObjBuilderappend (const StringData &fieldName, long long n)
 Append a NumberLong.
 
BSONObjBuilderappendIntOrLL (const StringData &fieldName, long long n)
 appends a number. More...
 
BSONObjBuilderappendNumber (const StringData &fieldName, int n)
 appendNumber is a series of method for appending the smallest sensible type mostly for JS
 
BSONObjBuilderappendNumber (const StringData &fieldName, double d)
 
BSONObjBuilderappendNumber (const StringData &fieldName, size_t n)
 
BSONObjBuilderappendNumber (const StringData &fieldName, long long llNumber)
 
BSONObjBuilderappend (const StringData &fieldName, double n)
 Append a double element.
 
bool appendAsNumber (const StringData &fieldName, const std::string &data)
 tries to append the data as a number More...
 
BSONObjBuilderappendOID (const StringData &fieldName, OID *oid=0, bool generateIfBlank=false)
 Append a BSON Object ID (OID type). More...
 
BSONObjBuilderappend (const StringData &fieldName, OID oid)
 Append a BSON Object ID. More...
 
BSONObjBuildergenOID ()
 Generate and assign an object id for the _id field. More...
 
BSONObjBuilderappendTimeT (const StringData &fieldName, time_t dt)
 Append a time_t date. More...
 
BSONObjBuilderappendDate (const StringData &fieldName, Date_t dt)
 Append a date. More...
 
BSONObjBuilderappend (const StringData &fieldName, Date_t dt)
 
BSONObjBuilderappendRegex (const StringData &fieldName, const StringData &regex, const StringData &options="")
 Append a regular expression value. More...
 
BSONObjBuilderappend (const StringData &fieldName, const BSONRegEx &regex)
 
BSONObjBuilderappendCode (const StringData &fieldName, const StringData &code)
 
BSONObjBuilderappend (const StringData &fieldName, const BSONCode &code)
 
BSONObjBuilderappend (const StringData &fieldName, const char *str, int sz)
 Append a string element. More...
 
BSONObjBuilderappend (const StringData &fieldName, const char *str)
 Append a string element.
 
BSONObjBuilderappend (const StringData &fieldName, const std::string &str)
 Append a string element.
 
BSONObjBuilderappend (const StringData &fieldName, const StringData &str)
 Append a string element.
 
BSONObjBuilderappendSymbol (const StringData &fieldName, const StringData &symbol)
 
BSONObjBuilderappend (const StringData &fieldName, const BSONSymbol &symbol)
 
void appendNull ()
 Implements builder interface but no-op in ObjBuilder.
 
BSONObjBuilderappendNull (const StringData &fieldName)
 Append a Null element to the object.
 
BSONObjBuilderappendMinKey (const StringData &fieldName)
 
BSONObjBuilderappendMaxKey (const StringData &fieldName)
 
BSONObjBuilderappendTimestamp (const StringData &fieldName)
 
BSONObjBuilderappend (const StringData &fieldName, OpTime optime)
 To store an OpTime in BSON, use this function. More...
 
BSONObjBuilderappendTimestamp (const StringData &fieldName, unsigned long long val)
 Alternative way to store an OpTime in BSON. More...
 
BSONObjBuilderappendTimestamp (const StringData &fieldName, unsigned long long time, unsigned int inc)
 Timestamps are a special BSON datatype that is used internally for replication. More...
 
BSONObjBuilderappendDBRef (const StringData &fieldName, const StringData &ns, const OID &oid)
 
BSONObjBuilderappend (const StringData &fieldName, const BSONDBRef &dbref)
 
BSONObjBuilderappendBinData (const StringData &fieldName, int len, BinDataType type, const void *data)
 Append a binary data element. More...
 
BSONObjBuilderappend (const StringData &fieldName, const BSONBinData &bd)
 
BSONObjBuilderappendBinDataArrayDeprecated (const char *fieldName, const void *data, int len)
 Subtype 2 is deprecated. More...
 
BSONObjBuilderappendCodeWScope (const StringData &fieldName, const StringData &code, const BSONObj &scope)
 Append to the BSON object a field of type CodeWScope. More...
 
BSONObjBuilderappend (const StringData &fieldName, const BSONCodeWScope &cws)
 
void appendUndefined (const StringData &fieldName)
 
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 >
BSONObjBuilderappend (const StringData &fieldName, const std::vector< T > &vals)
 Append an array of values. More...
 
template<class T >
BSONObjBuilderappend (const StringData &fieldName, const std::list< T > &vals)
 
template<class T >
BSONObjBuilderappend (const StringData &fieldName, const std::set< T > &vals)
 Append a set of values. More...
 
template<class K , class T >
BSONObjBuilderappend (const StringData &fieldName, const std::map< K, T > &vals)
 Append a map of values as a sub-object. More...
 
BSONObj obj ()
 destructive The returned BSONObj will free the buffer when it is finished. More...
 
BSONObj done ()
 Fetch the object we have built. More...
 
void doneFast ()
 
BSONObj asTempObj ()
 Peek at what is in the builder, but leave the builder ready for more appends. More...
 
void abandon ()
 Make it look as if "done" has been called, so that our destructor is a no-op. More...
 
void decouple ()
 
void appendKeys (const BSONObj &keyPattern, const BSONObj &values)
 
BSONObjBuilderValueStreamoperator<< (const StringData &name)
 Stream oriented way to add field names and values. More...
 
BSONObjBuilderoperator<< (GENOIDLabeler)
 Stream oriented way to add field names and values. More...
 
Labeler operator<< (const Labeler::Label &l)
 
template<typename T >
BSONObjBuilderValueStreamoperator<< (const BSONField< T > &f)
 
template<typename T >
BSONObjBuilderoperator<< (const BSONFieldValue< T > &v)
 
BSONObjBuilderoperator<< (const BSONElement &e)
 
bool isArray () const
 
bool owned () const
 
BSONObjIterator iterator () const
 
bool hasField (const StringData &name) const
 
int len () const
 
BufBuilderbb ()
 

Static Public Member Functions

static std::string numStr (int i)
 

Detailed Description

Utility for creating a BSONObj.

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

Constructor & Destructor Documentation

mongo::BSONObjBuilder::BSONObjBuilder ( int  initsize = 512)
inline
Parameters
initsizethis is just a hint as to the final size of the object
mongo::BSONObjBuilder::BSONObjBuilder ( BufBuilder baseBuilder)
inline
Parameters
baseBuilderconstruct 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 mongo::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& mongo::BSONObjBuilder::append ( const StringData &  fieldName,
unsigned  n 
)
inline

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

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

Append a BSON Object ID.

Parameters
fieldNameField name, e.g., "_id".
Returns
the builder object
BSONObjBuilder& mongo::BSONObjBuilder::append ( const StringData &  fieldName,
const char *  str,
int  sz 
)
inline

Append a string element.

Parameters
szsize includes terminating null character
BSONObjBuilder & mongo::BSONObjBuilder::append ( const StringData &  fieldName,
OpTime  optime 
)
inline

To store an OpTime in BSON, use this function.

This captures both the secs and inc fields.

template<class T >
BSONObjBuilder & mongo::BSONObjBuilder::append ( const StringData &  fieldName,
const std::vector< T > &  vals 
)
inline

Append an array of values.

template<class T >
BSONObjBuilder & mongo::BSONObjBuilder::append ( const StringData &  fieldName,
const std::set< T > &  vals 
)
inline

Append a set of values.

template<class K , class T >
BSONObjBuilder & mongo::BSONObjBuilder::append ( const StringData &  fieldName,
const std::map< K, T > &  vals 
)
inline

Append a map of values as a sub-object.

Note: the keys of the map should be StringData-compatible (i.e. strings).

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

add a subobject as a member with type Array.

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

Implements mongo::BSONBuilderBase.

bool mongo::BSONObjBuilder::appendAsNumber ( const StringData &  fieldName,
const std::string &  data 
)

tries to append the data as a number

Returns
true if the data was able to be converted to a number
BSONObjBuilder& mongo::BSONObjBuilder::appendBinData ( const StringData &  fieldName,
int  len,
BinDataType  type,
const void *  data 
)
inline

Append a binary data element.

Parameters
fieldNamename of the field
lenlength of the binary data in bytes
subtypesubtype information for the data.
See Also
enum BinDataType in bsontypes.h. Use BinDataGeneral if you don't care about the type.
Parameters
datathe byte array
BSONObjBuilder& mongo::BSONObjBuilder::appendBinDataArrayDeprecated ( const char *  fieldName,
const void *  data,
int  len 
)
inline

Subtype 2 is deprecated.

Append a BSON bindata bytearray element.

Parameters
dataa byte array
lenthe length of data
BSONObjBuilder& mongo::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 javascript code fragment accompanied by some scope that goes with it.

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

Append a date.

Parameters
dta Java-style 64 bit date value, that is the number of milliseconds since January 1, 1970, 00:00:00 GMT
BSONObjBuilder& mongo::BSONObjBuilder::appendIntOrLL ( const StringData &  fieldName,
long long  n 
)
inline

appends a number.

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

BSONObjBuilder& mongo::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& mongo::BSONObjBuilder::appendRegex ( const StringData &  fieldName,
const StringData &  regex,
const StringData &  options = "" 
)
inline

Append a regular expression value.

Parameters
regexthe regular expression pattern
regexoptions such as "i" or "g"
BSONObjBuilder& mongo::BSONObjBuilder::appendTimestamp ( const StringData &  fieldName,
unsigned long long  val 
)
inline

Alternative way to store an OpTime in BSON.

Pass the OpTime as a Date, as follows:

builder.appendTimestamp("field", optime.asDate());

This captures both the secs and inc fields.

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

Timestamps are a special BSON datatype that is used internally for replication.

Append a timestamp element to the object being ebuilt.

Parameters
time- in millis (but stored in seconds)
BSONObjBuilder& mongo::BSONObjBuilder::appendTimeT ( const StringData &  fieldName,
time_t  dt 
)
inline

Append a time_t date.

Parameters
dta C-style 32 bit date value, that is the number of seconds since January 1, 1970, 00:00:00 GMT
BSONObj mongo::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 mongo::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& mongo::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 mongo::BSONObjBuilder::obj ( )
inlinevirtual

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

Returns
owned BSONObj

Implements mongo::BSONBuilderBase.

BSONObjBuilderValueStream& mongo::BSONObjBuilder::operator<< ( const StringData &  name)
inline

Stream oriented way to add field names and values.

BSONObjBuilder& mongo::BSONObjBuilder::operator<< ( GENOIDLabeler  )
inline

Stream oriented way to add field names and values.

bool mongo::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& mongo::BSONObjBuilder::subobjStart ( const StringData &  fieldName)
inlinevirtual

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

Implements mongo::BSONBuilderBase.


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