xref: /third_party/gn/src/base/values.h

5 // This file specifies a recursive data storage class called Value intended for
8 // A Value represents something that can be stored in JSON or passed to/from
16 // NOTE: A Value parameter that is always a Value::STRING should just be passed
17 // as a std::string. Similarly for Values that are always Value::DICTIONARY
18 // (should be flat_map), Value::LIST (should be std::vector), et cetera.
42 class Value;
44 // The Value class is the base class for Values. A Value can be instantiated
49 // base::Value is currently in the process of being refactored. Design doc:
52 // Previously (which is how most code that currently exists is written), Value
53 // used derived types to implement the individual data types, and base::Value
59 //   std::unique_ptr<base::Value> GetFoo() {
65 // The new design makes base::Value a variant type that holds everything in
72 //   base::Value GetFoo() {
73 //     base::Value dict(base::Value::Type::DICTIONARY);
74 //     dict.SetKey("mykey", base::Value(foo));
77 class Value {
80   using DictStorage = flat_map<std::string, std::unique_ptr<Value>>;
81   using ListStorage = std::vector<Value>;
97   // DEPRECATED, use std::make_unique<Value>(const BlobStorage&) instead.
99   static std::unique_ptr<Value> CreateWithCopiedBuffer(const char* buffer,
103   static Value FromUniquePtrValue(std::unique_ptr<Value> val);
104   static std::unique_ptr<Value> ToUniquePtrValue(Value val);
106   Value(Value&& that) noexcept;
107   Value() noexcept;  // A null value.
109   // Value's copy constructor and copy assignment operator are deleted. Use this
111   Value Clone() const;
113   explicit Value(Type type);
114   explicit Value(bool in_bool);
115   explicit Value(int in_int);
117   // Value(const char*) and Value(const char16_t*) are required despite
118   // Value(std::string_view) and Value(std::u16string_view) because otherwise
119   // the compiler will choose the Value(bool) constructor for these arguments.
120   // Value(std::string&&) allow for efficient move construction.
121   explicit Value(const char* in_string);
122   explicit Value(std::string_view in_string);
123   explicit Value(std::string&& in_string) noexcept;
124   explicit Value(const char16_t* in_string16);
125   explicit Value(std::u16string_view in_string16);
127   explicit Value(const BlobStorage& in_blob);
128   explicit Value(BlobStorage&& in_blob) noexcept;
130   explicit Value(const DictStorage& in_dict);
131   explicit Value(DictStorage&& in_dict) noexcept;
133   explicit Value(const ListStorage& in_list);
134   explicit Value(ListStorage&& in_list) noexcept;
136   Value& operator=(Value&& that) noexcept;
138   ~Value();
143   // Returns the type of the value stored by the current Value object.
172   Value* FindKey(std::string_view key);
173   const Value* FindKey(std::string_view key) const;
184   Value* FindKeyOfType(std::string_view key, Type type);
185   const Value* FindKeyOfType(std::string_view key, Type type) const;
194   Value* SetKey(std::string_view key, Value value);
196   Value* SetKey(std::string&& key, Value value);
198   Value* SetKey(const char* key, Value value);
215   // The type of the leaf Value is not checked.
218   // will actually be into another Value, so it can't be compared to iterators
228   Value* FindPath(std::initializer_list<std::string_view> path);
229   Value* FindPath(span<const std::string_view> path);
230   const Value* FindPath(std::initializer_list<std::string_view> path) const;
231   const Value* FindPath(span<const std::string_view> path) const;
233   // Like FindPath() but will only return the value if the leaf Value type
238   Value* FindPathOfType(std::initializer_list<std::string_view> path,
240   Value* FindPathOfType(span<const std::string_view> path, Type type);
241   const Value* FindPathOfType(std::initializer_list<std::string_view> path,
243   const Value* FindPathOfType(span<const std::string_view> path,
262   Value* SetPath(std::initializer_list<std::string_view> path, Value value);
263   Value* SetPath(span<const std::string_view> path, Value value);
265   // Tries to remove a Value at the given path.
298   // These methods allow the convenient retrieval of the contents of the Value.
309   bool GetAsString(const Value** out_value) const;
320   // This creates a deep copy of the entire Value tree, and returns a pointer
324   // DEPRECATED, use Value::Clone() instead.
326   Value* DeepCopy() const;
327   // DEPRECATED, use Value::Clone() instead.
329   std::unique_ptr<Value> CreateDeepCopy() const;
333   friend bool operator==(const Value& lhs, const Value& rhs);
334   friend bool operator!=(const Value& lhs, const Value& rhs);
335   friend bool operator<(const Value& lhs, const Value& rhs);
336   friend bool operator>(const Value& lhs, const Value& rhs);
337   friend bool operator<=(const Value& lhs, const Value& rhs);
338   friend bool operator>=(const Value& lhs, const Value& rhs);
340   // Compares if two Value objects have equal contents.
341   // DEPRECATED, use operator==(const Value& lhs, const Value& rhs) instead.
343   bool Equals(const Value* other) const;
364   void InternalMoveConstructFrom(Value&& that);
367   Value(const Value&) = delete;
368   Value& operator=(const Value&) = delete;
374 class DictionaryValue : public Value {
380   static std::unique_ptr<DictionaryValue> From(std::unique_ptr<Value> value);
387   // DEPRECATED, use Value::FindKey(key) instead.
399   // Sets the Value associated with the given path starting from this object.
407   // DEPRECATED, use Value::SetPath(path, value) instead.
408   Value* Set(std::string_view path, std::unique_ptr<Value> in_value);
412   // DEPRECATED, use Value::SetPath(path, Value(bool)) instead.
413   Value* SetBoolean(std::string_view path, bool in_value);
414   // DEPRECATED, use Value::SetPath(path, Value(int)) instead.
415   Value* SetInteger(std::string_view path, int in_value);
416   // DEPRECATED, use Value::SetPath(path, Value(std::string_view)) instead.
417   Value* SetString(std::string_view path, std::string_view in_value);
418   // DEPRECATED, use Value::SetPath(path, Value(const string& 16)) instead.
419   Value* SetString(std::string_view path, const std::u16string& in_value);
420   // DEPRECATED, use Value::SetPath(path, Value(Type::DICTIONARY)) instead.
423   // DEPRECATED, use Value::SetPath(path, Value(Type::LIST)) instead.
429   // DEPRECATED, use Value::SetKey(key, value) instead.
430   Value* SetWithoutPathExpansion(std::string_view key,
431                                  std::unique_ptr<Value> in_value);
433   // Gets the Value associated with the given path starting from this object.
441   // DEPRECATED, use Value::FindPath(path) instead.
442   bool Get(std::string_view path, const Value** out_value) const;
443   // DEPRECATED, use Value::FindPath(path) instead.
444   bool Get(std::string_view path, Value** out_value);
450   // DEPRECATED, use Value::FindPath(path) and Value::GetBool() instead.
452   // DEPRECATED, use Value::FindPath(path) and Value::GetInt() instead.
454   // DEPRECATED, use Value::FindPath(path) and Value::GetString() instead.
456   // DEPRECATED, use Value::FindPath(path) and Value::GetString() instead.
458   // DEPRECATED, use Value::FindPath(path) and Value::GetString() instead.
460   // DEPRECATED, use Value::FindPath(path) and Value::GetBlob() instead.
461   bool GetBinary(std::string_view path, const Value** out_value) const;
462   // DEPRECATED, use Value::FindPath(path) and Value::GetBlob() instead.
463   bool GetBinary(std::string_view path, Value** out_value);
464   // DEPRECATED, use Value::FindPath(path) and Value's Dictionary API instead.
467   // DEPRECATED, use Value::FindPath(path) and Value's Dictionary API instead.
469   // DEPRECATED, use Value::FindPath(path) and Value::GetList() instead.
471   // DEPRECATED, use Value::FindPath(path) and Value::GetList() instead.
476   // DEPRECATED, use Value::FindKey(key) instead.
478                                const Value** out_value) const;
479   // DEPRECATED, use Value::FindKey(key) instead.
480   bool GetWithoutPathExpansion(std::string_view key, Value** out_value);
481   // DEPRECATED, use Value::FindKey(key) and Value::GetBool() instead.
484   // DEPRECATED, use Value::FindKey(key) and Value::GetInt() instead.
487   // DEPRECATED, use Value::FindKey(key) and Value::GetString() instead.
490   // DEPRECATED, use Value::FindKey(key) and Value::GetString() instead.
493   // DEPRECATED, use Value::FindKey(key) and Value's Dictionary API instead.
497   // DEPRECATED, use Value::FindKey(key) and Value's Dictionary API instead.
500   // DEPRECATED, use Value::FindKey(key) and Value::GetList() instead.
503   // DEPRECATED, use Value::FindKey(key) and Value::GetList() instead.
506   // Removes the Value with the specified path from this dictionary (or one
508   // If |out_value| is non-NULL, the removed Value will be passed out via
512   // DEPRECATED, use Value::RemovePath(path) instead.
513   bool Remove(std::string_view path, std::unique_ptr<Value>* out_value);
517   // DEPRECATED, use Value::RemoveKey(key) instead.
519                                   std::unique_ptr<Value>* out_value);
523   // DEPRECATED, use Value::RemovePath(path) instead.
524   bool RemovePath(std::string_view path, std::unique_ptr<Value>* out_value);
526   using Value::RemovePath;  // DictionaryValue::RemovePath shadows otherwise.
544   // DEPRECATED, use Value::DictItems() instead.
555     const Value& value() const { return *it_->second; }
563   // DEPRECATED, use Value::DictItems() instead.
567   // DEPRECATED, use Value::DictItems() instead.
571   // DEPRECATED, use Value::Clone() instead.
574   // DEPRECATED, use Value::Clone() instead.
579 // This type of Value represents a list of other Value values.
580 class ListValue : public Value {
586   static std::unique_ptr<ListValue> From(std::unique_ptr<Value> value);
608   // Sets the list item at the given index to be the Value specified by
614   bool Set(size_t index, std::unique_ptr<Value> in_value);
616   // Gets the Value at the given index.  Modifies |out_value| (and returns true)
618   // Note that the list always owns the Value passed out via |out_value|.
621   bool Get(size_t index, const Value** out_value) const;
622   bool Get(size_t index, Value** out_value);
625   // only if the index is valid and the Value at that index can be returned
639   using Value::GetList;
644   // Removes the Value with the specified index from this list.
645   // If |out_value| is non-NULL, the removed Value AND ITS OWNERSHIP will be
650   bool Remove(size_t index, std::unique_ptr<Value>* out_value);
656   bool Remove(const Value& value, size_t* index);
663   iterator Erase(iterator iter, std::unique_ptr<Value>* out_value);
665   // Appends a Value to the end of the list.
667   void Append(std::unique_ptr<Value> in_value);
679   // Appends a Value if it's not already present. Returns true if successful,
682   bool AppendIfNotPresent(std::unique_ptr<Value> in_value);
684   // Insert a Value at index.
687   bool Insert(size_t index, std::unique_ptr<Value> in_value);
690   // method of the Value type.
693   const_iterator Find(const Value& value) const;
710   // DEPRECATED, use Value::Clone() instead.
713   // DEPRECATED, use Value::Clone() instead.
719 // Value objects.
724   virtual bool Serialize(const Value& root) = 0;
727 // This interface is implemented by classes that know how to deserialize Value
733   // This method deserializes the subclass-specific format into a Value object.
735   // Value. If the return value is NULL, and if error_code is non-NULL,
739   virtual std::unique_ptr<Value> Deserialize(int* error_code,
747 std::ostream& operator<<(std::ostream& out, const Value& value);
751   return out << static_cast<const Value&>(value);
755   return out << static_cast<const Value&>(value);
759 std::ostream& operator<<(std::ostream& out, const Value::Type& type);

Indexes created Thu Nov 07 10:32:03 CST 2024