C++ representation of a "BSON" object – that is, an extended JSON-style object in a binary representation. More...
#include <bsonobj.h>
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, opISNULL =0x16 } |
typedef bson_intrusive_ptr < Holder, TrivialAllocator > | holder_type |
typedef BSONObjIterator | iterator |
Public Member Functions | |
BSONObj (const char *msgdata, bool check=true) | |
Construct a BSONObj from data in the proper format. | |
BSONObj (holder_type holder) | |
Construct a BSONObj from data in the proper format. | |
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 |
assure the data buffer is under the control of this BSONObj and not a remote buffer | |
BSONObj | copy () const |
string | toString (bool isArray=false, bool full=false, bool noThrow=true) 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 |
BSONElement | getFieldDotted (const string &name) const |
void | getFieldsDotted (const StringData &name, BSONElementSet &ret) const |
Like getFieldDotted(), but expands arrays and returns all matching objects. | |
void | getFieldsDotted (const StringData &name, BSONElementMSet &ret) const |
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 | getField (const char *name) const |
void | getFields (unsigned n, const char **fieldNames, BSONElement *fields) const |
Get several fields at once. | |
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 |
bool | hasElement (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 () const |
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 | equal (const BSONObj &r) const |
bool | shallowEqual (const BSONObj &r) const |
This is "shallow equality" – ints and doubles won't match. | |
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. | |
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 () const |
use something like this: for( BSONObj::iterator i = myObj.begin(); i.more(); ) { BSONElement e = i.next(); ... | |
void | appendSelfToBufBuilder (BufBuilder &b) const |
void | init (const char *data, bool check=true) |
initialize from existing buffer | |
Static Public Member Functions | |
static void | setJSCompatibility (bool compatible) |
when this value is not zero, the BSONObje::toString() method will show the string which is the same with that shows in sdb shell. | |
static bool | getJSCompatibility () |
get whether bson_print method will show the string which is the same with that shows in sdb shell or not | |
Friends | |
class | BSONObjIterator |
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>
|
inlineexplicit |
Construct a BSONObj from data in the proper format.
owned = whether this object owns this buffer.
|
inlineexplicit |
Construct a BSONObj from data in the proper format.
Use this constructor when you want BSONObj to free(holder) when it is no longer needed BSONObj::Holder has an extra 4 bytes for a ref-count before the start of the object
bson::BSONObj::BSONObj | ( | ) |
Construct an empty BSONObj – that is, {}.
BSONObjIterator bson::BSONObj::begin | ( | ) | const |
use something like this: for( BSONObj::iterator i = myObj.begin(); i.more(); ) { BSONElement e = i.next(); ...
}
BSONObj bson::BSONObj::copy | ( | ) | 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
|
inline |
bool bson::BSONObj::getBoolField | ( | const char * | name | ) | const |
BSONElement bson::BSONObj::getField | ( | const StringData & | name | ) | const |
Get the field of the specified name.
eoo() is true on the returned element if not found.
BSONElement bson::BSONObj::getFieldDotted | ( | const char * | name | ) | const |
name | field to find. supports dot (".") notation to reach into embedded objects. for example "x.y" means "in the nested object in field x, retrieve field y" |
|
inline |
name | field to find. supports dot (".") notation to reach into embedded objects. for example "x.y" means "in the nested object in field x, retrieve field y" |
BSONElement bson::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 bson::BSONObj::getFieldNames | ( | set< string > & | fields | ) | const |
adds the field names to the fields set.
does NOT clear it (appends).
void bson::BSONObj::getFields | ( | unsigned | n, |
const char ** | fieldNames, | ||
BSONElement * | fields | ||
) | const |
Get several fields at once.
This is faster than separate getField() calls as the size of elements iterated can then be calculated only once each.
n | number of fieldNames, and number of elements in the fields array |
fields | if a field is found its element is stored in its corresponding position in this array. if not found the array element is unchanged. |
void bson::BSONObj::getFieldsDotted | ( | const StringData & | name, |
BSONElementSet & | ret | ||
) | const |
Like getFieldDotted(), but expands arrays and returns all matching objects.
TODO(jbenet). trace bool expandLastArray param.
int bson::BSONObj::getIntField | ( | const char * | name | ) | const |
BSONObj bson::BSONObj::getObjectField | ( | const char * | name | ) | const |
bool bson::BSONObj::getObjectID | ( | BSONElement & | e | ) | const |
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.
BSONObj bson::BSONObj::getOwned | ( | ) | const |
const char* bson::BSONObj::getStringField | ( | const char * | name | ) | const |
|
inline |
|
inline |
|
inline |
|
inline |
|
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
bool bson::BSONObj::isValid | ( | ) | const |
performs a cursory check on the object's size only.
string bson::BSONObj::jsonString | ( | JsonStringFormat | format = Strict , |
int | pretty = 0 |
||
) | const |
Properly formatted JSON string.
pretty | if true we try to add some lf's and indentation |
string bson::BSONObj::md5 | ( | ) | const |
|
inline |
|
inline |
bool bson::BSONObj::okForStorage | ( | ) | const |
|
inline |
Get the field of the specified name.
eoo() is true on the returned element if not found.
Return new object with the field names replaced by those in the passed object.
|
inline |
This is "shallow equality" – ints and doubles won't match.
for a deep equality test use woCompare (which is slower).
string bson::BSONObj::toString | ( | bool | isArray = false , |
bool | full = false , |
||
bool | noThrow = true |
||
) | const |
Readable representation of a BSON object in an extended JSON-style notation.
This is an abbreviated representation which might be used for logging.
void bson::BSONObj::Vals | ( | vector< T > & | ) | 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);
void bson::BSONObj::Vals | ( | list< T > & | ) | const |
add all values of the object to the specified list.
If type mismatches, exception.
void bson::BSONObj::vals | ( | vector< T > & | ) | const |
add all values of the object to the specified vector.
If type mismatches, skip.
void bson::BSONObj::vals | ( | list< T > & | ) | const |
add all values of the object to the specified list.
If type mismatches, skip.
int bson::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.
int bson::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.
int bson::BSONObj::woSortOrder | ( | const BSONObj & | r, |
const BSONObj & | sortKey, | ||
bool | useDotted = false |
||
) | const |
useDotted | whether to treat sort key fields as possibly dotted and expand into them |