1 // Copyright (c) 2011 The Chromium Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
5 // This file specifies a recursive data storage class called Value intended for
6 // storing setting and other persistable data. It includes the ability to
7 // specify (recursive) lists and dictionaries, so it's fairly expressive.
8 // However, the API is optimized for the common case, namely storing a
9 // hierarchical tree of simple values. Given a DictionaryValue root, you can
10 // easily do things like:
12 // root->SetString("global.pages.homepage", "http://goateleporter.com");
13 // std::string homepage = "http://google.com"; // default/fallback value
14 // root->GetString("global.pages.homepage", &homepage);
16 // where "global" and "pages" are also DictionaryValues, and "homepage" is a
17 // string setting. If some elements of the path didn't exist yet, the
18 // SetString() method would create the missing elements and attach them to root
19 // before attaching the homepage value.
21 #ifndef BASE_VALUES_H_
22 #define BASE_VALUES_H_
30 #include "base/base_export.h"
31 #include "base/basictypes.h"
32 #include "base/compiler_specific.h"
33 #include "base/string16.h"
35 // This file declares "using base::Value", etc. at the bottom, so that
36 // current code can use these classes without the base namespace. In
37 // new code, please always use base::Value, etc. or add your own
38 // "using" declaration.
39 // http://crbug.com/88666
43 class DictionaryValue
;
44 class FundamentalValue
;
49 typedef std::vector
<Value
*> ValueVector
;
50 typedef std::map
<std::string
, Value
*> ValueMap
;
52 // The Value class is the base class for Values. A Value can be instantiated
53 // via the Create*Value() factory methods, or by directly creating instances of
55 class BASE_EXPORT Value
{
70 // Convenience methods for creating Value objects for various
71 // kinds of values without thinking about which class implements them.
72 // These can always be expected to return a valid Value*.
73 static Value
* CreateNullValue();
74 static FundamentalValue
* CreateBooleanValue(bool in_value
);
75 static FundamentalValue
* CreateIntegerValue(int in_value
);
76 static FundamentalValue
* CreateDoubleValue(double in_value
);
77 static StringValue
* CreateStringValue(const std::string
& in_value
);
78 static StringValue
* CreateStringValue(const string16
& in_value
);
80 // Returns the type of the value stored by the current Value object.
81 // Each type will be implemented by only one subclass of Value, so it's
82 // safe to use the Type to determine whether you can cast from
83 // Value* to (Implementing Class)*. Also, a Value object never changes
84 // its type after construction.
85 Type
GetType() const { return type_
; }
87 // Returns true if the current object represents a given type.
88 bool IsType(Type type
) const { return type
== type_
; }
90 // These methods allow the convenient retrieval of settings.
91 // If the current setting object can be converted into the given type,
92 // the value is returned through the |out_value| parameter and true is
93 // returned; otherwise, false is returned and |out_value| is unchanged.
94 virtual bool GetAsBoolean(bool* out_value
) const;
95 virtual bool GetAsInteger(int* out_value
) const;
96 virtual bool GetAsDouble(double* out_value
) const;
97 virtual bool GetAsString(std::string
* out_value
) const;
98 virtual bool GetAsString(string16
* out_value
) const;
99 virtual bool GetAsList(ListValue
** out_value
);
100 virtual bool GetAsList(const ListValue
** out_value
) const;
102 // This creates a deep copy of the entire Value tree, and returns a pointer
103 // to the copy. The caller gets ownership of the copy, of course.
105 // Subclasses return their own type directly in their overrides;
106 // this works because C++ supports covariant return types.
107 virtual Value
* DeepCopy() const;
109 // Compares if two Value objects have equal contents.
110 virtual bool Equals(const Value
* other
) const;
112 // Compares if two Value objects have equal contents. Can handle NULLs.
113 // NULLs are considered equal but different from Value::CreateNullValue().
114 static bool Equals(const Value
* a
, const Value
* b
);
116 #if !defined(OS_CHROMEOS)
117 // NOTE: We pass Value from libcros tp Chrome, so changing the size of Value
118 // breaks it. TODO(stevenjb): Eliminate that dependency (crosbug.com/19576).
119 // TODO(sky) bug 91396: remove this when we figure out 91396.
120 // If true crash when deleted.
121 void set_check_on_delete(bool value
) { check_on_delete_
= value
; }
123 void set_check_on_delete(bool value
) {}
127 // This isn't safe for end-users (they should use the Create*Value()
128 // static methods above), but it's useful for subclasses.
129 explicit Value(Type type
);
134 #if !defined(OS_CHROMEOS)
135 // See description above setter.
136 bool check_on_delete_
;
139 DISALLOW_COPY_AND_ASSIGN(Value
);
142 // FundamentalValue represents the simple fundamental types of values.
143 class BASE_EXPORT FundamentalValue
: public Value
{
145 explicit FundamentalValue(bool in_value
);
146 explicit FundamentalValue(int in_value
);
147 explicit FundamentalValue(double in_value
);
148 virtual ~FundamentalValue();
150 // Overridden from Value:
151 virtual bool GetAsBoolean(bool* out_value
) const OVERRIDE
;
152 virtual bool GetAsInteger(int* out_value
) const OVERRIDE
;
153 virtual bool GetAsDouble(double* out_value
) const OVERRIDE
;
154 virtual FundamentalValue
* DeepCopy() const OVERRIDE
;
155 virtual bool Equals(const Value
* other
) const OVERRIDE
;
161 double double_value_
;
164 DISALLOW_COPY_AND_ASSIGN(FundamentalValue
);
167 class BASE_EXPORT StringValue
: public Value
{
169 // Initializes a StringValue with a UTF-8 narrow character string.
170 explicit StringValue(const std::string
& in_value
);
172 // Initializes a StringValue with a string16.
173 explicit StringValue(const string16
& in_value
);
175 virtual ~StringValue();
177 // Overridden from Value:
178 virtual bool GetAsString(std::string
* out_value
) const OVERRIDE
;
179 virtual bool GetAsString(string16
* out_value
) const OVERRIDE
;
180 virtual StringValue
* DeepCopy() const OVERRIDE
;
181 virtual bool Equals(const Value
* other
) const OVERRIDE
;
186 DISALLOW_COPY_AND_ASSIGN(StringValue
);
189 class BASE_EXPORT BinaryValue
: public Value
{
191 virtual ~BinaryValue();
193 // Creates a Value to represent a binary buffer. The new object takes
194 // ownership of the pointer passed in, if successful.
195 // Returns NULL if buffer is NULL.
196 static BinaryValue
* Create(char* buffer
, size_t size
);
198 // For situations where you want to keep ownership of your buffer, this
199 // factory method creates a new BinaryValue by copying the contents of the
200 // buffer that's passed in.
201 // Returns NULL if buffer is NULL.
202 static BinaryValue
* CreateWithCopiedBuffer(const char* buffer
, size_t size
);
204 size_t GetSize() const { return size_
; }
205 char* GetBuffer() { return buffer_
; }
206 const char* GetBuffer() const { return buffer_
; }
208 // Overridden from Value:
209 virtual BinaryValue
* DeepCopy() const OVERRIDE
;
210 virtual bool Equals(const Value
* other
) const OVERRIDE
;
213 // Constructor is private so that only objects with valid buffer pointers
214 // and size values can be created.
215 BinaryValue(char* buffer
, size_t size
);
220 DISALLOW_COPY_AND_ASSIGN(BinaryValue
);
223 // DictionaryValue provides a key-value dictionary with (optional) "path"
224 // parsing for recursive access; see the comment at the top of the file. Keys
225 // are |std::string|s and should be UTF-8 encoded.
226 class BASE_EXPORT DictionaryValue
: public Value
{
229 virtual ~DictionaryValue();
231 // Returns true if the current dictionary has a value for the given key.
232 bool HasKey(const std::string
& key
) const;
234 // Returns the number of Values in this dictionary.
235 size_t size() const { return dictionary_
.size(); }
237 // Returns whether the dictionary is empty.
238 bool empty() const { return dictionary_
.empty(); }
240 // Clears any current contents of this dictionary.
243 // Sets the Value associated with the given path starting from this object.
244 // A path has the form "<key>" or "<key>.<key>.[...]", where "." indexes
245 // into the next DictionaryValue down. Obviously, "." can't be used
246 // within a key, but there are no other restrictions on keys.
247 // If the key at any step of the way doesn't exist, or exists but isn't
248 // a DictionaryValue, a new DictionaryValue will be created and attached
249 // to the path in that location.
250 // Note that the dictionary takes ownership of the value referenced by
251 // |in_value|, and therefore |in_value| must be non-NULL.
252 void Set(const std::string
& path
, Value
* in_value
);
254 // Convenience forms of Set(). These methods will replace any existing
255 // value at that path, even if it has a different type.
256 void SetBoolean(const std::string
& path
, bool in_value
);
257 void SetInteger(const std::string
& path
, int in_value
);
258 void SetDouble(const std::string
& path
, double in_value
);
259 void SetString(const std::string
& path
, const std::string
& in_value
);
260 void SetString(const std::string
& path
, const string16
& in_value
);
262 // Like Set(), but without special treatment of '.'. This allows e.g. URLs to
264 void SetWithoutPathExpansion(const std::string
& key
, Value
* in_value
);
266 // Gets the Value associated with the given path starting from this object.
267 // A path has the form "<key>" or "<key>.<key>.[...]", where "." indexes
268 // into the next DictionaryValue down. If the path can be resolved
269 // successfully, the value for the last key in the path will be returned
270 // through the |out_value| parameter, and the function will return true.
271 // Otherwise, it will return false and |out_value| will be untouched.
272 // Note that the dictionary always owns the value that's returned.
273 bool Get(const std::string
& path
, Value
** out_value
) const;
275 // These are convenience forms of Get(). The value will be retrieved
276 // and the return value will be true if the path is valid and the value at
277 // the end of the path can be returned in the form specified.
278 bool GetBoolean(const std::string
& path
, bool* out_value
) const;
279 bool GetInteger(const std::string
& path
, int* out_value
) const;
280 bool GetDouble(const std::string
& path
, double* out_value
) const;
281 bool GetString(const std::string
& path
, std::string
* out_value
) const;
282 bool GetString(const std::string
& path
, string16
* out_value
) const;
283 bool GetStringASCII(const std::string
& path
, std::string
* out_value
) const;
284 bool GetBinary(const std::string
& path
, BinaryValue
** out_value
) const;
285 bool GetDictionary(const std::string
& path
,
286 DictionaryValue
** out_value
) const;
287 bool GetList(const std::string
& path
, ListValue
** out_value
) const;
289 // Like Get(), but without special treatment of '.'. This allows e.g. URLs to
291 bool GetWithoutPathExpansion(const std::string
& key
,
292 Value
** out_value
) const;
293 bool GetIntegerWithoutPathExpansion(const std::string
& key
,
294 int* out_value
) const;
295 bool GetDoubleWithoutPathExpansion(const std::string
& key
,
296 double* out_value
) const;
297 bool GetStringWithoutPathExpansion(const std::string
& key
,
298 std::string
* out_value
) const;
299 bool GetStringWithoutPathExpansion(const std::string
& key
,
300 string16
* out_value
) const;
301 bool GetDictionaryWithoutPathExpansion(const std::string
& key
,
302 DictionaryValue
** out_value
) const;
303 bool GetListWithoutPathExpansion(const std::string
& key
,
304 ListValue
** out_value
) const;
306 // Removes the Value with the specified path from this dictionary (or one
307 // of its child dictionaries, if the path is more than just a local key).
308 // If |out_value| is non-NULL, the removed Value AND ITS OWNERSHIP will be
309 // passed out via out_value. If |out_value| is NULL, the removed value will
310 // be deleted. This method returns true if |path| is a valid path; otherwise
311 // it will return false and the DictionaryValue object will be unchanged.
312 bool Remove(const std::string
& path
, Value
** out_value
);
314 // Like Remove(), but without special treatment of '.'. This allows e.g. URLs
315 // to be used as paths.
316 bool RemoveWithoutPathExpansion(const std::string
& key
, Value
** out_value
);
318 // Makes a copy of |this| but doesn't include empty dictionaries and lists in
319 // the copy. This never returns NULL, even if |this| itself is empty.
320 DictionaryValue
* DeepCopyWithoutEmptyChildren();
322 // Merge a given dictionary into this dictionary. This is done recursively,
323 // i.e. any subdictionaries will be merged as well. In case of key collisions,
324 // the passed in dictionary takes precedence and data already present will be
326 void MergeDictionary(const DictionaryValue
* dictionary
);
328 // Swaps contents with the |other| dictionary.
329 void Swap(DictionaryValue
* other
) {
330 dictionary_
.swap(other
->dictionary_
);
333 // This class provides an iterator for the keys in the dictionary.
334 // It can't be used to modify the dictionary.
336 // YOU SHOULD ALWAYS USE THE XXXWithoutPathExpansion() APIs WITH THESE, NOT
337 // THE NORMAL XXX() APIs. This makes sure things will work correctly if any
338 // keys have '.'s in them.
340 : private std::iterator
<std::input_iterator_tag
, const std::string
> {
342 explicit key_iterator(ValueMap::const_iterator itr
) { itr_
= itr
; }
343 key_iterator
operator++() {
347 const std::string
& operator*() { return itr_
->first
; }
348 bool operator!=(const key_iterator
& other
) { return itr_
!= other
.itr_
; }
349 bool operator==(const key_iterator
& other
) { return itr_
== other
.itr_
; }
352 ValueMap::const_iterator itr_
;
355 key_iterator
begin_keys() const { return key_iterator(dictionary_
.begin()); }
356 key_iterator
end_keys() const { return key_iterator(dictionary_
.end()); }
358 // Overridden from Value:
359 virtual DictionaryValue
* DeepCopy() const OVERRIDE
;
360 virtual bool Equals(const Value
* other
) const OVERRIDE
;
363 ValueMap dictionary_
;
365 DISALLOW_COPY_AND_ASSIGN(DictionaryValue
);
368 // This type of Value represents a list of other Value values.
369 class BASE_EXPORT ListValue
: public Value
{
371 typedef ValueVector::iterator iterator
;
372 typedef ValueVector::const_iterator const_iterator
;
375 virtual ~ListValue();
377 // Clears the contents of this ListValue
380 // Returns the number of Values in this list.
381 size_t GetSize() const { return list_
.size(); }
383 // Returns whether the list is empty.
384 bool empty() const { return list_
.empty(); }
386 // Sets the list item at the given index to be the Value specified by
387 // the value given. If the index beyond the current end of the list, null
388 // Values will be used to pad out the list.
389 // Returns true if successful, or false if the index was negative or
390 // the value is a null pointer.
391 bool Set(size_t index
, Value
* in_value
);
393 // Gets the Value at the given index. Modifies |out_value| (and returns true)
394 // only if the index falls within the current list range.
395 // Note that the list always owns the Value passed out via |out_value|.
396 bool Get(size_t index
, Value
** out_value
) const;
398 // Convenience forms of Get(). Modifies |out_value| (and returns true)
399 // only if the index is valid and the Value at that index can be returned
400 // in the specified form.
401 bool GetBoolean(size_t index
, bool* out_value
) const;
402 bool GetInteger(size_t index
, int* out_value
) const;
403 bool GetDouble(size_t index
, double* out_value
) const;
404 bool GetString(size_t index
, std::string
* out_value
) const;
405 bool GetString(size_t index
, string16
* out_value
) const;
406 bool GetBinary(size_t index
, BinaryValue
** out_value
) const;
407 bool GetDictionary(size_t index
, DictionaryValue
** out_value
) const;
408 bool GetList(size_t index
, ListValue
** out_value
) const;
410 // Removes the Value with the specified index from this list.
411 // If |out_value| is non-NULL, the removed Value AND ITS OWNERSHIP will be
412 // passed out via |out_value|. If |out_value| is NULL, the removed value will
413 // be deleted. This method returns true if |index| is valid; otherwise
414 // it will return false and the ListValue object will be unchanged.
415 bool Remove(size_t index
, Value
** out_value
);
417 // Removes the first instance of |value| found in the list, if any, and
418 // deletes it. |index| is the location where |value| was found. Returns false
420 bool Remove(const Value
& value
, size_t* index
);
422 // Appends a Value to the end of the list.
423 void Append(Value
* in_value
);
425 // Appends a Value if it's not already present. Takes ownership of the
426 // |in_value|. Returns true if successful, or false if the value was already
427 // present. If the value was already present the |in_value| is deleted.
428 bool AppendIfNotPresent(Value
* in_value
);
430 // Insert a Value at index.
431 // Returns true if successful, or false if the index was out of range.
432 bool Insert(size_t index
, Value
* in_value
);
434 // Swaps contents with the |other| list.
435 void Swap(ListValue
* other
) {
436 list_
.swap(other
->list_
);
440 iterator
begin() { return list_
.begin(); }
441 iterator
end() { return list_
.end(); }
443 const_iterator
begin() const { return list_
.begin(); }
444 const_iterator
end() const { return list_
.end(); }
446 // Overridden from Value:
447 virtual bool GetAsList(ListValue
** out_value
) OVERRIDE
;
448 virtual bool GetAsList(const ListValue
** out_value
) const OVERRIDE
;
449 virtual ListValue
* DeepCopy() const OVERRIDE
;
450 virtual bool Equals(const Value
* other
) const OVERRIDE
;
455 DISALLOW_COPY_AND_ASSIGN(ListValue
);
458 // This interface is implemented by classes that know how to serialize and
459 // deserialize Value objects.
460 class BASE_EXPORT ValueSerializer
{
462 virtual ~ValueSerializer();
464 virtual bool Serialize(const Value
& root
) = 0;
466 // This method deserializes the subclass-specific format into a Value object.
467 // If the return value is non-NULL, the caller takes ownership of returned
468 // Value. If the return value is NULL, and if error_code is non-NULL,
469 // error_code will be set with the underlying error.
470 // If |error_message| is non-null, it will be filled in with a formatted
471 // error message including the location of the error if appropriate.
472 virtual Value
* Deserialize(int* error_code
, std::string
* error_str
) = 0;
477 // http://crbug.com/88666
478 using base::DictionaryValue
;
479 using base::ListValue
;
480 using base::StringValue
;
483 #endif // BASE_VALUES_H_