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) {
        // do not append eoo, that would corrupt us. the builder auto appends when done() is called.
        verify(!e.eoo());
        _b.appendBuf((void*)e.rawdata(), e.size());
        return *this;
    }
 
    BSONObjBuilder& appendAs(const BSONElement& e, const StringData& fieldName) {
        // do not append eoo, that would corrupt us. the builder auto appends when done() is called.
        verify(!e.eoo());
        _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));
}
}