C++ representation of a "BSON" object – that is, an extended JSON-style object in a binary representation.
More...
|
| BSONObj () |
| Construct an empty BSONObj – that is, {}. More...
|
|
| BSONObj (const char *bsonData) |
| Construct a BSONObj from data in the proper format. More...
|
|
BSONObj & | operator= (BSONObj otherCopy) |
| Provide assignment semantics. More...
|
|
void | swap (BSONObj &other) |
| Swap this BSONObj with 'other'.
|
|
bool | isOwned () const |
| A BSONObj can use a buffer it "owns" or one it does not. More...
|
|
BSONObj | getOwned () const |
| assure the data buffer is under the control of this BSONObj and not a remote buffer More...
|
|
BSONObj | copy () const |
|
std::string | jsonString (JsonStringFormat format=Strict, int pretty=0, bool isArray=false) const |
| Properly formatted JSON string. More...
|
|
int | addFields (BSONObj &from, std::set< std::string > &fields) |
| note: addFields always adds _id even if not specified
|
|
BSONObj | removeField (const StringData &name) const |
| remove specified field and return a new object with the remaining fields. More...
|
|
int | nFields () const |
| returns # of top level fields in the object note: iterates to count the fields
|
|
int | getFieldNames (std::set< std::string > &fields) const |
| adds the field names to the fields set. More...
|
|
BSONElement | getFieldDotted (const StringData &name) const |
|
void | getFieldsDotted (const StringData &name, BSONElementSet &ret, bool expandLastArray=true) const |
| Like getFieldDotted(), but expands arrays and returns all matching objects. More...
|
|
BSONElement | getFieldDottedOrArray (const char *&name) const |
| Like getFieldDotted(), but returns first array encountered while traversing the dotted fields of name. More...
|
|
BSONElement | getField (const StringData &name) const |
| Get the field of the specified name. More...
|
|
void | getFields (unsigned n, const char **fieldNames, BSONElement *fields) const |
| Get several fields at once. More...
|
|
BSONElement | operator[] (const StringData &field) const |
| Get the field of the specified name. More...
|
|
bool | hasField (const StringData &name) const |
|
bool | hasElement (const StringData &name) const |
|
const char * | getStringField (const StringData &name) const |
|
BSONObj | getObjectField (const StringData &name) const |
|
int | getIntField (const StringData &name) const |
|
bool | getBoolField (const StringData &name) const |
|
BSONObj | extractFieldsUnDotted (const BSONObj &pattern) const |
|
BSONObj | extractFields (const BSONObj &pattern, bool fillWithNull=false) const |
| extract items from object which match a pattern object. More...
|
|
bool | couldBeArray () const |
| arrays are bson objects with numeric and increasing field names More...
|
|
const char * | objdata () const |
|
int | objsize () const |
|
bool | isValid () const |
| performs a cursory check on the object's size only. More...
|
|
bool | okForStorage () const |
|
bool | okForStorageAsRoot () const |
| Same as above with the following extra restrictions Not valid if: More...
|
|
Status | storageValidEmbedded (const bool deep=true) const |
| Validates that this can be stored as an embedded document See details above in okForStorage. More...
|
|
Status | storageValid (const bool deep=true) const |
| Validates that this can be stored as a document (in a collection) See details above in okForStorageAsRoot. More...
|
|
bool | isEmpty () const |
|
std::string | hexDump () const |
| Alternative output format.
|
|
int | woCompare (const BSONObj &r, const Ordering &o, bool considerFieldName=true) const |
| wo='well ordered'. More...
|
|
int | woCompare (const BSONObj &r, const BSONObj &ordering=BSONObj(), bool considerFieldName=true) const |
| wo='well ordered'. More...
|
|
int | woSortOrder (const BSONObj &r, const BSONObj &sortKey, bool useDotted=false) const |
|
bool | isPrefixOf (const BSONObj &otherObj) const |
|
bool | isFieldNamePrefixOf (const BSONObj &otherObj) const |
|
bool | binaryEqual (const BSONObj &r) const |
| This is "shallow equality" – ints and doubles won't match. More...
|
|
BSONElement | firstElement () const |
|
const char * | firstElementFieldName () const |
| faster than firstElement().fieldName() - for the first element we can easily find the fieldname without computing the element size.
|
|
bool | getObjectID (BSONElement &e) const |
| Get the _id field from the object. More...
|
|
BSONObj | replaceFieldNames (const BSONObj &obj) const |
| Return new object with the field names replaced by those in the passed object. More...
|
|
bool | valid () const |
| true unless corrupt
|
|
void | elems (std::vector< BSONElement > &) const |
| add all elements of the object to the specified vector
|
|
void | elems (std::list< BSONElement > &) const |
| add all elements of the object to the specified list
|
|
BSONObjIterator | begin () const |
| use something like this: for( BSONObj::iterator i = myObj.begin(); i.more(); ) { BSONElement e = i.next(); ... More...
|
|
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>
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