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/basictypes.h"
31 #include "base/string16.h"
32 #include "build/build_config.h"
35 class DictionaryValue
;
37 class FundamentalValue
;
42 typedef std::vector
<Value
*> ValueVector
;
43 typedef std::map
<std::string
, Value
*> ValueMap
;
45 // The Value class is the base class for Values. A Value can be
46 // instantiated via the Create*Value() factory methods, or by directly
47 // creating instances of the subclasses.
63 // Convenience methods for creating Value objects for various
64 // kinds of values without thinking about which class implements them.
65 // These can always be expected to return a valid Value*.
66 static Value
* CreateNullValue();
67 static FundamentalValue
* CreateBooleanValue(bool in_value
);
68 static FundamentalValue
* CreateIntegerValue(int in_value
);
69 static FundamentalValue
* CreateDoubleValue(double in_value
);
70 static StringValue
* CreateStringValue(const std::string
& in_value
);
71 static StringValue
* CreateStringValue(const string16
& in_value
);
72 static StringValue
* CreateFilePathValue(const FilePath
& in_value
);
74 // This one can return NULL if the input isn't valid. If the return value
75 // is non-null, the new object has taken ownership of the buffer pointer.
76 static BinaryValue
* CreateBinaryValue(char* buffer
, size_t size
);
78 // Returns the type of the value stored by the current Value object.
79 // Each type will be implemented by only one subclass of Value, so it's
80 // safe to use the ValueType to determine whether you can cast from
81 // Value* to (Implementing Class)*. Also, a Value object never changes
82 // its type after construction.
83 ValueType
GetType() const { return type_
; }
85 // Returns true if the current object represents a given type.
86 bool IsType(ValueType type
) const { return type
== type_
; }
88 // These methods allow the convenient retrieval of settings.
89 // If the current setting object can be converted into the given type,
90 // the value is returned through the |out_value| parameter and true is
91 // returned; otherwise, false is returned and |out_value| is unchanged.
92 virtual bool GetAsBoolean(bool* out_value
) const;
93 virtual bool GetAsInteger(int* out_value
) const;
94 virtual bool GetAsDouble(double* out_value
) const;
95 virtual bool GetAsString(std::string
* out_value
) const;
96 virtual bool GetAsString(string16
* out_value
) const;
97 virtual bool GetAsFilePath(FilePath
* out_value
) const;
98 virtual bool GetAsList(ListValue
** out_value
);
100 // This creates a deep copy of the entire Value tree, and returns a pointer
101 // to the copy. The caller gets ownership of the copy, of course.
103 // Subclasses return their own type directly in their overrides;
104 // this works because C++ supports covariant return types.
105 virtual Value
* DeepCopy() const;
107 // Compares if two Value objects have equal contents.
108 virtual bool Equals(const Value
* other
) const;
110 // Compares if two Value objects have equal contents. Can handle NULLs.
111 // NULLs are considered equal but different from Value::CreateNullValue().
112 static bool Equals(const Value
* a
, const Value
* b
);
115 // This isn't safe for end-users (they should use the Create*Value()
116 // static methods above), but it's useful for subclasses.
117 explicit Value(ValueType type
);
124 DISALLOW_COPY_AND_ASSIGN(Value
);
127 // FundamentalValue represents the simple fundamental types of values.
128 class FundamentalValue
: public Value
{
130 explicit FundamentalValue(bool in_value
);
131 explicit FundamentalValue(int in_value
);
132 explicit FundamentalValue(double in_value
);
133 virtual ~FundamentalValue();
135 // Subclassed methods
136 virtual bool GetAsBoolean(bool* out_value
) const;
137 virtual bool GetAsInteger(int* out_value
) const;
138 virtual bool GetAsDouble(double* out_value
) const;
139 virtual FundamentalValue
* DeepCopy() const;
140 virtual bool Equals(const Value
* other
) const;
146 double double_value_
;
149 DISALLOW_COPY_AND_ASSIGN(FundamentalValue
);
152 class StringValue
: public Value
{
154 // Initializes a StringValue with a UTF-8 narrow character string.
155 explicit StringValue(const std::string
& in_value
);
157 // Initializes a StringValue with a string16.
158 explicit StringValue(const string16
& in_value
);
160 virtual ~StringValue();
162 // Subclassed methods
163 virtual bool GetAsString(std::string
* out_value
) const;
164 virtual bool GetAsString(string16
* out_value
) const;
165 virtual bool GetAsFilePath(FilePath
* out_value
) const;
166 virtual StringValue
* DeepCopy() const;
167 virtual bool Equals(const Value
* other
) const;
172 DISALLOW_COPY_AND_ASSIGN(StringValue
);
175 class BinaryValue
: public Value
{
177 virtual ~BinaryValue();
179 // Creates a Value to represent a binary buffer. The new object takes
180 // ownership of the pointer passed in, if successful.
181 // Returns NULL if buffer is NULL.
182 static BinaryValue
* Create(char* buffer
, size_t size
);
184 // For situations where you want to keep ownership of your buffer, this
185 // factory method creates a new BinaryValue by copying the contents of the
186 // buffer that's passed in.
187 // Returns NULL if buffer is NULL.
188 static BinaryValue
* CreateWithCopiedBuffer(const char* buffer
, size_t size
);
190 size_t GetSize() const { return size_
; }
191 char* GetBuffer() { return buffer_
; }
192 const char* GetBuffer() const { return buffer_
; }
194 // Overridden from Value:
195 virtual BinaryValue
* DeepCopy() const;
196 virtual bool Equals(const Value
* other
) const;
199 // Constructor is private so that only objects with valid buffer pointers
200 // and size values can be created.
201 BinaryValue(char* buffer
, size_t size
);
206 DISALLOW_COPY_AND_ASSIGN(BinaryValue
);
209 // DictionaryValue provides a key-value dictionary with (optional) "path"
210 // parsing for recursive access; see the comment at the top of the file. Keys
211 // are |std::string|s and should be UTF-8 encoded.
212 class DictionaryValue
: public Value
{
215 virtual ~DictionaryValue();
217 // Returns true if the current dictionary has a value for the given key.
218 bool HasKey(const std::string
& key
) const;
220 // Returns the number of Values in this dictionary.
221 size_t size() const { return dictionary_
.size(); }
223 // Returns whether the dictionary is empty.
224 bool empty() const { return dictionary_
.empty(); }
226 // Clears any current contents of this dictionary.
229 // Sets the Value associated with the given path starting from this object.
230 // A path has the form "<key>" or "<key>.<key>.[...]", where "." indexes
231 // into the next DictionaryValue down. Obviously, "." can't be used
232 // within a key, but there are no other restrictions on keys.
233 // If the key at any step of the way doesn't exist, or exists but isn't
234 // a DictionaryValue, a new DictionaryValue will be created and attached
235 // to the path in that location.
236 // Note that the dictionary takes ownership of the value referenced by
237 // |in_value|, and therefore |in_value| must be non-NULL.
238 void Set(const std::string
& path
, Value
* in_value
);
240 // Convenience forms of Set(). These methods will replace any existing
241 // value at that path, even if it has a different type.
242 void SetBoolean(const std::string
& path
, bool in_value
);
243 void SetInteger(const std::string
& path
, int in_value
);
244 void SetDouble(const std::string
& path
, double in_value
);
245 void SetString(const std::string
& path
, const std::string
& in_value
);
246 void SetString(const std::string
& path
, const string16
& in_value
);
248 // Like Set(), but without special treatment of '.'. This allows e.g. URLs to
250 void SetWithoutPathExpansion(const std::string
& key
, Value
* in_value
);
252 // Gets the Value associated with the given path starting from this object.
253 // A path has the form "<key>" or "<key>.<key>.[...]", where "." indexes
254 // into the next DictionaryValue down. If the path can be resolved
255 // successfully, the value for the last key in the path will be returned
256 // through the |out_value| parameter, and the function will return true.
257 // Otherwise, it will return false and |out_value| will be untouched.
258 // Note that the dictionary always owns the value that's returned.
259 bool Get(const std::string
& path
, Value
** out_value
) const;
261 // These are convenience forms of Get(). The value will be retrieved
262 // and the return value will be true if the path is valid and the value at
263 // the end of the path can be returned in the form specified.
264 bool GetBoolean(const std::string
& path
, bool* out_value
) const;
265 bool GetInteger(const std::string
& path
, int* out_value
) const;
266 bool GetDouble(const std::string
& path
, double* out_value
) const;
267 bool GetString(const std::string
& path
, std::string
* out_value
) const;
268 bool GetString(const std::string
& path
, string16
* out_value
) const;
269 bool GetStringASCII(const std::string
& path
, std::string
* out_value
) const;
270 bool GetBinary(const std::string
& path
, BinaryValue
** out_value
) const;
271 bool GetDictionary(const std::string
& path
,
272 DictionaryValue
** out_value
) const;
273 bool GetList(const std::string
& path
, ListValue
** out_value
) const;
275 // Like Get(), but without special treatment of '.'. This allows e.g. URLs to
277 bool GetWithoutPathExpansion(const std::string
& key
,
278 Value
** out_value
) const;
279 bool GetIntegerWithoutPathExpansion(const std::string
& key
,
280 int* out_value
) const;
281 bool GetDoubleWithoutPathExpansion(const std::string
& key
,
282 double* out_value
) const;
283 bool GetStringWithoutPathExpansion(const std::string
& key
,
284 std::string
* out_value
) const;
285 bool GetStringWithoutPathExpansion(const std::string
& key
,
286 string16
* out_value
) const;
287 bool GetDictionaryWithoutPathExpansion(const std::string
& key
,
288 DictionaryValue
** out_value
) const;
289 bool GetListWithoutPathExpansion(const std::string
& key
,
290 ListValue
** out_value
) const;
292 // Removes the Value with the specified path from this dictionary (or one
293 // of its child dictionaries, if the path is more than just a local key).
294 // If |out_value| is non-NULL, the removed Value AND ITS OWNERSHIP will be
295 // passed out via out_value. If |out_value| is NULL, the removed value will
296 // be deleted. This method returns true if |path| is a valid path; otherwise
297 // it will return false and the DictionaryValue object will be unchanged.
298 bool Remove(const std::string
& path
, Value
** out_value
);
300 // Like Remove(), but without special treatment of '.'. This allows e.g. URLs
301 // to be used as paths.
302 bool RemoveWithoutPathExpansion(const std::string
& key
, Value
** out_value
);
304 // Makes a copy of |this| but doesn't include empty dictionaries and lists in
305 // the copy. This never returns NULL, even if |this| itself is empty.
306 DictionaryValue
* DeepCopyWithoutEmptyChildren();
308 // Merge a given dictionary into this dictionary. This is done recursively,
309 // i.e. any subdictionaries will be merged as well. In case of key collisions,
310 // the passed in dictionary takes precedence and data already present will be
312 void MergeDictionary(const DictionaryValue
* dictionary
);
314 // This class provides an iterator for the keys in the dictionary.
315 // It can't be used to modify the dictionary.
317 // YOU SHOULD ALWAYS USE THE XXXWithoutPathExpansion() APIs WITH THESE, NOT
318 // THE NORMAL XXX() APIs. This makes sure things will work correctly if any
319 // keys have '.'s in them.
321 : private std::iterator
<std::input_iterator_tag
, const std::string
> {
323 explicit key_iterator(ValueMap::const_iterator itr
) { itr_
= itr
; }
324 key_iterator
operator++() {
328 const std::string
& operator*() { return itr_
->first
; }
329 bool operator!=(const key_iterator
& other
) { return itr_
!= other
.itr_
; }
330 bool operator==(const key_iterator
& other
) { return itr_
== other
.itr_
; }
333 ValueMap::const_iterator itr_
;
336 key_iterator
begin_keys() const { return key_iterator(dictionary_
.begin()); }
337 key_iterator
end_keys() const { return key_iterator(dictionary_
.end()); }
339 // Overridden from Value:
340 virtual DictionaryValue
* DeepCopy() const;
341 virtual bool Equals(const Value
* other
) const;
344 ValueMap dictionary_
;
346 DISALLOW_COPY_AND_ASSIGN(DictionaryValue
);
349 // This type of Value represents a list of other Value values.
350 class ListValue
: public Value
{
352 typedef ValueVector::iterator iterator
;
353 typedef ValueVector::const_iterator const_iterator
;
358 // Clears the contents of this ListValue
361 // Returns the number of Values in this list.
362 size_t GetSize() const { return list_
.size(); }
364 // Returns whether the list is empty.
365 bool empty() const { return list_
.empty(); }
367 // Sets the list item at the given index to be the Value specified by
368 // the value given. If the index beyond the current end of the list, null
369 // Values will be used to pad out the list.
370 // Returns true if successful, or false if the index was negative or
371 // the value is a null pointer.
372 bool Set(size_t index
, Value
* in_value
);
374 // Gets the Value at the given index. Modifies |out_value| (and returns true)
375 // only if the index falls within the current list range.
376 // Note that the list always owns the Value passed out via |out_value|.
377 bool Get(size_t index
, Value
** out_value
) const;
379 // Convenience forms of Get(). Modifies |out_value| (and returns true)
380 // only if the index is valid and the Value at that index can be returned
381 // in the specified form.
382 bool GetBoolean(size_t index
, bool* out_value
) const;
383 bool GetInteger(size_t index
, int* out_value
) const;
384 bool GetDouble(size_t index
, double* out_value
) const;
385 bool GetString(size_t index
, std::string
* out_value
) const;
386 bool GetString(size_t index
, string16
* out_value
) const;
387 bool GetBinary(size_t index
, BinaryValue
** out_value
) const;
388 bool GetDictionary(size_t index
, DictionaryValue
** out_value
) const;
389 bool GetList(size_t index
, ListValue
** out_value
) const;
391 // Removes the Value with the specified index from this list.
392 // If |out_value| is non-NULL, the removed Value AND ITS OWNERSHIP will be
393 // passed out via |out_value|. If |out_value| is NULL, the removed value will
394 // be deleted. This method returns true if |index| is valid; otherwise
395 // it will return false and the ListValue object will be unchanged.
396 bool Remove(size_t index
, Value
** out_value
);
398 // Removes the first instance of |value| found in the list, if any, and
399 // deletes it. Returns the index that it was located at (-1 for not present).
400 int Remove(const Value
& value
);
402 // Appends a Value to the end of the list.
403 void Append(Value
* in_value
);
405 // Appends a Value if it's not already present.
406 // Returns true if successful, or false if the value was already present.
407 bool AppendIfNotPresent(Value
* in_value
);
409 // Insert a Value at index.
410 // Returns true if successful, or false if the index was out of range.
411 bool Insert(size_t index
, Value
* in_value
);
413 // Swaps contents with the |other| list.
414 void Swap(ListValue
* other
) {
415 list_
.swap(other
->list_
);
419 ListValue::iterator
begin() { return list_
.begin(); }
420 ListValue::iterator
end() { return list_
.end(); }
422 ListValue::const_iterator
begin() const { return list_
.begin(); }
423 ListValue::const_iterator
end() const { return list_
.end(); }
425 // Overridden from Value:
426 virtual bool GetAsList(ListValue
** out_value
);
427 virtual ListValue
* DeepCopy() const;
428 virtual bool Equals(const Value
* other
) const;
433 DISALLOW_COPY_AND_ASSIGN(ListValue
);
436 // This interface is implemented by classes that know how to serialize and
437 // deserialize Value objects.
438 class ValueSerializer
{
440 virtual ~ValueSerializer();
442 virtual bool Serialize(const Value
& root
) = 0;
444 // This method deserializes the subclass-specific format into a Value object.
445 // If the return value is non-NULL, the caller takes ownership of returned
446 // Value. If the return value is NULL, and if error_code is non-NULL,
447 // error_code will be set with the underlying error.
448 // If |error_message| is non-null, it will be filled in with a formatted
449 // error message including the location of the error if appropriate.
450 virtual Value
* Deserialize(int* error_code
, std::string
* error_str
) = 0;
453 #endif // BASE_VALUES_H_