MongoDB  2.7.0
Classes | Public Member Functions | Friends | List of all members
mongo::BSONElement Class Reference

BSONElement represents an "element" in a BSONObj. More...

#include <bsonelement.h>

Classes

struct  FieldNameSizeTag
 

Public Member Functions

std::string String () const
 These functions, which start with a capital letter, throw a MsgAssertionException if the element is not of the required type. More...
 
Date_t Date () const
 
double Number () const
 
double Double () const
 
long long Long () const
 
int Int () const
 
bool Bool () const
 
std::vector< BSONElementArray () const
 
mongo::OID OID () const
 
void Null () const
 
void OK () const
 
BSONObj Obj () const
 
void Val (Date_t &v) const
 populate v with the value of the element. More...
 
void Val (long long &v) const
 
void Val (bool &v) const
 
void Val (BSONObj &v) const
 
void Val (mongo::OID &v) const
 
void Val (int &v) const
 
void Val (double &v) const
 
void Val (std::string &v) const
 
bool ok () const
 Use ok() to check if a value is assigned: if( myObj["foo"].ok() ) ...
 
std::string toString (bool includeFieldName=true, bool full=false) const
 
void toString (StringBuilder &s, bool includeFieldName=true, bool full=false, int depth=0) const
 
std::string jsonString (JsonStringFormat format, bool includeFieldNames=true, int pretty=0) const
 
 operator std::string () const
 
BSONType type () const
 Returns the type of the element.
 
BSONElement operator[] (const std::string &field) const
 retrieve a field within this element throws exception if *this is not an embedded object
 
int canonicalType () const
 See canonicalizeBSONType in bsontypes.h.
 
bool eoo () const
 Indicates if it is the end-of-object element, which is present at the end of every BSON object.
 
int size (int maxLen) const
 Size of the element. More...
 
int size () const
 
BSONObj wrap () const
 Wrap this element up as a singleton object. More...
 
BSONObj wrap (const StringData &newName) const
 Wrap this element up as a singleton object with a new name. More...
 
const char * fieldName () const
 field name of the element. More...
 
int fieldNameSize () const
 NOTE: size includes the NULL terminator.
 
const StringData fieldNameStringData () const
 
const char * value () const
 raw data of the element's value (so be careful). More...
 
int valuesize () const
 size in bytes of the element's value (when applicable). More...
 
bool isBoolean () const
 
bool boolean () const
 
bool booleanSafe () const
 
Date_t date () const
 Retrieve a java style date value from the element. More...
 
bool trueValue () const
 Convert the value to boolean, regardless of its type, in a javascript-like fashion (i.e., treats zero and null and eoo as false).
 
bool isSimpleType () const
 True if number, string, bool, date, OID.
 
bool isNumber () const
 True if element is of a numeric type. More...
 
double _numberDouble () const
 Return double value for this field. More...
 
int _numberInt () const
 Return int value for this field. More...
 
long long _numberLong () const
 Return long long value for this field. More...
 
int numberInt () const
 Retrieve int value for the element safely. More...
 
long long numberLong () const
 Retrieve long value for the element safely. More...
 
long long safeNumberLong () const
 Like numberLong() but with well-defined behavior for doubles that are NaNs, or too large/small to be represented as long longs. More...
 
double numberDouble () const
 Retrieve the numeric value of the element. More...
 
double number () const
 Retrieve the numeric value of the element. More...
 
const mongo::OID__oid () const
 Retrieve the object ID stored in the object. More...
 
bool isNull () const
 True if element is null. More...
 
int valuestrsize () const
 Size (length) of a string element. More...
 
size_t objsize () const
 
const char * valuestr () const
 Get a string's value. More...
 
const char * valuestrsafe () const
 Get the string value of the element. More...
 
std::string str () const
 Get the string value of the element. More...
 
const char * codeWScopeCode () const
 Get javascript code of a CodeWScope data element. More...
 
int codeWScopeCodeLen () const
 Get length of the code part of the CodeWScope object This INCLUDES the null char at the end.
 
const char * codeWScopeScopeDataUnsafe () const
 Get the scope SavedContext of a CodeWScope data element. More...
 
const char * codeWScopeScopeData () const
 
BSONObj embeddedObject () const
 Get the embedded object this element holds. More...
 
BSONObj embeddedObjectUserCheck () const
 
BSONObj codeWScopeObject () const
 
const char * binData (int &len) const
 Get raw binary data. More...
 
const char * binDataClean (int &len) const
 Get binary data. More...
 
BinDataType binDataType () const
 
const char * regex () const
 Retrieve the regex string for a Regex element.
 
const char * regexFlags () const
 Retrieve the regex flags (options) for a Regex element.
 
bool valuesEqual (const BSONElement &r) const
 like operator== but doesn't check the fieldname, just the value.
 
bool operator== (const BSONElement &r) const
 Returns true if elements are equal. More...
 
bool operator!= (const BSONElement &r) const
 Returns true if elements are unequal. More...
 
int woCompare (const BSONElement &e, bool considerFieldName=true) const
 Well ordered comparison. More...
 
const char * rawdata () const
 
int getGtLtOp (int def=0) const
 0 == Equality, just not defined yet
 
 BSONElement ()
 Constructs an empty element.
 
bool mayEncapsulate () const
 True if this element may contain subobjects. More...
 
bool isABSONObj () const
 True if this element can be a BSONObj.
 
Date_t timestampTime () const
 
unsigned int timestampInc () const
 
unsigned long long timestampValue () const
 
const char * dbrefNS () const
 
const mongo::OIDdbrefOID () const
 
bool operator< (const BSONElement &other) const
 this does not use fieldName in the comparison, just the value
 
 BSONElement (const char *d, int maxLen)
 
 BSONElement (const char *d)
 
 BSONElement (const char *d, int fieldNameSize, FieldNameSizeTag)
 Construct a BSONElement where you already know the length of the name. More...
 
std::string _asCode () const
 
OpTime _opTime () const
 
template<typename T >
bool coerce (T *out) const
 
template<>
bool coerce (int *out) const
 
template<>
bool coerce (double *out) const
 
template<>
bool coerce (bool *out) const
 

Friends

class BSONObjIterator
 
class BSONObj
 

Detailed Description

BSONElement represents an "element" in a BSONObj.

So for the object { a : 3, b : "abc" }, 'a : 3' is the first element (key+value).

The BSONElement object points into the BSONObj's data. Thus the BSONObj must stay in scope for the life of the BSONElement.

internals: <type><fieldName>

-----— size() ---------— -fieldNameSize- value() type()

Constructor & Destructor Documentation

mongo::BSONElement::BSONElement ( const char *  d,
int  fieldNameSize,
FieldNameSizeTag   
)
inline

Construct a BSONElement where you already know the length of the name.

The value passed here includes the null terminator. The data pointed to by 'd' must not represent an EOO. You may pass -1 to indicate that you don't actually know the size.

Member Function Documentation

const mongo::OID& mongo::BSONElement::__oid ( ) const
inline

Retrieve the object ID stored in the object.

You must ensure the element is of type jstOID first.

double mongo::BSONElement::_numberDouble ( ) const
inline

Return double value for this field.

MUST be NumberDouble type.

int mongo::BSONElement::_numberInt ( ) const
inline

Return int value for this field.

MUST be NumberInt type.

long long mongo::BSONElement::_numberLong ( ) const
inline

Return long long value for this field.

MUST be NumberLong type.

const char* mongo::BSONElement::binData ( int &  len) const
inline

Get raw binary data.

Element must be of type BinData. Doesn't handle type 2 specially

const char* mongo::BSONElement::binDataClean ( int &  len) const
inline

Get binary data.

Element must be of type BinData. Handles type 2

bool mongo::BSONElement::boolean ( ) const
inline
Returns
value of a boolean element. You must assure element is a boolean before calling.
const char* mongo::BSONElement::codeWScopeCode ( ) const
inline

Get javascript code of a CodeWScope data element.

const char* mongo::BSONElement::codeWScopeScopeDataUnsafe ( ) const
inline

Get the scope SavedContext of a CodeWScope data element.

This function is DEPRECATED, since it can error if there are null chars in the codeWScopeCode. However, some existing indexes may be based on an incorrect ordering derived from this function, so it may still need to be used in certain cases.

Date_t mongo::BSONElement::date ( ) const
inline

Retrieve a java style date value from the element.

Ensure element is of type Date before calling.

See Also
Bool(), trueValue()
BSONObj mongo::BSONElement::embeddedObject ( ) const
inline

Get the embedded object this element holds.

const char* mongo::BSONElement::fieldName ( ) const
inline

field name of the element.

e.g., for name : "Joe" "name" is the fieldname

bool mongo::BSONElement::isNull ( ) const
inline

True if element is null.

bool mongo::BSONElement::isNumber ( ) const
inline

True if element is of a numeric type.

Returns
true if element is of a numeric type.
bool mongo::BSONElement::mayEncapsulate ( ) const
inline

True if this element may contain subobjects.

double mongo::BSONElement::number ( ) const
inline

Retrieve the numeric value of the element.

If not of a numeric type, returns 0. Note: casts to double, data loss may occur with large (>52 bit) NumberLong values.

double mongo::BSONElement::numberDouble ( ) const
inline

Retrieve the numeric value of the element.

If not of a numeric type, returns 0. Note: casts to double, data loss may occur with large (>52 bit) NumberLong values.

int mongo::BSONElement::numberInt ( ) const
inline

Retrieve int value for the element safely.

Zero returned if not a number.

Zero returned if not a number. Converted to int if another numeric type.

long long mongo::BSONElement::numberLong ( ) const
inline

Retrieve long value for the element safely.

Zero returned if not a number. Behavior is not defined for double values that are NaNs, or too large/small to be represented by long longs

Zero returned if not a number.

BSONObj mongo::BSONElement::Obj ( ) const
inline
Returns
the embedded object associated with this field. Note the returned object is a reference to within the parent bson object. If that object is out of scope, this pointer will no longer be valid. Call getOwned() on the returned BSONObj if you need your own copy. throws UserException if the element is not of type object.
bool mongo::BSONElement::operator!= ( const BSONElement r) const
inline

Returns true if elements are unequal.

bool mongo::BSONElement::operator== ( const BSONElement r) const
inline

Returns true if elements are equal.

long long mongo::BSONElement::safeNumberLong ( ) const
inline

Like numberLong() but with well-defined behavior for doubles that are NaNs, or too large/small to be represented as long longs.

NaNs -> 0 very large doubles -> LLONG_MAX very small doubles -> LLONG_MIN

int mongo::BSONElement::size ( int  maxLen) const
inline

Size of the element.

Parameters
maxLenIf maxLen is specified, don't scan more than maxLen bytes to calculate size.
std::string mongo::BSONElement::str ( ) const
inline

Get the string value of the element.

If not a string returns "".

std::string mongo::BSONElement::String ( ) const
inline

These functions, which start with a capital letter, throw a MsgAssertionException if the element is not of the required type.

Example:

std::string foo = obj["foo"].String(); // std::exception if not a std::string type or DNE

void mongo::BSONElement::Val ( Date_t v) const
inline

populate v with the value of the element.

If type does not match, throw exception. useful in templates – see also BSONObj::Vals().

const char* mongo::BSONElement::value ( ) const
inline

raw data of the element's value (so be careful).

int mongo::BSONElement::valuesize ( ) const
inline

size in bytes of the element's value (when applicable).

const char* mongo::BSONElement::valuestr ( ) const
inline

Get a string's value.

Also gives you start of the real data for an embedded object. You must assure data is of an appropriate type first – see also valuestrsafe().

const char* mongo::BSONElement::valuestrsafe ( ) const
inline

Get the string value of the element.

If not a string returns "".

int mongo::BSONElement::valuestrsize ( ) const
inline

Size (length) of a string element.

You must assure of type String first.

Returns
string size including terminating null
int mongo::BSONElement::woCompare ( const BSONElement e,
bool  considerFieldName = true 
) const
inline

Well ordered comparison.

Returns
<0: l<r. 0:l==r. >0:l>r order by type, field name, and field value. If considerFieldName is true, pay attention to the field name.
BSONObj mongo::BSONElement::wrap ( ) const
inline

Wrap this element up as a singleton object.

BSONObj mongo::BSONElement::wrap ( const StringData &  newName) const
inline

Wrap this element up as a singleton object with a new name.


The documentation for this class was generated from the following files: