2 * Copyright 2017 Facebook, Inc.
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
18 * This is a runtime dynamically typed value. It holds types from a
19 * specific predetermined set of types (ints, bools, arrays, etc). In
20 * particular, it can be used as a convenient in-memory representation
21 * for complete json objects.
23 * In general you can try to use these objects as if they were the
24 * type they represent (although in some cases with a slightly less
25 * complete interface than the raw type), and it'll just throw a
26 * TypeError if it is used in an illegal way.
30 * dynamic twelve = 12;
31 * dynamic str = "string";
32 * dynamic map = dynamic::object;
34 * map[str + "another_str"] = dynamic::array("array", "of", 4, "elements");
35 * map.insert("null_element", nullptr);
37 * assert(map[str] == 13);
39 * // Building a complex object with a sub array inline:
40 * dynamic d = dynamic::object
42 * ("key2", dynamic::array("a", "array"))
45 * Also see folly/json.h for the serialization and deserialization
48 * Additional documentation is in folly/docs/Dynamic.md.
50 * @author Jordan DeLong <delong.j@fb.com>
59 #include <type_traits>
60 #include <unordered_map>
64 #include <boost/operators.hpp>
66 #include <folly/Range.h>
67 #include <folly/Traits.h>
71 //////////////////////////////////////////////////////////////////////
76 //////////////////////////////////////////////////////////////////////
78 struct dynamic : private boost::operators<dynamic> {
88 template<class T, class Enable = void> struct NumericTypeHelper;
91 * We support direct iteration of arrays, and indirect iteration of objects.
92 * See begin(), end(), keys(), values(), and items() for more.
94 * Array iterators dereference as the elements in the array.
95 * Object key iterators dereference as the keys in the object.
96 * Object value iterators dereference as the values in the object.
97 * Object item iterators dereference as pairs of (key, value).
100 typedef std::vector<dynamic> Array;
102 typedef Array::iterator iterator;
103 typedef Array::const_iterator const_iterator;
104 typedef dynamic value_type;
106 struct const_key_iterator;
107 struct const_value_iterator;
108 struct const_item_iterator;
110 struct value_iterator;
111 struct item_iterator;
114 * Creation routines for making dynamic objects and arrays. Objects
115 * are maps from key to value (so named due to json-related origins
120 * // Make a fairly complex dynamic:
121 * dynamic d = dynamic::object("key", "value1")
122 * ("key2", dynamic::array("value",
127 * // Build an object in a few steps:
128 * dynamic d = dynamic::object;
130 * d["something_else"] = dynamic::array(1, 2, 3, nullptr);
133 struct EmptyArrayTag {};
137 static void array(EmptyArrayTag);
138 template <class... Args>
139 static dynamic array(Args&& ...args);
141 static ObjectMaker object();
142 static ObjectMaker object(dynamic, dynamic);
145 * Default constructor, initializes with nullptr.
150 * String compatibility constructors.
152 /* implicit */ dynamic(std::nullptr_t);
153 /* implicit */ dynamic(StringPiece val);
154 /* implicit */ dynamic(char const* val);
155 /* implicit */ dynamic(std::string val);
158 * This is part of the plumbing for array() and object(), above.
159 * Used to create a new array or object dynamic.
161 /* implicit */ dynamic(void (*)(EmptyArrayTag));
162 /* implicit */ dynamic(ObjectMaker (*)());
163 /* implicit */ dynamic(ObjectMaker const&) = delete;
164 /* implicit */ dynamic(ObjectMaker&&);
167 * Constructors for integral and float types.
168 * Other types are SFINAEd out with NumericTypeHelper.
170 template<class T, class NumericType = typename NumericTypeHelper<T>::type>
171 /* implicit */ dynamic(T t);
174 * Create a dynamic that is an array of the values from the supplied
177 template<class Iterator>
178 explicit dynamic(Iterator first, Iterator last);
180 dynamic(dynamic const&);
181 dynamic(dynamic&&) noexcept;
185 * "Deep" equality comparison. This will compare all the way down
186 * an object or array, and is potentially expensive.
188 bool operator==(dynamic const& o) const;
191 * For all types except object this returns the natural ordering on
192 * those types. For objects, we throw TypeError.
194 bool operator<(dynamic const& o) const;
199 * These throw TypeError when used with types or type combinations
200 * that don't support them.
202 * These functions may also throw if you use 64-bit integers with
203 * doubles when the integers are too big to fit in a double.
205 dynamic& operator+=(dynamic const&);
206 dynamic& operator-=(dynamic const&);
207 dynamic& operator*=(dynamic const&);
208 dynamic& operator/=(dynamic const&);
209 dynamic& operator%=(dynamic const&);
210 dynamic& operator|=(dynamic const&);
211 dynamic& operator&=(dynamic const&);
212 dynamic& operator^=(dynamic const&);
213 dynamic& operator++();
214 dynamic& operator--();
217 * Assignment from other dynamics. Because of the implicit conversion
218 * to dynamic from its potential types, you can use this to change the
219 * type pretty intuitively.
221 * Basic guarantee only.
223 dynamic& operator=(dynamic const&);
224 dynamic& operator=(dynamic&&) noexcept;
227 * For simple dynamics (not arrays or objects), this prints the
228 * value to an std::ostream in the expected way. Respects the
229 * formatting manipulators that have been sent to the stream
232 * If the dynamic holds an object or array, this prints them in a
233 * format very similar to JSON. (It will in fact actually be JSON
234 * as long as the dynamic validly represents a JSON object---i.e. it
235 * can't have non-string keys.)
237 friend std::ostream& operator<<(std::ostream&, dynamic const&);
240 * Returns true if this dynamic is of the specified type.
242 bool isString() const;
243 bool isObject() const;
246 bool isArray() const;
247 bool isDouble() const;
251 * Returns: isInt() || isDouble().
253 bool isNumber() const;
256 * Returns the type of this dynamic.
261 * Returns the type of this dynamic as a printable string.
263 const char* typeName() const;
266 * Extract a value while trying to convert to the specified type.
267 * Throws exceptions if we cannot convert from the real type to the
270 * Note you can only use this to access integral types or strings,
271 * since arrays and objects are generally best dealt with as a
274 std::string asString() const;
275 double asDouble() const;
276 int64_t asInt() const;
280 * Extract the value stored in this dynamic without type conversion.
282 * These will throw a TypeError if the dynamic has a different type.
284 const std::string& getString() const&;
285 double getDouble() const&;
286 int64_t getInt() const&;
287 bool getBool() const&;
288 std::string& getString() &;
289 double& getDouble() &;
292 std::string&& getString() &&;
293 double getDouble() &&;
298 * It is occasionally useful to access a string's internal pointer
299 * directly, without the type conversion of `asString()`.
301 * These will throw a TypeError if the dynamic is not a string.
303 const char* data() const&;
304 const char* data() && = delete;
305 const char* c_str() const&;
306 const char* c_str() && = delete;
307 StringPiece stringPiece() const;
310 * Returns: true if this dynamic is null, an empty array, an empty
311 * object, or an empty string.
316 * If this is an array or an object, returns the number of elements
317 * contained. If it is a string, returns the length. Otherwise
320 std::size_t size() const;
323 * You can iterate over the values of the array. Calling these on
324 * non-arrays will throw a TypeError.
326 const_iterator begin() const;
327 const_iterator end() const;
333 * Helper object returned by keys(), values(), and items().
335 template <class T> struct IterableProxy;
339 * You can iterate over the keys, values, or items (std::pair of key and
340 * value) in an object. Calling these on non-objects will throw a TypeError.
342 IterableProxy<const_key_iterator> keys() const;
343 IterableProxy<const_value_iterator> values() const;
344 IterableProxy<const_item_iterator> items() const;
345 IterableProxy<value_iterator> values();
346 IterableProxy<item_iterator> items();
349 * AssociativeContainer-style find interface for objects. Throws if
350 * this is not an object.
352 * Returns: items().end() if the key is not present, or a
353 * const_item_iterator pointing to the item.
355 const_item_iterator find(dynamic const&) const;
356 item_iterator find(dynamic const&);
359 * If this is an object, returns whether it contains a field with
360 * the given name. Otherwise throws TypeError.
362 std::size_t count(dynamic const&) const;
365 * For objects or arrays, provides access to sub-fields by index or
368 * Using these with dynamic objects that are not arrays or objects
369 * will throw a TypeError. Using an index that is out of range or
370 * object-element that's not present throws std::out_of_range.
372 dynamic const& at(dynamic const&) const&;
373 dynamic& at(dynamic const&) &;
374 dynamic&& at(dynamic const&) &&;
377 * Like 'at', above, except it returns either a pointer to the contained
378 * object or nullptr if it wasn't found. This allows a key to be tested for
379 * containment and retrieved in one operation. Example:
381 * if (auto* found = d.get_ptr(key))
384 * Using these with dynamic objects that are not arrays or objects
385 * will throw a TypeError.
387 const dynamic* get_ptr(dynamic const&) const&;
388 dynamic* get_ptr(dynamic const&) &;
389 dynamic* get_ptr(dynamic const&) && = delete;
392 * This works for access to both objects and arrays.
394 * In the case of an array, the index must be an integer, and this will throw
395 * std::out_of_range if it is less than zero or greater than size().
397 * In the case of an object, the non-const overload inserts a null
398 * value if the key isn't present. The const overload will throw
399 * std::out_of_range if the key is not present.
401 * These functions do not invalidate iterators.
403 dynamic& operator[](dynamic const&) &;
404 dynamic const& operator[](dynamic const&) const&;
405 dynamic&& operator[](dynamic const&) &&;
408 * Only defined for objects, throws TypeError otherwise.
410 * getDefault will return the value associated with the supplied key, the
411 * supplied default otherwise. setDefault will set the key to the supplied
412 * default if it is not yet set, otherwise leaving it. setDefault returns
413 * a reference to the existing value if present, the new value otherwise.
416 getDefault(const dynamic& k, const dynamic& v = dynamic::object) const&;
417 dynamic getDefault(const dynamic& k, dynamic&& v) const&;
418 dynamic getDefault(const dynamic& k, const dynamic& v = dynamic::object) &&;
419 dynamic getDefault(const dynamic& k, dynamic&& v) &&;
420 template<class K, class V>
421 dynamic& setDefault(K&& k, V&& v);
422 // MSVC 2015 Update 3 needs these extra overloads because if V were a
423 // defaulted template parameter, it causes MSVC to consider v an rvalue
424 // reference rather than a universal reference, resulting in it not being
425 // able to find the correct overload to construct a dynamic with.
427 dynamic& setDefault(K&& k, dynamic&& v);
429 dynamic& setDefault(K&& k, const dynamic& v = dynamic::object);
432 * Resizes an array so it has at n elements, using the supplied
433 * default to fill new elements. Throws TypeError if this dynamic
436 * May invalidate iterators.
440 void resize(std::size_t n, dynamic const& = nullptr);
443 * Inserts the supplied key-value pair to an object, or throws if
444 * it's not an object.
446 * Invalidates iterators.
448 template<class K, class V> void insert(K&&, V&& val);
451 * These functions merge two folly dynamic objects.
452 * The "update" and "update_missing" functions extend the object by
453 * inserting the key/value pairs of mergeObj into the current object.
454 * For update, if key is duplicated between the two objects, it
455 * will overwrite with the value of the object being inserted (mergeObj).
456 * For "update_missing", it will prefer the value in the original object
458 * The "merge" function creates a new object consisting of the key/value
459 * pairs of both mergeObj1 and mergeObj2
460 * If the key is duplicated between the two objects,
461 * it will prefer value in the second object (mergeObj2)
463 void update(const dynamic& mergeObj);
464 void update_missing(const dynamic& other);
465 static dynamic merge(const dynamic& mergeObj1, const dynamic& mergeObj2);
468 * Erase an element from a dynamic object, by key.
470 * Invalidates iterators to the element being erased.
472 * Returns the number of elements erased (i.e. 1 or 0).
474 std::size_t erase(dynamic const& key);
477 * Erase an element from a dynamic object or array, using an
478 * iterator or an iterator range.
480 * In arrays, invalidates iterators to elements after the element
481 * being erased. In objects, invalidates iterators to the elements
484 * Returns a new iterator to the first element beyond any elements
485 * removed, or end() if there are none. (The iteration order does
488 iterator erase(const_iterator it);
489 iterator erase(const_iterator first, const_iterator last);
491 const_key_iterator erase(const_key_iterator it);
492 const_key_iterator erase(const_key_iterator first, const_key_iterator last);
494 value_iterator erase(const_value_iterator it);
495 value_iterator erase(const_value_iterator first, const_value_iterator last);
497 item_iterator erase(const_item_iterator it);
498 item_iterator erase(const_item_iterator first, const_item_iterator last);
500 * Append elements to an array. If this is not an array, throws
503 * Invalidates iterators.
505 void push_back(dynamic const&);
506 void push_back(dynamic&&);
509 * Remove an element from the back of an array. If this is not an array,
512 * Does not invalidate iterators.
517 * Get a hash code. This function is called by a std::hash<>
518 * specialization, also.
520 * Throws TypeError if this is an object, array, or null.
522 std::size_t hash() const;
525 friend struct TypeError;
527 template<class T> struct TypeInfo;
528 template<class T> struct CompareOp;
529 template<class T> struct GetAddrImpl;
530 template<class T> struct PrintImpl;
532 explicit dynamic(Array&& array);
534 template<class T> T const& get() const;
535 template<class T> T& get();
536 template<class T> T* get_nothrow() & noexcept;
537 template<class T> T const* get_nothrow() const& noexcept;
538 template<class T> T* get_nothrow() && noexcept = delete;
539 template<class T> T* getAddress() noexcept;
540 template<class T> T const* getAddress() const noexcept;
542 template<class T> T asImpl() const;
544 static char const* typeName(Type);
545 void destroy() noexcept;
546 void print(std::ostream&) const;
547 void print_as_pseudo_json(std::ostream&) const; // see json.cpp
552 explicit Data() : nul(nullptr) {}
563 * Objects are placement new'd here. We have to use a char buffer
564 * because we don't know the type here (std::unordered_map<> with
565 * dynamic would be parameterizing a std:: template with an
566 * incomplete type right now). (Note that in contrast we know it
567 * is ok to do this with fbvector because we own it.)
569 std::aligned_storage<
570 sizeof(std::unordered_map<int,int>),
571 alignof(std::unordered_map<int,int>)
572 >::type objectBuffer;
576 //////////////////////////////////////////////////////////////////////
580 #include <folly/dynamic-inl.h>