diff options
author | dwight <dwight@10gen.com> | 2010-11-29 23:50:20 -0500 |
---|---|---|
committer | dwight <dwight@10gen.com> | 2010-11-29 23:50:20 -0500 |
commit | e183f5d1447741fa0c5d9bbb0b82fb6ea9d6bdd5 (patch) | |
tree | f7008522db95f58ea0fded1ced01afa6088d8edc | |
parent | 1808b5693904a2e89bfa96dcafdbea5e9d491987 (diff) | |
download | mongo-e183f5d1447741fa0c5d9bbb0b82fb6ea9d6bdd5.tar.gz |
comments
-rw-r--r-- | bson/bsonobj.h | 57 | ||||
-rw-r--r-- | bson/bsonobjiterator.h | 12 |
2 files changed, 47 insertions, 22 deletions
diff --git a/bson/bsonobj.h b/bson/bsonobj.h index 66604336d50..33067ed1486 100644 --- a/bson/bsonobj.h +++ b/bson/bsonobj.h @@ -71,19 +71,42 @@ namespace mongo { /** Construct a BSONObj from data in the proper format. @param ifree true if the BSONObj should free() the msgdata when it destructs. - */ + */ explicit BSONObj(const char *msgdata, bool ifree = false) { init(msgdata, ifree); } + BSONObj(const Record *r); + /** Construct an empty BSONObj -- that is, {}. */ BSONObj(); + ~BSONObj() { /*defensive:*/ _objdata = 0; } - void appendSelfToBufBuilder(BufBuilder& b) const { - assert( objsize() ); - b.appendBuf(reinterpret_cast<const void *>( objdata() ), objsize()); - } + /** + A BSONObj can use a buffer it "owns" or one it does not. If the BSONObj owns the buffer, it will free() + it during ~BSONObj() destruction. + + You can specify ownership with the ifree parameter in the constructor. + + 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. + + On assignment of a BSONObj, the buffer pointer moves to the lvalue bsonobj, and is set to null on the rvalue. + This is a lot like auto_ptr semantics. The owned state transfers too. + + Why would it not be owned? To avoid a memcpy. For example if the source data exists in say, a memory mapped file, + we can reference it directly. + + @return true if the buffer is owned by *this. + */ + bool isOwned() const { return _holder.get() != 0; } + + /* make sure the data buffer is under the control of this BSONObj and not a remote buffer */ + BSONObj getOwned() const; + + /** @return a new full (and owned) copy of the object. */ + BSONObj copy() const; /** Readable representation of a BSON object in an extended JSON-style notation. This is an abbreviated representation which might be used for logging. @@ -198,9 +221,7 @@ namespace mongo { bool okForStorage() const; /** @return true if object is empty -- i.e., {} */ - bool isEmpty() const { - return objsize() <= 5; - } + bool isEmpty() const { return objsize() <= 5; } void dump() const; @@ -258,14 +279,6 @@ namespace mongo { */ bool getObjectID(BSONElement& e) const; - /** @return a new full copy of the object. */ - BSONObj copy() const; - - /* make sure the data buffer is under the control of this BSONObj and not a remote buffer */ - BSONObj getOwned() const; - - bool isOwned() const { return _holder.get() != 0; } - /** @return A hash code for the object */ int hash() const { unsigned x = 0; @@ -345,8 +358,20 @@ namespace mongo { friend class BSONObjIterator; typedef BSONObjIterator iterator; + + /** use something like this: + for( BSONObj::iterator i = myObj.begin(); i.more(); ) { + BSONElement e = i.next(); + ... + } + */ BSONObjIterator begin(); + void appendSelfToBufBuilder(BufBuilder& b) const { + assert( objsize() ); + b.appendBuf(reinterpret_cast<const void *>( objdata() ), objsize()); + } + private: class Holder { public: diff --git a/bson/bsonobjiterator.h b/bson/bsonobjiterator.h index c8224d2d6b6..de5d75bf7aa 100644 --- a/bson/bsonobjiterator.h +++ b/bson/bsonobjiterator.h @@ -20,6 +20,7 @@ #include <boost/preprocessor/cat.hpp> // like the ## operator but works with __LINE__ namespace mongo { + /** iterator for a BSONObj Note each BSONObj ends with an EOO element: so you will get more() on an empty @@ -48,12 +49,11 @@ namespace mongo { } /** @return true if more elements exist to be enumerated. */ - bool moreWithEOO() { - return _pos < _theend; - } - bool more(){ - return _pos < _theend && _pos[0]; - } + bool more() { return _pos < _theend && _pos[0]; } + + /** @return true if more elements exist to be enumerated INCLUDING the EOO element which is always at the end. */ + bool moreWithEOO() { return _pos < _theend; } + /** @return the next element in the object. For the final element, element.eoo() will be true. */ BSONElement next( bool checkEnd = false ) { assert( _pos < _theend ); |