bsonobjbuilder.h

/* bsonobjbuilder.h
 
   Classes in this file:
   BSONObjBuilder
   BSONArrayBuilder
*/
 
/*    Copyright 2009 10gen Inc.
 *
 *    Licensed under the Apache License, Version 2.0 (the "License");
 *    you may not use this file except in compliance with the License.
 *    You may obtain a copy of the License at
 *
 *    http://www.apache.org/licenses/LICENSE-2.0
 *
 *    Unless required by applicable law or agreed to in writing, software
 *    distributed under the License is distributed on an "AS IS" BASIS,
 *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *    See the License for the specific language governing permissions and
 *    limitations under the License.
 */
 
#pragma once
 
#include <boost/static_assert.hpp>
#include <map>
#include <cmath>
#include <limits>
 
#include "mongo/base/data_cursor.h"
#include "mongo/base/parse_number.h"
#include "mongo/bson/bson_field.h"
#include "mongo/bson/bsonelement.h"
#include "mongo/bson/bsonmisc.h"
#include "mongo/bson/bsonobj.h"
#include "mongo/bson/timestamp.h"
#include "mongo/client/export_macros.h"
 
namespace mongo {
 
#if defined(_WIN32)
// warning: 'this' : used in base member initializer list
#pragma warning( disable : 4355 )
#endif
 
    inline void checkFieldName(StringData fieldName) {
        uassert(0, "field name cannot contain null bytes", fieldName.find('\0') == std::string::npos);
    }
 
    class MONGO_CLIENT_API BSONObjBuilder : boost::noncopyable {
    public:
        BSONObjBuilder(int initsize=512)
            : _b(_buf)
            , _buf(sizeof(BSONObj::Holder) + initsize)
            , _offset(sizeof(BSONObj::Holder))
            , _s(this)
            , _tracker(0)
            , _doneCalled(false) {
            // Skip over space for a holder object at the beginning of the buffer, followed by
            // space for the object length. The length is filled in by _done.
            _b.skip(sizeof(BSONObj::Holder));
            _b.skip(sizeof(int));
 
            // Reserve space for the EOO byte. This means _done() can't fail.
            _b.reserveBytes(1);
        }
 
        BSONObjBuilder(BufBuilder &baseBuilder)
            : _b(baseBuilder)
            , _buf(0)
            , _offset(baseBuilder.len())
            , _s(this)
            , _tracker(0)
            , _doneCalled(false) {
            // Skip over space for the object length, which is filled in by _done. We don't need a
            // holder since we are a sub-builder, and some parent builder has already made the
            // reservation.
            _b.skip(sizeof(int));
 
            // Reserve space for the EOO byte. This means _done() can't fail.
            _b.reserveBytes(1);
        }
 
        BSONObjBuilder( const BSONSizeTracker & tracker )
            : _b(_buf)
            , _buf(sizeof(BSONObj::Holder) + tracker.getSize())
            , _offset(sizeof(BSONObj::Holder))
            , _s(this)
            , _tracker(const_cast<BSONSizeTracker*>(&tracker))
            , _doneCalled(false) {
            // See the comments in the first constructor for details.
            _b.skip(sizeof(BSONObj::Holder));
            _b.skip(sizeof(int));
 
            // Reserve space for the EOO byte. This means _done() can't fail.
            _b.reserveBytes(1);
        }
 
        ~BSONObjBuilder() {
            // If 'done' has not already been called, and we have a reference to an owning
            // BufBuilder but do not own it ourselves, then we must call _done to write in the
            // length. Otherwise, we own this memory and its lifetime ends with us, therefore
            // we can elide the write.
            if ( !_doneCalled && _b.buf() && _buf.getSize() == 0 ) {
                _done();
            }
        }
 
        BSONObjBuilder& appendElements(BSONObj x);
 
        BSONObjBuilder& appendElementsUnique( BSONObj x );
 
        BSONObjBuilder& append( const BSONElement& e) {
            checkFieldName(e.fieldNameStringData());
            verify( !e.eoo() ); // do not append eoo, that would corrupt us. the builder auto appends when done() is called.
            _b.appendBuf((void*) e.rawdata(), e.size());
            return *this;
        }
 
        BSONObjBuilder& appendAs(const BSONElement& e, const StringData& fieldName) {
            checkFieldName(fieldName);
            verify( !e.eoo() ); // do not append eoo, that would corrupt us. the builder auto appends when done() is called.
            _b.appendNum((char) e.type());
            _b.appendStr(fieldName);
            _b.appendBuf((void *) e.value(), e.valuesize());
            return *this;
        }
 
        BSONObjBuilder& append(const StringData& fieldName, BSONObj subObj) {
            checkFieldName(fieldName);
            _b.appendNum((char) Object);
            _b.appendStr(fieldName);
            _b.appendBuf((void *) subObj.objdata(), subObj.objsize());
            return *this;
        }
 
        BSONObjBuilder& appendObject(const StringData& fieldName, const char * objdata , int size = 0 ) {
            checkFieldName(fieldName);
            verify( objdata );
            if ( size == 0 ) {
                size = ConstDataView(objdata).readLE<int>();
            }
 
            verify( size > 4 && size < 100000000 );
 
            _b.appendNum((char) Object);
            _b.appendStr(fieldName);
            _b.appendBuf((void*)objdata, size );
            return *this;
        }
 
        BufBuilder &subobjStart(const StringData& fieldName) {
            checkFieldName(fieldName);
            _b.appendNum((char) Object);
            _b.appendStr(fieldName);
            return _b;
        }
 
        BSONObjBuilder& appendArray(const StringData& fieldName, const BSONObj &subObj) {
            checkFieldName(fieldName);
            _b.appendNum((char) Array);
            _b.appendStr(fieldName);
            _b.appendBuf((void *) subObj.objdata(), subObj.objsize());
            return *this;
        }
        BSONObjBuilder& append(const StringData& fieldName, BSONArray arr) {
            return appendArray(fieldName, arr);
        }
 
        BufBuilder &subarrayStart(const StringData& fieldName) {
            checkFieldName(fieldName);
            _b.appendNum((char) Array);
            _b.appendStr(fieldName);
            return _b;
        }
 
        BSONObjBuilder& appendBool(const StringData& fieldName, int val) {
            checkFieldName(fieldName);
            _b.appendNum((char) Bool);
            _b.appendStr(fieldName);
            _b.appendNum((char) (val?1:0));
            return *this;
        }
 
        BSONObjBuilder& append(const StringData& fieldName, bool val) {
            checkFieldName(fieldName);
            _b.appendNum((char) Bool);
            _b.appendStr(fieldName);
            _b.appendNum((char) (val?1:0));
            return *this;
        }
 
        BSONObjBuilder& append(const StringData& fieldName, int n) {
            checkFieldName(fieldName);
            _b.appendNum((char) NumberInt);
            _b.appendStr(fieldName);
            _b.appendNum(n);
            return *this;
        }
 
        BSONObjBuilder& append(const StringData& fieldName, unsigned n) {
            return append(fieldName, (int) n);
        }
 
        BSONObjBuilder& append(const StringData& fieldName, long long n) {
            checkFieldName(fieldName);
            _b.appendNum((char) NumberLong);
            _b.appendStr(fieldName);
            _b.appendNum(n);
            return *this;
        }
 
        BSONObjBuilder& appendIntOrLL( const StringData& fieldName , long long n ) {
            // extra () to avoid max macro on windows
            static const long long maxInt = (std::numeric_limits<int>::max)() / 2;
            static const long long minInt = -maxInt;
            if ( minInt < n && n < maxInt ) {
                append( fieldName , static_cast<int>( n ) );
            }
            else {
                append( fieldName , n );
            }
            return *this;
        }
 
        BSONObjBuilder& appendNumber( const StringData& fieldName , int n ) {
            return append( fieldName , n );
        }
 
        BSONObjBuilder& appendNumber( const StringData& fieldName , double d ) {
            return append( fieldName , d );
        }
 
        BSONObjBuilder& appendNumber( const StringData& fieldName , size_t n ) {
            static const size_t maxInt = ( 1 << 30 );
 
            if ( n < maxInt )
                append( fieldName, static_cast<int>( n ) );
            else
                append( fieldName, static_cast<long long>( n ) );
            return *this;
        }
 
        BSONObjBuilder& appendNumber( const StringData& fieldName, long long llNumber ) {
            static const long long maxInt = ( 1LL << 30 );
            static const long long minInt = -maxInt;
            static const long long maxDouble = ( 1LL << 40 );
            static const long long minDouble = -maxDouble;
 
            if ( minInt < llNumber && llNumber < maxInt ) {
                append( fieldName, static_cast<int>( llNumber ) );
            }
            else if ( minDouble < llNumber && llNumber < maxDouble ) {
                append( fieldName, static_cast<double>( llNumber ) );
            }
            else {
                append( fieldName, llNumber );
            }
 
            return *this;
        }
 
        BSONObjBuilder& append(const StringData& fieldName, double n) {
            checkFieldName(fieldName);
            _b.appendNum((char) NumberDouble);
            _b.appendStr(fieldName);
            _b.appendNum(n);
            return *this;
        }
 
        bool appendAsNumber( const StringData& fieldName , const std::string& data );
 
        BSONObjBuilder& appendOID(const StringData& fieldName, OID *oid = 0 , bool generateIfBlank = false ) {
            checkFieldName(fieldName);
            _b.appendNum((char) jstOID);
            _b.appendStr(fieldName);
            if ( oid )
                _b.appendBuf( oid->view().view(), OID::kOIDSize );
            else {
                OID tmp;
                if ( generateIfBlank )
                    tmp.init();
                else
                    tmp.clear();
                _b.appendBuf( tmp.view().view(), OID::kOIDSize );
            }
            return *this;
        }
 
        BSONObjBuilder& append( const StringData& fieldName, OID oid ) {
            checkFieldName(fieldName);
            _b.appendNum((char) jstOID);
            _b.appendStr(fieldName);
            _b.appendBuf( oid.view().view(), OID::kOIDSize );
            return *this;
        }
 
        BSONObjBuilder& genOID() {
            return append("_id", OID::gen());
        }
 
        BSONObjBuilder& appendTimeT(const StringData& fieldName, time_t dt) {
            checkFieldName(fieldName);
            _b.appendNum((char) Date);
            _b.appendStr(fieldName);
            _b.appendNum(static_cast<unsigned long long>(dt) * 1000);
            return *this;
        }
        BSONObjBuilder& appendDate(const StringData& fieldName, Date_t dt);
        BSONObjBuilder& append(const StringData& fieldName, Date_t dt) {
            return appendDate(fieldName, dt);
        }
 
        BSONObjBuilder& appendRegex(const StringData& fieldName, const StringData& regex, const StringData& options = "") {
            checkFieldName(fieldName);
            uassert(0, "regex cannot contain null bytes", regex.find('\0') == std::string::npos);
            _b.appendNum((char) RegEx);
            _b.appendStr(fieldName);
            _b.appendStr(regex);
            _b.appendStr(options);
            return *this;
        }
 
        BSONObjBuilder& append(const StringData& fieldName, const BSONRegEx& regex) {
            return appendRegex(fieldName, regex.pattern, regex.flags);
        }
 
        BSONObjBuilder& appendCode(const StringData& fieldName, const StringData& code) {
            checkFieldName(fieldName);
            _b.appendNum((char) Code);
            _b.appendStr(fieldName);
            _b.appendNum((int) code.size()+1);
            _b.appendStr(code);
            return *this;
        }
 
        BSONObjBuilder& append(const StringData& fieldName, const BSONCode& code) {
            return appendCode(fieldName, code.code);
        }
 
        BSONObjBuilder& append(const StringData& fieldName, const char *str, int sz) {
            checkFieldName(fieldName);
            _b.appendNum((char) String);
            _b.appendStr(fieldName);
            _b.appendNum((int)sz);
            _b.appendBuf(str, sz);
            return *this;
        }
        BSONObjBuilder& append(const StringData& fieldName, const char *str) {
            return append(fieldName, str, (int) strlen(str)+1);
        }
        BSONObjBuilder& append(const StringData& fieldName, const std::string& str) {
            return append(fieldName, str.c_str(), (int) str.size()+1);
        }
        BSONObjBuilder& append(const StringData& fieldName, const StringData& str) {
            checkFieldName(fieldName);
            _b.appendNum((char) String);
            _b.appendStr(fieldName);
            _b.appendNum((int)str.size()+1);
            _b.appendStr(str, true);
            return *this;
        }
 
        BSONObjBuilder& appendSymbol(const StringData& fieldName, const StringData& symbol) {
            checkFieldName(fieldName);
            _b.appendNum((char) Symbol);
            _b.appendStr(fieldName);
            _b.appendNum((int) symbol.size()+1);
            _b.appendStr(symbol);
            return *this;
        }
 
        BSONObjBuilder& append(const StringData& fieldName, const BSONSymbol& symbol) {
            return appendSymbol(fieldName, symbol.symbol);
        }
 
        void appendNull() {
            msgasserted(16234, "Invalid call to appendNull in BSONObj Builder.");
        }
 
        BSONObjBuilder& appendNull( const StringData& fieldName ) {
            checkFieldName(fieldName);
            _b.appendNum( (char) jstNULL );
            _b.appendStr( fieldName );
            return *this;
        }
 
        // Append an element that is less than all other keys.
        BSONObjBuilder& appendMinKey( const StringData& fieldName ) {
            checkFieldName(fieldName);
            _b.appendNum( (char) MinKey );
            _b.appendStr( fieldName );
            return *this;
        }
        // Append an element that is greater than all other keys.
        BSONObjBuilder& appendMaxKey( const StringData& fieldName ) {
            checkFieldName(fieldName);
            _b.appendNum( (char) MaxKey );
            _b.appendStr( fieldName );
            return *this;
        }
 
        BSONObjBuilder& appendTimestamp( const StringData& fieldName , const Timestamp_t& ts = Timestamp_t() ) {
            checkFieldName(fieldName);
            _b.appendNum( (char) Timestamp );
            _b.appendStr( fieldName );
 
            char buf[2 * sizeof(uint32_t)];
            DataCursor cur(buf);
            cur.writeLEAndAdvance<>(ts.increment());
            cur.writeLEAndAdvance<>(ts.seconds());
 
            _b.appendBuf(buf, sizeof(buf));
            return *this;
        }
 
        BSONObjBuilder& append( const StringData& fieldName, const Timestamp_t& ts ) {
            return appendTimestamp(fieldName, ts);
        }
 
        /*
        Append an element of the deprecated DBRef type.
        @deprecated
        */
        BSONObjBuilder& appendDBRef( const StringData& fieldName, const StringData& ns, const OID &oid ) {
            checkFieldName(fieldName);
            _b.appendNum( (char) DBRef );
            _b.appendStr( fieldName );
            _b.appendNum( (int) ns.size() + 1 );
            _b.appendStr( ns );
            _b.appendBuf( oid.view().view(), OID::kOIDSize );
            return *this;
        }
 
        BSONObjBuilder& append(const StringData& fieldName, const BSONDBRef& dbref) {
            return appendDBRef(fieldName, dbref.ns, dbref.oid);
        }
 
        BSONObjBuilder& appendBinData( const StringData& fieldName, int len, BinDataType type, const void *data ) {
            checkFieldName(fieldName);
            _b.appendNum( (char) BinData );
            _b.appendStr( fieldName );
            _b.appendNum( len );
            _b.appendNum( (char) type );
            _b.appendBuf( data, len );
            return *this;
        }
 
        BSONObjBuilder& append(const StringData& fieldName, const BSONBinData& bd) {
            return appendBinData(fieldName, bd.length, bd.type, bd.data);
        }
 
        BSONObjBuilder& appendBinDataArrayDeprecated( const char * fieldName , const void * data , int len ) {
            checkFieldName(fieldName);
            _b.appendNum( (char) BinData );
            _b.appendStr( fieldName );
            _b.appendNum( len + 4 );
            _b.appendNum( (char)0x2 );
            _b.appendNum( len );
            _b.appendBuf( data, len );
            return *this;
        }
 
        BSONObjBuilder& appendCodeWScope( const StringData& fieldName, const StringData& code, const BSONObj &scope ) {
            checkFieldName(fieldName);
            _b.appendNum( (char) CodeWScope );
            _b.appendStr( fieldName );
            _b.appendNum( ( int )( 4 + 4 + code.size() + 1 + scope.objsize() ) );
            _b.appendNum( ( int ) code.size() + 1 );
            _b.appendStr( code );
            _b.appendBuf( ( void * )scope.objdata(), scope.objsize() );
            return *this;
        }
 
        BSONObjBuilder& append(const StringData& fieldName, const BSONCodeWScope& cws) {
            return appendCodeWScope(fieldName, cws.code, cws.scope);
        }
 
        void appendUndefined( const StringData& fieldName ) {
            _b.appendNum( (char) Undefined );
            _b.appendStr( fieldName );
        }
 
        /* helper function -- see Query::where() for primary way to do this. */
        void appendWhere( const StringData& code, const BSONObj &scope ) {
            appendCodeWScope( "$where" , code , scope );
        }
 
        void appendMinForType( const StringData& fieldName , int type );
        void appendMaxForType( const StringData& fieldName , int type );
 
        template < class T >
        BSONObjBuilder& append( const StringData& fieldName, const std::vector< T >& vals );
 
        template < class T >
        BSONObjBuilder& append( const StringData& fieldName, const std::list< T >& vals );
 
        template < class T >
        BSONObjBuilder& append( const StringData& fieldName, const std::set< T >& vals );
 
        template < class K, class T >
        BSONObjBuilder& append( const StringData& fieldName, const std::map< K, T >& vals );
 
        BSONObj obj() {
            massert( 10335 , "builder does not own memory", owned() );
            doneFast();
            char* buf = _b.buf();
            decouple();
            return BSONObj::takeOwnership(buf);
        }
 
        BSONObj done() {
            return BSONObj(_done());
        }
 
        // Like 'done' above, but does not construct a BSONObj to return to the caller.
        void doneFast() {
            (void)_done();
        }
 
        BSONObj asTempObj() {
            BSONObj temp(_done());
            _b.setlen(_b.len()-1); //next append should overwrite the EOO
            _b.reserveBytes(1); // Rereserve room for the real EOO
            _doneCalled = false;
            return temp;
        }
 
        void abandon() {
            _doneCalled = true;
        }
 
        void decouple() {
            _b.decouple();    // post done() call version.  be sure jsobj frees...
        }
 
        void appendKeys( const BSONObj& keyPattern , const BSONObj& values );
 
        static std::string MONGO_CLIENT_FUNC numStr( int i ) {
            if (i>=0 && i<100 && numStrsReady)
                return numStrs[i];
            StringBuilder o;
            o << i;
            return o.str();
        }
 
        BSONObjBuilderValueStream &operator<<( const StringData& name ) {
            _s.endField( name );
            return _s;
        }
 
        BSONObjBuilder& operator<<( GENOIDLabeler ) { return genOID(); }
 
        Labeler operator<<( const Labeler::Label &l ) {
            massert( 10336 ,  "No subobject started", _s.subobjStarted() );
            return _s << l;
        }
 
        template<typename T>
        BSONObjBuilderValueStream& operator<<( const BSONField<T>& f ) {
            _s.endField( f.name() );
            return _s;
        }
 
        template<typename T>
        BSONObjBuilder& operator<<( const BSONFieldValue<T>& v ) {
            append( v.name(), v.value() );
            return *this;
        }
 
        BSONObjBuilder& operator<<( const BSONElement& e ){
            append( e );
            return *this;
        }
 
        bool isArray() const {
            return false;
        }
 
        bool owned() const { return &_b == &_buf; }
 
        BSONObjIterator iterator() const ;
 
        bool hasField( const StringData& name ) const ;
 
        int len() const { return _b.len(); }
 
        BufBuilder& bb() { return _b; }
 
    private:
        char* _done() {
            if ( _doneCalled )
                return _b.buf() + _offset;
 
            _doneCalled = true;
 
            // TODO remove this or find some way to prevent it from failing. Since this is intended
            // for use with BSON() literal queries, it is less likely to result in oversized BSON.
            _s.endField();
 
            _b.claimReservedBytes(1); // Prevents adding EOO from failing.
            _b.appendNum((char) EOO);
 
            char *data = _b.buf() + _offset;
            int size = _b.len() - _offset;
            DataView(data).writeLE(size);
            if ( _tracker )
                _tracker->got( size );
            return data;
        }
 
        BufBuilder &_b;
        BufBuilder _buf;
        int _offset;
        BSONObjBuilderValueStream _s;
        BSONSizeTracker * _tracker;
        bool _doneCalled;
 
        static const std::string numStrs[100]; // cache of 0 to 99 inclusive
        static bool numStrsReady; // for static init safety.
    };
 
    class BSONArrayBuilder : boost::noncopyable {
    public:
        BSONArrayBuilder() : _i(0), _b() {}
        BSONArrayBuilder( BufBuilder &_b ) : _i(0), _b(_b) {}
        BSONArrayBuilder( int initialSize ) : _i(0), _b(initialSize) {}
 
        template <typename T>
        BSONArrayBuilder& append(const T& x) {
            _b.append(num(), x);
            return *this;
        }
 
        BSONArrayBuilder& append(const BSONElement& e) {
            _b.appendAs(e, num());
            return *this;
        }
 
        BSONArrayBuilder& operator<<(const BSONElement& e) {
            return append(e);
        }
 
        template <typename T>
        BSONArrayBuilder& operator<<(const T& x) {
            _b << num().c_str() << x;
            return *this;
        }
 
        void appendNull() {
            _b.appendNull(num());
        }
 
        void appendUndefined() {
            _b.appendUndefined(num());
        }
 
        BSONArray arr() { return BSONArray(_b.obj()); }
        BSONObj obj() { return _b.obj(); }
 
        BSONObj done() { return _b.done(); }
 
        void doneFast() { _b.doneFast(); }
 
        template < class T >
        BSONArrayBuilder& append( const std::list< T >& vals );
 
        template < class T >
        BSONArrayBuilder& append( const std::set< T >& vals );
 
        // These two just use next position
        BufBuilder &subobjStart() { return _b.subobjStart( num() ); }
        BufBuilder &subarrayStart() { return _b.subarrayStart( num() ); }
 
        BSONArrayBuilder& appendRegex(const StringData& regex, const StringData& options = "") {
            uassert(0, "regex cannot contain null bytes", regex.find('\0') == std::string::npos);
            _b.appendRegex(num(), regex, options);
            return *this;
        }
 
        BSONArrayBuilder& appendBinData(int len, BinDataType type, const void* data) {
            _b.appendBinData(num(), len, type, data);
            return *this;
        }
 
        BSONArrayBuilder& appendCode(const StringData& code) {
            _b.appendCode(num(), code);
            return *this;
        }
 
        BSONArrayBuilder& appendCodeWScope(const StringData& code, const BSONObj& scope) {
            _b.appendCodeWScope(num(), code, scope);
            return *this;
        }
 
        BSONArrayBuilder& appendTimeT(time_t dt) {
            _b.appendTimeT(num(), dt);
            return *this;
        }
 
        BSONArrayBuilder& appendDate(Date_t dt) {
            _b.appendDate(num(), dt);
            return *this;
        }
 
        BSONArrayBuilder& appendBool(bool val) {
            _b.appendBool(num(), val);
            return *this;
        }
 
        bool isArray() const {
            return true;
        }
 
        int len() const { return _b.len(); }
        int arrSize() const { return _i; }
 
        BufBuilder& bb() { return _b.bb(); }
 
    private:
 
        std::string num() { return _b.numStr(_i++); }
        int _i;
        BSONObjBuilder _b;
    };
 
    template < class T >
    inline BSONObjBuilder& BSONObjBuilder::append( const StringData& fieldName, const std::vector< T >& vals ) {
        BSONObjBuilder arrBuilder;
        for ( unsigned int i = 0; i < vals.size(); ++i )
            arrBuilder.append( numStr( i ), vals[ i ] );
        appendArray( fieldName, arrBuilder.done() );
        return *this;
    }
 
    template < class L >
    inline BSONObjBuilder& _appendIt( BSONObjBuilder& _this, const StringData& fieldName, const L& vals ) {
        BSONObjBuilder arrBuilder;
        int n = 0;
        for( typename L::const_iterator i = vals.begin(); i != vals.end(); i++ )
            arrBuilder.append( BSONObjBuilder::numStr(n++), *i );
        _this.appendArray( fieldName, arrBuilder.done() );
        return _this;
    }
 
    template < class T >
    inline BSONObjBuilder& BSONObjBuilder::append( const StringData& fieldName, const std::list< T >& vals ) {
        return _appendIt< std::list< T > >( *this, fieldName, vals );
    }
 
    template < class T >
    inline BSONObjBuilder& BSONObjBuilder::append( const StringData& fieldName, const std::set< T >& vals ) {
        return _appendIt< std::set< T > >( *this, fieldName, vals );
    }
 
    template < class K, class T >
    inline BSONObjBuilder& BSONObjBuilder::append( const StringData& fieldName, const std::map< K, T >& vals ) {
        BSONObjBuilder bob;
        for( typename std::map<K,T>::const_iterator i = vals.begin(); i != vals.end(); ++i ){
            bob.append(i->first, i->second);
        }
        append(fieldName, bob.obj());
        return *this;
    }
 
 
    template < class L >
    inline BSONArrayBuilder& _appendArrayIt( BSONArrayBuilder& _this, const L& vals ) {
        for( typename L::const_iterator i = vals.begin(); i != vals.end(); i++ )
            _this.append( *i );
        return _this;
    }
 
    template < class T >
    inline BSONArrayBuilder& BSONArrayBuilder::append( const std::list< T >& vals ) {
        return _appendArrayIt< std::list< T > >( *this, vals );
    }
 
    template < class T >
    inline BSONArrayBuilder& BSONArrayBuilder::append( const std::set< T >& vals ) {
        return _appendArrayIt< std::set< T > >( *this, vals );
    }
 
    template<typename T>
    inline BSONFieldValue<BSONObj> BSONField<T>::query( const char * q , const T& t ) const {
        BSONObjBuilder b;
        b.append( q , t );
        return BSONFieldValue<BSONObj>( _name , b.obj() );
    }
 
    // $or helper: OR(BSON("x" << GT << 7), BSON("y" << LT 6));
    inline BSONObj OR(const BSONObj& a, const BSONObj& b)
    { return BSON( "$or" << BSON_ARRAY(a << b) ); }
    inline BSONObj OR(const BSONObj& a, const BSONObj& b, const BSONObj& c)
    { return BSON( "$or" << BSON_ARRAY(a << b << c) ); }
    inline BSONObj OR(const BSONObj& a, const BSONObj& b, const BSONObj& c, const BSONObj& d)
    { return BSON( "$or" << BSON_ARRAY(a << b << c << d) ); }
    inline BSONObj OR(const BSONObj& a, const BSONObj& b, const BSONObj& c, const BSONObj& d, const BSONObj& e)
    { return BSON( "$or" << BSON_ARRAY(a << b << c << d << e) ); }
    inline BSONObj OR(const BSONObj& a, const BSONObj& b, const BSONObj& c, const BSONObj& d, const BSONObj& e, const BSONObj& f)
    { return BSON( "$or" << BSON_ARRAY(a << b << c << d << e << f) ); }
 
}