MongoDB  2.7.0
element.h
1 /* Copyright 2013 10gen Inc.
2  *
3  * Licensed under the Apache License, Version 2.0 (the "License");
4  * you may not use this file except in compliance with the License.
5  * You may obtain a copy of the License at
6  *
7  * http://www.apache.org/licenses/LICENSE-2.0
8  *
9  * Unless required by applicable law or agreed to in writing, software
10  * distributed under the License is distributed on an "AS IS" BASIS,
11  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12  * See the License for the specific language governing permissions and
13  * limitations under the License.
14  */
15 
16 #pragma once
17 
18 #include "mongo/base/status.h"
19 #include "mongo/base/string_data.h"
20 #include "mongo/db/jsobj.h"
21 #include "mongo/platform/cstdint.h"
22 #include "mongo/util/safe_num.h"
23 
24 namespace mongo {
25 namespace mutablebson {
26 
29  class ConstElement;
30  class Document;
31 
99  class Element {
100  public:
101  typedef uint32_t RepIdx;
102 
103  // Some special RepIdx values. These are really implementation details, but they are
104  // here so that we can inline Element::OK, which gets called very frequently, and they
105  // need to be public so some free functions in document.cpp can use them. You must not
106  // use these values explicitly.
107 
108  // Used to signal an invalid Element.
109  static const RepIdx kInvalidRepIdx = RepIdx(-1);
110 
111  // A rep that points to an unexamined entity
112  static const RepIdx kOpaqueRepIdx = RepIdx(-2);
113 
114  // This is the highest valid rep that does not overlap flag values.
115  static const RepIdx kMaxRepIdx = RepIdx(-3);
116 
117  //
118  // Topology mutation API. Element arguments must belong to the same Document.
119  //
120 
124  Status addSiblingLeft(Element e);
125 
129  Status addSiblingRight(Element e);
130 
135  Status remove();
136 
140  Status pushFront(Element e);
141 
145  Status pushBack(Element e);
146 
148  Status popFront();
149 
151  Status popBack();
152 
154  Status rename(const StringData& newName);
155 
156 
157  //
158  // Navigation API.
159  //
160 
164  Element leftChild() const;
165 
170  Element rightChild() const;
171 
175  bool hasChildren() const;
176 
180  Element leftSibling(size_t distance = 1) const;
181 
185  Element rightSibling(size_t distance = 1) const;
186 
190  Element parent() const;
191 
196  Element findNthChild(size_t n) const;
197  inline Element operator[](size_t n) const;
198 
203  Element findFirstChildNamed(const StringData& name) const;
204  inline Element operator[](const StringData& name) const;
205 
211  Element findElementNamed(const StringData& name) const;
212 
213  //
214  // Counting API.
215  //
216 
218  size_t countSiblingsLeft() const;
219 
221  size_t countSiblingsRight() const;
222 
224  size_t countChildren() const;
225 
226  //
227  // Value access API.
228  //
229  // We only provide accessors for BSONElement and for simple types. For more complex
230  // types like regex you should obtain the BSONElement and use that API to extract the
231  // components.
232  //
233  // Note that the getValueX methods are *unchecked* in release builds: You are
234  // responsible for calling hasValue() to ensure that this element has a value
235  // representation, and for calling getType to ensure that the Element is of the proper
236  // type.
237  //
238  // As usual, methods here are in bsonspec type order, please keep them that way.
239  //
240 
245  bool hasValue() const;
246 
250  bool isNumeric() const;
251 
255  bool isIntegral() const;
256 
269  const BSONElement getValue() const;
270 
272  inline double getValueDouble() const;
273 
275  inline StringData getValueString() const;
276 
280  inline BSONObj getValueObject() const;
281 
285  inline BSONArray getValueArray() const;
286 
288  inline bool isValueUndefined() const;
289 
291  inline OID getValueOID() const;
292 
294  inline bool getValueBool() const;
295 
297  inline Date_t getValueDate() const;
298 
300  inline bool isValueNull() const;
301 
303  inline StringData getValueSymbol() const;
304 
306  inline int32_t getValueInt() const;
307 
309  inline OpTime getValueTimestamp() const;
310 
312  inline int64_t getValueLong() const;
313 
315  inline bool isValueMinKey() const;
316 
318  inline bool isValueMaxKey() const;
319 
321  SafeNum getValueSafeNum() const;
322 
323 
324  //
325  // Comparision API.
326  //
327 
337  int compareWithElement(const ConstElement& other, bool considerFieldName = true) const;
338 
347  int compareWithBSONElement(const BSONElement& other, bool considerFieldName = true) const;
348 
355  int compareWithBSONObj(const BSONObj& other, bool considerFieldName = true) const;
356 
357 
358  //
359  // Serialization API.
360  //
361 
363  void writeTo(BSONObjBuilder* builder) const;
364 
368  void writeArrayTo(BSONArrayBuilder* builder) const;
369 
370 
371  //
372  // Value mutation API. Please note that the types are ordered according to bsonspec.org
373  // ordering. Please keep them that way.
374  //
375 
377  Status setValueDouble(double value);
378 
380  Status setValueString(const StringData& value);
381 
385  Status setValueObject(const BSONObj& value);
386 
390  Status setValueArray(const BSONObj& value);
391 
393  Status setValueBinary(uint32_t len, mongo::BinDataType binType, const void* data);
394 
396  Status setValueUndefined();
397 
399  Status setValueOID(OID value);
400 
402  Status setValueBool(bool value);
403 
405  Status setValueDate(Date_t value);
406 
408  Status setValueNull();
409 
411  Status setValueRegex(const StringData& re, const StringData& flags);
412 
414  Status setValueDBRef(const StringData& ns, OID oid);
415 
417  Status setValueCode(const StringData& value);
418 
420  Status setValueSymbol(const StringData& value);
421 
423  Status setValueCodeWithScope(const StringData& code, const BSONObj& scope);
424 
426  Status setValueInt(int32_t value);
427 
429  Status setValueTimestamp(OpTime value);
430 
432  Status setValueLong(int64_t value);
433 
435  Status setValueMinKey();
436 
438  Status setValueMaxKey();
439 
440 
441  //
442  // Value mutation API from variant types.
443  //
444 
450  Status setValueBSONElement(const BSONElement& value);
451 
455  Status setValueSafeNum(const SafeNum value);
456 
457 
458  //
459  // Accessors
460  //
461 
463  inline bool ok() const;
464 
466  inline Document& getDocument();
467 
469  inline const Document& getDocument() const;
470 
472  BSONType getType() const;
473 
475  inline bool isType(BSONType type) const;
476 
482  StringData getFieldName() const;
483 
487  inline RepIdx getIdx() const;
488 
489 
490  //
491  // Stream API - BSONObjBuilder like API, but methods return a Status. These are
492  // strictly a convenience API. You don't need to use them if you would rather be more
493  // explicit.
494  //
495 
497  Status appendDouble(const StringData& fieldName, double value);
498 
500  Status appendString(const StringData& fieldName, const StringData& value);
501 
505  Status appendObject(const StringData& fieldName, const BSONObj& value);
506 
510  Status appendArray(const StringData& fieldName, const BSONObj& value);
511 
513  Status appendBinary(const StringData& fieldName,
514  uint32_t len, mongo::BinDataType binType, const void* data);
515 
517  Status appendUndefined(const StringData& fieldName);
518 
520  Status appendOID(const StringData& fieldName, mongo::OID value);
521 
523  Status appendBool(const StringData& fieldName, bool value);
524 
526  Status appendDate(const StringData& fieldName, Date_t value);
527 
529  Status appendNull(const StringData& fieldName);
530 
532  Status appendRegex(const StringData& fieldName,
533  const StringData& re, const StringData& flags);
534 
536  Status appendDBRef(const StringData& fieldName,
537  const StringData& ns, mongo::OID oid);
538 
540  Status appendCode(const StringData& fieldName, const StringData& value);
541 
543  Status appendSymbol(const StringData& fieldName, const StringData& value);
544 
546  Status appendCodeWithScope(const StringData& fieldName,
547  const StringData& code, const BSONObj& scope);
548 
550  Status appendInt(const StringData& fieldName, int32_t value);
551 
553  Status appendTimestamp(const StringData& fieldName, OpTime value);
554 
556  Status appendLong(const StringData& fieldName, int64_t value);
557 
559  Status appendMinKey(const StringData& fieldName);
560 
562  Status appendMaxKey(const StringData& fieldName);
563 
565  Status appendElement(const BSONElement& value);
566 
570  Status appendSafeNum(const StringData& fieldName, SafeNum value);
571 
574  std::string toString() const;
575 
576  private:
577  friend class Document;
578  friend class ConstElement;
579 
580  friend bool operator==(const Element&, const Element&);
581 
582  inline Element(Document* doc, RepIdx repIdx);
583 
584  Status addChild(Element e, bool front);
585 
586  StringData getValueStringOrSymbol() const;
587 
588  Status setValue(Element::RepIdx newValueIdx);
589 
590  Document* _doc;
591  RepIdx _repIdx;
592  };
593 
601  inline bool operator==(const Element& l, const Element& r);
602 
604  inline bool operator!=(const Element& l, const Element& r);
605 
606 } // namespace mutablebson
607 } // namespace mongo
608 
609 #include "mongo/bson/mutable/element-inl.h"
Status setValueDate(Date_t value)
Set the value of this Element to the given date.
Definition: document.cpp:1763
Status setValueString(const StringData &value)
Set the value of this Element to the given string.
Definition: document.cpp:1686
Status setValueMinKey()
Set the value of this Element to MinKey.
Definition: document.cpp:1871
Status setValueBSONElement(const BSONElement &value)
Set the value of this element to equal the value of the provided BSONElement 'value'.
Definition: document.cpp:1889
Utility for creating a BSONObj.
Definition: bsonobjbuilder.h:52
Status appendArray(const StringData &fieldName, const BSONObj &value)
Append the provided array object as a new field with the provided name.
Definition: element.cpp:63
Status appendBool(const StringData &fieldName, bool value)
Append the provided bool as a new field with the provided name.
Definition: element.cpp:81
bool hasValue() const
Returns true if 'getValue' can return a valid BSONElement from which a value may be extracted...
Definition: document.cpp:1456
Element rightChild() const
Returns either this Element's right child, or a non-ok Element if no right child exists.
Definition: document.cpp:1329
Status pushBack(Element e)
If this Element is empty, add 'e' as the first child.
Definition: element.cpp:33
Status appendCodeWithScope(const StringData &fieldName, const StringData &code, const BSONObj &scope)
Append the provided code and scope data as a new field with the provided name.
Definition: element.cpp:111
BSONArray getValueArray() const
Get the value from an object valued Element.
Definition: element-inl.h:44
size_t countChildren() const
Return the number of children of this Element.
Definition: document.cpp:1443
Status addSiblingLeft(Element e)
Add the provided Element to the left of this Element.
Definition: document.cpp:1100
Status appendCode(const StringData &fieldName, const StringData &value)
Append the provided code data as a new field with the iven name.
Definition: element.cpp:103
bool isValueUndefined() const
Returns true if this Element is the undefined type.
Definition: element-inl.h:49
Status setValueRegex(const StringData &re, const StringData &flags)
Set the value of this Element to the given regex parameters.
Definition: document.cpp:1781
bool getValueBool() const
Get the value from a bool valued Element.
Definition: element-inl.h:58
Status appendUndefined(const StringData &fieldName)
Append an undefined value as a new field with the provided name.
Definition: element.cpp:73
Status appendSafeNum(const StringData &fieldName, SafeNum value)
Append the provided number as field of the appropriate numeric type with the provided name...
Definition: element.cpp:140
Status popFront()
Remove the leftmost child Element if it exists, otherwise return an error.
Definition: element.cpp:37
Status appendBinary(const StringData &fieldName, uint32_t len, mongo::BinDataType binType, const void *data)
Append the provided binary data as a new field with the provided name.
Definition: element.cpp:67
Status setValueSymbol(const StringData &value)
Set the value of this Element to the given symbol.
Definition: document.cpp:1818
size_t countSiblingsRight() const
Returns the number of valid siblings to the right of this Element.
Definition: document.cpp:1429
Status popBack()
Remove the rightmost child Element if it exists, otherwise return an error.
Definition: element.cpp:44
BSON classes.
OpTime getValueTimestamp() const
Get the value from a timestamp valued Element.
Definition: element-inl.h:82
bool ok() const
Returns true if this Element represents a valid part of the Document.
Definition: element-inl.h:100
const BSONElement getValue() const
Get the value of this element if available.
Definition: document.cpp:1482
Status setValueArray(const BSONObj &value)
Set the value of this Element to the given object.
Definition: document.cpp:1710
Status setValueObject(const BSONObj &value)
Set the value of this Element to the given object.
Definition: document.cpp:1698
Definition: time_support.h:35
bool isValueNull() const
Returns true if this Element is the null type.
Definition: element-inl.h:68
Status setValueCodeWithScope(const StringData &code, const BSONObj &scope)
Set the value of this Element to the given code and scope data.
Definition: document.cpp:1830
Status setValueDBRef(const StringData &ns, OID oid)
Set the value of this Element to the given db ref parameters.
Definition: document.cpp:1794
Status pushFront(Element e)
If this Element is empty, add 'e' as the first child.
Definition: element.cpp:29
OID getValueOID() const
Get the value from an OID valued Element.
Definition: element-inl.h:53
friend bool operator==(const Element &, const Element &)
Element comparison support.
Definition: element-inl.h:134
Status appendElement(const BSONElement &value)
Append the given BSONElement.
Definition: element.cpp:136
Status addSiblingRight(Element e)
Add the provided Element to the right of this Element.
Definition: document.cpp:1152
std::string toString() const
Convert this element to its JSON representation if ok(), otherwise return !ok() message.
Definition: element.cpp:144
Status appendTimestamp(const StringData &fieldName, OpTime value)
Append the provided timestamp as a new field with the provided name.
Definition: element.cpp:120
Date_t getValueDate() const
Get the value from a date valued Element.
Definition: element-inl.h:63
bool hasChildren() const
Returns true if this element has children.
Definition: document.cpp:1341
Status rename(const StringData &newName)
Rename this Element to the provided name.
Definition: document.cpp:1263
BSONType
the complete list of valid BSON types see also bsonspec.org
Definition: bsontypes.h:43
bool isValueMaxKey() const
Returns true if this Element is the max key type.
Definition: element-inl.h:96
Status appendOID(const StringData &fieldName, mongo::OID value)
Append the provided OID as a new field with the provided name.
Definition: element.cpp:77
Status setValueDouble(double value)
Set the value of this Element to the given double.
Definition: document.cpp:1677
Status appendMinKey(const StringData &fieldName)
Append a max key as a new field with the provided name.
Definition: element.cpp:128
bool isType(BSONType type) const
Returns true if this Element is of the specified type.
Definition: element-inl.h:113
Status appendObject(const StringData &fieldName, const BSONObj &value)
Append the provided object as a new field with the provided name.
Definition: element.cpp:59
Element leftSibling(size_t distance=1) const
Returns either this Element's sibling 'distance' elements to the left, or a non-ok Element if no such...
Definition: document.cpp:1350
Status appendMaxKey(const StringData &fieldName)
Append a min key as a new field with the provided name.
Definition: element.cpp:132
Status setValueOID(OID value)
Set the value of this Element to the given OID.
Definition: document.cpp:1745
Status appendRegex(const StringData &fieldName, const StringData &re, const StringData &flags)
Append the provided regex data as a new field with the provided name.
Definition: element.cpp:93
SafeNum holds and does arithmetic on a number in a safe way, handling overflow and casting for the us...
Definition: safe_num.h:56
Status setValueNull()
Set the value of this Element to Null.
Definition: document.cpp:1772
Element findElementNamed(const StringData &name) const
Returns the first element found named 'name', starting the search at the current Element, and walking right.
Definition: document.cpp:1404
double getValueDouble() const
Get the value from a double valued Element.
Definition: element-inl.h:29
void writeTo(BSONObjBuilder *builder) const
Write this Element to the provided object builder.
Definition: document.cpp:1655
Document & getDocument()
Returns the Document to which this Element belongs.
Definition: element-inl.h:105
Status appendInt(const StringData &fieldName, int32_t value)
Append the provided integer as a new field with the provided name.
Definition: element.cpp:116
Status setValueLong(int64_t value)
Set the value of this Element to the given long integer.
Definition: document.cpp:1862
Definition: optime.h:41
Status setValueSafeNum(const SafeNum value)
Set the value of this Element to a numeric type appropriate to hold the given SafeNum value...
Definition: document.cpp:1905
StringData getValueSymbol() const
Get the value from a symbol valued Element.
Definition: element-inl.h:72
bool isNumeric() const
Returns true if this element is a numeric type (e.g.
Definition: document.cpp:1463
Element represents a BSON value or object in a mutable BSON Document.
Definition: element.h:99
Status appendNull(const StringData &fieldName)
Append a null as a new field with the provided name.
Definition: element.cpp:89
int32_t getValueInt() const
Get the value from an int valued Element.
Definition: element-inl.h:77
Status setValueMaxKey()
Set the value of this Element to MaxKey.
Definition: document.cpp:1880
int64_t getValueLong() const
Get the value from a long valued Element.
Definition: element-inl.h:87
Status setValueUndefined()
Set the value of this Element to Undefined.
Definition: document.cpp:1736
Status setValueTimestamp(OpTime value)
Set the value of this Element to the given timestamp.
Definition: document.cpp:1853
size_t countSiblingsLeft() const
Returns the number of valid siblings to the left of this Element.
Definition: document.cpp:1414
Element parent() const
Returns this Element's parent, or a non-ok Element if this Element has no parent (is a root)...
Definition: document.cpp:1374
Status setValueBool(bool value)
Set the value of this Element to the given boolean.
Definition: document.cpp:1754
BSONObj getValueObject() const
Get the value from an object valued Element.
Definition: element-inl.h:39
int compareWithBSONElement(const BSONElement &other, bool considerFieldName=true) const
Compare this Element with BSONElement 'other'.
Definition: document.cpp:1585
bool isIntegral() const
Returns true if this element is one of the integral numeric types (e.g.
Definition: document.cpp:1473
BSONElement represents an "element" in a BSONObj.
Definition: bsonelement.h:62
BSONType getType() const
Returns the BSONType of this Element.
Definition: document.cpp:1921
C++ representation of a "BSON" object – that is, an extended JSON-style object in a binary representa...
Definition: bsonobj.h:77
Status appendDBRef(const StringData &fieldName, const StringData &ns, mongo::OID oid)
Append the provided DBRef data as a new field with the provided name.
Definition: element.cpp:98
Status appendDouble(const StringData &fieldName, double value)
Append the provided double value as a new field with the provided name.
Definition: element.cpp:51
Status setValueBinary(uint32_t len, mongo::BinDataType binType, const void *data)
Set the value of this Element to the given binary data.
Definition: document.cpp:1722
bool isValueMinKey() const
Returns true if this Element is the min key type.
Definition: element-inl.h:92
Status setValueCode(const StringData &value)
Set the value of this Element to the given code data.
Definition: document.cpp:1806
StringData getValueString() const
Get the value from a string valued Element.
Definition: element-inl.h:34
Element findNthChild(size_t n) const
Returns the nth child, if any, of this Element.
Definition: document.cpp:1382
Element rightSibling(size_t distance=1) const
Returns either this Element's sibling 'distance' Elements to the right, or a non-ok Element if no suc...
Definition: document.cpp:1361
SafeNum getValueSafeNum() const
Returns the numeric value as a SafeNum.
Definition: document.cpp:1491
Definition: bsonobjbuilder.h:705
For an overview of mutable BSON, please see the file document.h in this directory.
Definition: const_element.h:36
Definition: bsonobj.h:585
Status appendString(const StringData &fieldName, const StringData &value)
Append the provided string value as a new field with the provided name.
Definition: element.cpp:55
int compareWithBSONObj(const BSONObj &other, bool considerFieldName=true) const
Compare this Element, which must be an Object or an Array, with 'other'.
Definition: document.cpp:1625
Object ID type.
Definition: oid.h:42
Status appendLong(const StringData &fieldName, int64_t value)
Append the provided long integer as a new field with the provided name.
Definition: element.cpp:124
Status appendSymbol(const StringData &fieldName, const StringData &value)
Append the provided symbol data as a new field with the provided name.
Definition: element.cpp:107
void writeArrayTo(BSONArrayBuilder *builder) const
Write this Element to the provided array builder.
Definition: document.cpp:1669
Element findFirstChildNamed(const StringData &name) const
Returns the first child, if any, of this Element named 'name'.
Definition: document.cpp:1392
StringData getFieldName() const
Returns the field name of this Element.
Definition: document.cpp:1928
Mutable BSON Overview.
Definition: document.h:221
Status appendDate(const StringData &fieldName, Date_t value)
Append the provided date as a new field with the provided name.
Definition: element.cpp:85
int compareWithElement(const ConstElement &other, bool considerFieldName=true) const
Compare this Element with Element 'other'.
Definition: document.cpp:1504
Element leftChild() const
Returns either this Element's left child, or a non-ok Element if no left child exists.
Definition: document.cpp:1317
Status setValueInt(int32_t value)
Set the value of this Element to the given integer.
Definition: document.cpp:1844
RepIdx getIdx() const
Returns the opaque ID for this element.
Definition: element-inl.h:117