[go: nahoru, domu]

blob: 67147157a091e269e8d50a0841a7a8495d85c390 [file] [log] [blame]
// Copyright 2012 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#ifndef BASE_VALUES_H_
#define BASE_VALUES_H_
#include <stddef.h>
#include <stdint.h>
#include <array>
#include <initializer_list>
#include <iosfwd>
#include <iterator>
#include <memory>
#include <optional>
#include <string>
#include <string_view>
#include <utility>
#include <vector>
#include "base/base_export.h"
#include "base/bit_cast.h"
#include "base/compiler_specific.h"
#include "base/containers/checked_iterators.h"
#include "base/containers/flat_map.h"
#include "base/containers/span.h"
#include "base/memory/raw_ref.h"
#include "base/trace_event/base_tracing_forward.h"
#include "base/value_iterators.h"
#include "third_party/abseil-cpp/absl/types/variant.h"
namespace base {
// The `Value` class is a variant type can hold one of the following types:
// - null
// - bool
// - int
// - double
// - string (internally UTF8-encoded)
// - binary data (i.e. a blob)
// - dictionary of string keys to `Value`s
// - list of `Value`s
//
// With the exception of binary blobs, `Value` is intended to be the C++ version
// of data types that can be represented in JSON.
//
// Warning: blob support may be removed in the future.
//
// ## Usage
//
// Do not use `Value` if a more specific type would be more appropriate. For
// example, a function that only accepts dictionary values should have a
// `base::Value::Dict` parameter, not a `base::Value` parameter.
//
// Construction:
//
// `Value` is directly constructible from `bool`, `int`, `double`, binary blobs
// (`std::vector<uint8_t>`), `std::string_view`, `std::u16string_view`,
// `Value::Dict`, and `Value::List`.
//
// Copying:
//
// `Value` does not support C++ copy semantics to make it harder to accidentally
// copy large values. Instead, use `Clone()` to manually create a deep copy.
//
// Reading:
//
// `GetBool()`, GetInt()`, et cetera `CHECK()` that the `Value` has the correct
// subtype before returning the contained value. `bool`, `int`, `double` are
// returned by value. Binary blobs, `std::string`, `Value::Dict`, `Value::List`
// are returned by reference.
//
// `GetIfBool()`, `GetIfInt()`, et cetera return `std::nullopt`/`nullptr` if
// the `Value` does not have the correct subtype; otherwise, returns the value
// wrapped in an `std::optional` (for `bool`, `int`, `double`) or by pointer
// (for binary blobs, `std::string`, `Value::Dict`, `Value::List`).
//
// Note: both `GetDouble()` and `GetIfDouble()` still return a non-null result
// when the subtype is `Value::Type::INT`. In that case, the stored value is
// coerced to a double before being returned.
//
// Assignment:
//
// It is not possible to directly assign `bool`, `int`, et cetera to a `Value`.
// Instead, wrap the underlying type in `Value` before assigning.
//
// ## Dictionaries and Lists
//
// `Value` provides the `Value::Dict` and `Value::List` container types for
// working with dictionaries and lists of values respectively, rather than
// exposing the underlying container types directly. This allows the types to
// provide convenient helpers for dictionaries and lists, as well as giving
// greater flexibility for changing implementation details in the future.
//
// Both container types support enough STL-isms to be usable in range-based for
// loops and generic operations such as those from <algorithm>.
//
// Dictionaries support:
// - `empty()`, `size()`, `begin()`, `end()`, `cbegin()`, `cend()`,
// `contains()`, `clear()`, `erase()`: Identical to the STL container
// equivalents, with additional safety checks, e.g. iterators will
// `CHECK()` if `end()` is dereferenced.
//
// - `Clone()`: Create a deep copy.
// - `Merge()`: Merge another dictionary into this dictionary.
// - `Find()`: Find a value by `std::string_view` key, returning nullptr if the
// key is not present.
// - `FindBool()`, `FindInt()`, ...: Similar to `Find()`, but ensures that the
// `Value` also has the correct subtype. Same return semantics as
// `GetIfBool()`, `GetIfInt()`, et cetera, returning `std::nullopt` or
// `nullptr` if the key is not present or the value has the wrong subtype.
// - `Set()`: Associate a value with a `std::string_view` key. Accepts `Value`
// or any of the subtypes that `Value` can hold.
// - `Remove()`: Remove the key from this dictionary, if present.
// - `Extract()`: If the key is present in the dictionary, removes the key from
// the dictionary and transfers ownership of `Value` to the caller.
// Otherwise, returns `std::nullopt`.
//
// Dictionaries also support an additional set of helper methods that operate on
// "paths": `FindByDottedPath()`, `SetByDottedPath()`, `RemoveByDottedPath()`,
// and `ExtractByDottedPath()`. Dotted paths are a convenience method of naming
// intermediate nested dictionaries, separating the components of the path using
// '.' characters. For example, finding a string path on a `Value::Dict` using
// the dotted path:
//
// "aaa.bbb.ccc"
//
// Will first look for a `Value::Type::DICT` associated with the key "aaa", then
// another `Value::Type::DICT` under the "aaa" dict associated with the
// key "bbb", and then a `Value::Type::STRING` under the "bbb" dict associated
// with the key "ccc".
//
// If a path only has one component (i.e. has no dots), please use the regular,
// non-path APIs.
//
// Lists support:
// - `empty()`, `size()`, `begin()`, `end()`, `cbegin()`, `cend()`,
// `rbegin()`, `rend()`, `front()`, `back()`, `reserve()`, `operator[]`,
// `clear()`, `erase()`: Identical to the STL container equivalents, with
// additional safety checks, e.g. `operator[]` will `CHECK()` if the index
// is out of range.
// - `Clone()`: Create a deep copy.
// - `Append()`: Append a value to the end of the list. Accepts `Value` or any
// of the subtypes that `Value` can hold.
// - `Insert()`: Insert a `Value` at a specified point in the list.
// - `EraseValue()`: Erases all matching `Value`s from the list.
// - `EraseIf()`: Erase all `Value`s matching an arbitrary predicate from the
// list.
class BASE_EXPORT GSL_OWNER Value {
public:
using BlobStorage = std::vector<uint8_t>;
class Dict;
class List;
enum class Type : unsigned char {
NONE = 0,
BOOLEAN,
INTEGER,
DOUBLE,
STRING,
BINARY,
DICT,
LIST,
// Note: Do not add more types. See the file-level comment above for why.
};
// Adaptors for converting from the old way to the new way and vice versa.
static Value FromUniquePtrValue(std::unique_ptr<Value> val);
static std::unique_ptr<Value> ToUniquePtrValue(Value val);
Value() noexcept;
Value(Value&&) noexcept;
Value& operator=(Value&&) noexcept;
// Deleted to prevent accidental copying.
Value(const Value&) = delete;
Value& operator=(const Value&) = delete;
// Creates a deep copy of this value.
Value Clone() const;
// Creates a `Value` of `type`. The data of the corresponding type will be
// default constructed.
explicit Value(Type type);
// Constructor for `Value::Type::BOOLEAN`.
explicit Value(bool value);
// Prevent pointers from implicitly converting to bool. Another way to write
// this would be to template the bool constructor and use SFINAE to only allow
// use if `std::is_same_v<T, bool>` is true, but this has surprising behavior
// with range-based for loops over a `std::vector<bool>` (which will
// unintuitively match the int overload instead).
//
// The `const` is load-bearing; otherwise, a `char*` argument would prefer the
// deleted overload due to requiring a qualification conversion.
template <typename T>
explicit Value(const T*) = delete;
// Constructor for `Value::Type::INT`.
explicit Value(int value);
// Constructor for `Value::Type::DOUBLE`.
explicit Value(double value);
// Constructors for `Value::Type::STRING`.
explicit Value(std::string_view value);
explicit Value(std::u16string_view value);
// `char*` and `char16_t*` are needed to provide a more specific overload than
// the deleted `const T*` overload above.
explicit Value(const char* value);
explicit Value(const char16_t* value);
// `std::string&&` allows for efficient move construction.
explicit Value(std::string&& value) noexcept;
// Constructors for `Value::Type::BINARY`.
explicit Value(const std::vector<char>& value);
explicit Value(base::span<const uint8_t> value);
explicit Value(BlobStorage&& value) noexcept;
// Constructor for `Value::Type::DICT`.
explicit Value(Dict&& value) noexcept;
// Constructor for `Value::Type::LIST`.
explicit Value(List&& value) noexcept;
~Value();
// Returns the name for a given `type`.
static const char* GetTypeName(Type type);
// Returns the type of the value stored by the current Value object.
Type type() const { return static_cast<Type>(data_.index()); }
// Returns true if the current object represents a given type.
bool is_none() const { return type() == Type::NONE; }
bool is_bool() const { return type() == Type::BOOLEAN; }
bool is_int() const { return type() == Type::INTEGER; }
bool is_double() const { return type() == Type::DOUBLE; }
bool is_string() const { return type() == Type::STRING; }
bool is_blob() const { return type() == Type::BINARY; }
bool is_dict() const { return type() == Type::DICT; }
bool is_list() const { return type() == Type::LIST; }
// Returns the stored data if the type matches, or `std::nullopt`/`nullptr`
// otherwise. `bool`, `int`, and `double` are returned in a wrapped
// `std::optional`; blobs, `Value::Dict`, and `Value::List` are returned by
// pointer.
std::optional<bool> GetIfBool() const;
std::optional<int> GetIfInt() const;
// Returns a non-null value for both `Value::Type::DOUBLE` and
// `Value::Type::INT`, converting the latter to a double.
std::optional<double> GetIfDouble() const;
const std::string* GetIfString() const;
std::string* GetIfString();
const BlobStorage* GetIfBlob() const;
const Dict* GetIfDict() const;
Dict* GetIfDict();
const List* GetIfList() const;
List* GetIfList();
// Similar to the `GetIf...()` variants above, but fails with a `CHECK()` on a
// type mismatch. `bool`, `int`, and `double` are returned by value; blobs,
// `Value::Dict`, and `Value::List` are returned by reference.
bool GetBool() const;
int GetInt() const;
// Returns a value for both `Value::Type::DOUBLE` and `Value::Type::INT`,
// converting the latter to a double.
double GetDouble() const;
const std::string& GetString() const;
std::string& GetString();
const BlobStorage& GetBlob() const;
const Dict& GetDict() const;
Dict& GetDict();
const List& GetList() const;
List& GetList();
// Transfers ownership of the underlying value. Similarly to `Get...()`
// variants above, fails with a `CHECK()` on a type mismatch. After
// transferring the ownership `*this` is in a valid, but unspecified, state.
// Prefer over `std::move(value.Get...())` so clang-tidy can warn about
// potential use-after-move mistakes.
std::string TakeString() &&;
Dict TakeDict() &&;
List TakeList() &&;
// Represents a dictionary of string keys to Values.
class BASE_EXPORT GSL_OWNER Dict {
public:
using iterator = detail::dict_iterator;
using const_iterator = detail::const_dict_iterator;
Dict();
Dict(Dict&&) noexcept;
Dict& operator=(Dict&&) noexcept;
// Deleted to prevent accidental copying.
Dict(const Dict&) = delete;
Dict& operator=(const Dict&) = delete;
// Takes move_iterators iterators that return std::pair<std::string, Value>,
// and moves their values into a new Dict. Adding all entries at once
// results in a faster initial sort operation. Takes move iterators to avoid
// having to clone the input.
template <class IteratorType>
explicit Dict(std::move_iterator<IteratorType> first,
std::move_iterator<IteratorType> last) {
// Need to move into a vector first, since `storage_` currently uses
// unique_ptrs.
std::vector<std::pair<std::string, std::unique_ptr<Value>>> values;
for (auto current = first; current != last; ++current) {
// With move iterators, no need to call Clone(), but do need to move
// to a temporary first, as accessing either field individually will
// directly from the iterator will delete the other field.
auto value = *current;
values.emplace_back(std::move(value.first),
std::make_unique<Value>(std::move(value.second)));
}
storage_ =
flat_map<std::string, std::unique_ptr<Value>>(std::move(values));
}
~Dict();
// Returns true if there are no entries in this dictionary and false
// otherwise.
bool empty() const;
// Returns the number of entries in this dictionary.
size_t size() const;
// Returns an iterator to the first entry in this dictionary.
iterator begin();
const_iterator begin() const;
const_iterator cbegin() const;
// Returns an iterator following the last entry in this dictionary. May not
// be dereferenced.
iterator end();
const_iterator end() const;
const_iterator cend() const;
// Returns true if `key` is an entry in this dictionary.
bool contains(std::string_view key) const;
// Removes all entries from this dictionary.
REINITIALIZES_AFTER_MOVE void clear();
// Removes the entry referenced by `pos` in this dictionary and returns an
// iterator to the entry following the removed entry.
iterator erase(iterator pos);
iterator erase(const_iterator pos);
// Creates a deep copy of this dictionary.
Dict Clone() const;
// Merges the entries from `dict` into this dictionary. If an entry with the
// same key exists in this dictionary and `dict`:
// - if both entries are dictionaries, they will be recursively merged
// - otherwise, the already-existing entry in this dictionary will be
// overwritten with the entry from `dict`.
void Merge(Dict dict);
// Finds the entry corresponding to `key` in this dictionary. Returns
// nullptr if there is no such entry.
const Value* Find(std::string_view key) const;
Value* Find(std::string_view key);
// Similar to `Find()` above, but returns `std::nullopt`/`nullptr` if the
// type of the entry does not match. `bool`, `int`, and `double` are
// returned in a wrapped `std::optional`; blobs, `Value::Dict`, and
// `Value::List` are returned by pointer.
std::optional<bool> FindBool(std::string_view key) const;
std::optional<int> FindInt(std::string_view key) const;
// Returns a non-null value for both `Value::Type::DOUBLE` and
// `Value::Type::INT`, converting the latter to a double.
std::optional<double> FindDouble(std::string_view key) const;
const std::string* FindString(std::string_view key) const;
std::string* FindString(std::string_view key);
const BlobStorage* FindBlob(std::string_view key) const;
const Dict* FindDict(std::string_view key) const;
Dict* FindDict(std::string_view key);
const List* FindList(std::string_view key) const;
List* FindList(std::string_view key);
// If there's a value of the specified type at `key` in this dictionary,
// returns it. Otherwise, creates an empty container of the specified type,
// inserts it at `key`, and returns it. If there's a value of some other
// type at `key`, will overwrite that entry.
Dict* EnsureDict(std::string_view key);
List* EnsureList(std::string_view key);
// Sets an entry with `key` and `value` in this dictionary, overwriting any
// existing entry with the same `key`. Returns a pointer to the set `value`.
Value* Set(std::string_view key, Value&& value) &;
Value* Set(std::string_view key, bool value) &;
template <typename T>
Value* Set(std::string_view, const T*) & = delete;
Value* Set(std::string_view key, int value) &;
Value* Set(std::string_view key, double value) &;
Value* Set(std::string_view key, std::string_view value) &;
Value* Set(std::string_view key, std::u16string_view value) &;
Value* Set(std::string_view key, const char* value) &;
Value* Set(std::string_view key, const char16_t* value) &;
Value* Set(std::string_view key, std::string&& value) &;
Value* Set(std::string_view key, BlobStorage&& value) &;
Value* Set(std::string_view key, Dict&& value) &;
Value* Set(std::string_view key, List&& value) &;
// Rvalue overrides of the `Set` methods, which allow you to construct
// a `Value::Dict` builder-style:
//
// Value::Dict result =
// Value::Dict()
// .Set("key-1", "first value")
// .Set("key-2", 2)
// .Set("key-3", true)
// .Set("nested-dictionary", Value::Dict()
// .Set("nested-key-1", "value")
// .Set("nested-key-2", true))
// .Set("nested-list", Value::List()
// .Append("nested-list-value")
// .Append(5)
// .Append(true));
//
// Each method returns a rvalue reference to `this`, so this is as efficient
// as stand-alone calls to `Set`, while also making it harder to
// accidentally insert items in the wrong dictionary.
//
// The equivalent code without using these builder-style methods:
//
// Value::Dict no_builder_example;
// no_builder_example.Set("key-1", "first value")
// no_builder_example.Set("key-2", 2)
// no_builder_example.Set("key-3", true)
// Value::Dict nested_dictionary;
// nested_dictionary.Set("nested-key-1", "value");
// nested_dictionary.Set("nested-key-2", true);
// no_builder_example.Set("nested_dictionary",
// std::move(nested_dictionary));
// Value::List nested_list;
// nested_list.Append("nested-list-value");
// nested_list.Append(5);
// nested_list.Append(true);
// no_builder_example.Set("nested-list", std::move(nested_list));
//
// Sometimes `git cl format` does a less than perfect job formatting these
// chained `Set` calls. In these cases you can use a trailing empty comment
// to influence the code formatting:
//
// Value::Dict result = Value::Dict().Set(
// "nested",
// base::Value::Dict().Set("key", "value").Set("other key", "other"));
//
// Value::Dict result = Value::Dict().Set("nested",
// base::Value::Dict() //
// .Set("key", "value")
// .Set("other key", "value"));
//
Dict&& Set(std::string_view key, Value&& value) &&;
Dict&& Set(std::string_view key, bool value) &&;
template <typename T>
Dict&& Set(std::string_view, const T*) && = delete;
Dict&& Set(std::string_view key, int value) &&;
Dict&& Set(std::string_view key, double value) &&;
Dict&& Set(std::string_view key, std::string_view value) &&;
Dict&& Set(std::string_view key, std::u16string_view value) &&;
Dict&& Set(std::string_view key, const char* value) &&;
Dict&& Set(std::string_view key, const char16_t* value) &&;
Dict&& Set(std::string_view key, std::string&& value) &&;
Dict&& Set(std::string_view key, BlobStorage&& value) &&;
Dict&& Set(std::string_view key, Dict&& value) &&;
Dict&& Set(std::string_view key, List&& value) &&;
// Removes the entry corresponding to `key` from this dictionary. Returns
// true if an entry was removed or false otherwise.
bool Remove(std::string_view key);
// Similar to `Remove()`, but returns the value corresponding to the removed
// entry or `std::nullopt` otherwise.
std::optional<Value> Extract(std::string_view key);
// Equivalent to the above methods but operating on paths instead of keys.
// A path is shorthand syntax for referring to a key nested inside
// intermediate dictionaries, with components delimited by ".". Paths may
// not be empty.
//
// Prefer the non-path methods above when possible. Paths that have only one
// component (i.e. no dots in the path) should never use the path-based
// methods.
//
// Originally, the path-based APIs were the only way of specifying a key, so
// there are likely to be many legacy (and unnecessary) uses of the path
// APIs that do not actually require traversing nested dictionaries.
const Value* FindByDottedPath(std::string_view path) const;
Value* FindByDottedPath(std::string_view path);
std::optional<bool> FindBoolByDottedPath(std::string_view path) const;
std::optional<int> FindIntByDottedPath(std::string_view path) const;
// Returns a non-null value for both `Value::Type::DOUBLE` and
// `Value::Type::INT`, converting the latter to a double.
std::optional<double> FindDoubleByDottedPath(std::string_view path) const;
const std::string* FindStringByDottedPath(std::string_view path) const;
std::string* FindStringByDottedPath(std::string_view path);
const BlobStorage* FindBlobByDottedPath(std::string_view path) const;
const Dict* FindDictByDottedPath(std::string_view path) const;
Dict* FindDictByDottedPath(std::string_view path);
const List* FindListByDottedPath(std::string_view path) const;
List* FindListByDottedPath(std::string_view path);
// Creates a new entry with a dictionary for any non-last component that is
// missing an entry while performing the path traversal. Will fail if any
// non-last component of the path refers to an already-existing entry that
// is not a dictionary. Returns `nullptr` on failure.
//
// Warning: repeatedly using this API to enter entries in the same nested
// dictionary is inefficient, so please do not write the following:
//
// bad_example.SetByDottedPath("a.nested.dictionary.field_1", 1);
// bad_example.SetByDottedPath("a.nested.dictionary.field_2", "value");
// bad_example.SetByDottedPath("a.nested.dictionary.field_3", 1);
//
Value* SetByDottedPath(std::string_view path, Value&& value) &;
Value* SetByDottedPath(std::string_view path, bool value) &;
template <typename T>
Value* SetByDottedPath(std::string_view, const T*) & = delete;
Value* SetByDottedPath(std::string_view path, int value) &;
Value* SetByDottedPath(std::string_view path, double value) &;
Value* SetByDottedPath(std::string_view path, std::string_view value) &;
Value* SetByDottedPath(std::string_view path, std::u16string_view value) &;
Value* SetByDottedPath(std::string_view path, const char* value) &;
Value* SetByDottedPath(std::string_view path, const char16_t* value) &;
Value* SetByDottedPath(std::string_view path, std::string&& value) &;
Value* SetByDottedPath(std::string_view path, BlobStorage&& value) &;
Value* SetByDottedPath(std::string_view path, Dict&& value) &;
Value* SetByDottedPath(std::string_view path, List&& value) &;
// Rvalue overrides of the `SetByDottedPath` methods, which allow you to
// construct a `Value::Dict` builder-style:
//
// Value::Dict result =
// Value::Dict()
// .SetByDottedPath("a.nested.dictionary.with.key-1", "first value")
// .Set("local-key-1", 2));
//
// Each method returns a rvalue reference to `this`, so this is as efficient
// as (and less mistake-prone than) stand-alone calls to `Set`.
//
// Warning: repeatedly using this API to enter entries in the same nested
// dictionary is inefficient, so do not write this:
//
// Value::Dict bad_example =
// Value::Dict()
// .SetByDottedPath("nested.dictionary.key-1", "first value")
// .SetByDottedPath("nested.dictionary.key-2", "second value")
// .SetByDottedPath("nested.dictionary.key-3", "third value");
//
// Instead, simply write this
//
// Value::Dict good_example =
// Value::Dict()
// .Set("nested",
// base::Value::Dict()
// .Set("dictionary",
// base::Value::Dict()
// .Set(key-1", "first value")
// .Set(key-2", "second value")
// .Set(key-3", "third value")));
//
//
Dict&& SetByDottedPath(std::string_view path, Value&& value) &&;
Dict&& SetByDottedPath(std::string_view path, bool value) &&;
template <typename T>
Dict&& SetByDottedPath(std::string_view, const T*) && = delete;
Dict&& SetByDottedPath(std::string_view path, int value) &&;
Dict&& SetByDottedPath(std::string_view path, double value) &&;
Dict&& SetByDottedPath(std::string_view path, std::string_view value) &&;
Dict&& SetByDottedPath(std::string_view path, std::u16string_view value) &&;
Dict&& SetByDottedPath(std::string_view path, const char* value) &&;
Dict&& SetByDottedPath(std::string_view path, const char16_t* value) &&;
Dict&& SetByDottedPath(std::string_view path, std::string&& value) &&;
Dict&& SetByDottedPath(std::string_view path, BlobStorage&& value) &&;
Dict&& SetByDottedPath(std::string_view path, Dict&& value) &&;
Dict&& SetByDottedPath(std::string_view path, List&& value) &&;
bool RemoveByDottedPath(std::string_view path);
std::optional<Value> ExtractByDottedPath(std::string_view path);
// Estimates dynamic memory usage. Requires tracing support
// (enable_base_tracing gn flag), otherwise always returns 0. See
// base/trace_event/memory_usage_estimator.h for more info.
size_t EstimateMemoryUsage() const;
// Serializes to a string for logging and debug purposes.
std::string DebugString() const;
#if BUILDFLAG(ENABLE_BASE_TRACING)
// Write this object into a trace.
void WriteIntoTrace(perfetto::TracedValue) const;
#endif // BUILDFLAG(ENABLE_BASE_TRACING)
private:
BASE_EXPORT friend bool operator==(const Dict& lhs, const Dict& rhs);
BASE_EXPORT friend bool operator!=(const Dict& lhs, const Dict& rhs);
BASE_EXPORT friend bool operator<(const Dict& lhs, const Dict& rhs);
BASE_EXPORT friend bool operator>(const Dict& lhs, const Dict& rhs);
BASE_EXPORT friend bool operator<=(const Dict& lhs, const Dict& rhs);
BASE_EXPORT friend bool operator>=(const Dict& lhs, const Dict& rhs);
explicit Dict(const flat_map<std::string, std::unique_ptr<Value>>& storage);
// TODO(dcheng): Replace with `flat_map<std::string, Value>` once no caller
// relies on stability of pointers anymore.
flat_map<std::string, std::unique_ptr<Value>> storage_;
};
// Represents a list of Values.
class BASE_EXPORT GSL_OWNER List {
public:
using iterator = CheckedContiguousIterator<Value>;
using const_iterator = CheckedContiguousConstIterator<Value>;
using reverse_iterator = std::reverse_iterator<iterator>;
using const_reverse_iterator = std::reverse_iterator<const_iterator>;
using value_type = Value;
// Creates a list with the given capacity reserved.
// Correctly using this will greatly reduce the code size and improve
// performance when creating a list whose size is known up front.
static List with_capacity(size_t capacity);
List();
List(List&&) noexcept;
List& operator=(List&&) noexcept;
// Deleted to prevent accidental copying.
List(const List&) = delete;
List& operator=(const List&) = delete;
~List();
// Returns true if there are no values in this list and false otherwise.
bool empty() const;
// Returns the number of values in this list.
size_t size() const;
// Returns an iterator to the first value in this list.
iterator begin();
const_iterator begin() const;
const_iterator cbegin() const;
// Returns an iterator following the last value in this list. May not be
// dereferenced.
iterator end();
const_iterator end() const;
const_iterator cend() const;
// Returns a reverse iterator preceding the first value in this list. May
// not be dereferenced.
reverse_iterator rend();
const_reverse_iterator rend() const;
// Returns a reverse iterator to the last value in this list.
reverse_iterator rbegin();
const_reverse_iterator rbegin() const;
// Returns a reference to the first value in the container. Fails with
// `CHECK()` if the list is empty.
const Value& front() const;
Value& front();
// Returns a reference to the last value in the container. Fails with
// `CHECK()` if the list is empty.
const Value& back() const;
Value& back();
// Increase the capacity of the backing container, but does not change
// the size. Assume all existing iterators will be invalidated.
void reserve(size_t capacity);
// Resizes the list.
// If `new_size` is greater than current size, the extra elements in the
// back will be destroyed.
// If `new_size` is less than current size, new default-initialized elements
// will be added to the back.
// Assume all existing iterators will be invalidated.
void resize(size_t new_size);
// Returns a reference to the value at `index` in this list. Fails with a
// `CHECK()` if `index >= size()`.
const Value& operator[](size_t index) const;
Value& operator[](size_t index);
// Removes all value from this list.
REINITIALIZES_AFTER_MOVE void clear();
// Removes the value referenced by `pos` in this list and returns an
// iterator to the value following the removed value.
iterator erase(iterator pos);
const_iterator erase(const_iterator pos);
// Remove the values in the range [`first`, `last`). Returns iterator to the
// first value following the removed range, which is `last`. If `first` ==
// `last`, removes nothing and returns `last`.
iterator erase(iterator first, iterator last);
const_iterator erase(const_iterator first, const_iterator last);
// Creates a deep copy of this dictionary.
List Clone() const;
// Appends `value` to the end of this list.
void Append(Value&& value) &;
void Append(bool value) &;
template <typename T>
void Append(const T*) & = delete;
void Append(int value) &;
void Append(double value) &;
void Append(std::string_view value) &;
void Append(std::u16string_view value) &;
void Append(const char* value) &;
void Append(const char16_t* value) &;
void Append(std::string&& value) &;
void Append(BlobStorage&& value) &;
void Append(Dict&& value) &;
void Append(List&& value) &;
// Rvalue overrides of the `Append` methods, which allow you to construct
// a `Value::List` builder-style:
//
// Value::List result =
// Value::List().Append("first value").Append(2).Append(true);
//
// Each method returns a rvalue reference to `this`, so this is as efficient
// as stand-alone calls to `Append`, while at the same time making it harder
// to accidentally append to the wrong list.
//
// The equivalent code without using these builder-style methods:
//
// Value::List no_builder_example;
// no_builder_example.Append("first value");
// no_builder_example.Append(2);
// no_builder_example.Append(true);
//
List&& Append(Value&& value) &&;
List&& Append(bool value) &&;
template <typename T>
List&& Append(const T*) && = delete;
List&& Append(int value) &&;
List&& Append(double value) &&;
List&& Append(std::string_view value) &&;
List&& Append(std::u16string_view value) &&;
List&& Append(const char* value) &&;
List&& Append(const char16_t* value) &&;
List&& Append(std::string&& value) &&;
List&& Append(BlobStorage&& value) &&;
List&& Append(Dict&& value) &&;
List&& Append(List&& value) &&;
// Inserts `value` before `pos` in this list. Returns an iterator to the
// inserted value.
// TODO(dcheng): Should this provide the same set of overloads that Append()
// does?
iterator Insert(const_iterator pos, Value&& value);
// Erases all values equal to `value` from this list.
size_t EraseValue(const Value& value);
// Erases all values for which `predicate` evaluates to true from this list.
template <typename Predicate>
size_t EraseIf(Predicate predicate) {
return std::erase_if(storage_, predicate);
}
// Estimates dynamic memory usage. Requires tracing support
// (enable_base_tracing gn flag), otherwise always returns 0. See
// base/trace_event/memory_usage_estimator.h for more info.
size_t EstimateMemoryUsage() const;
// Serializes to a string for logging and debug purposes.
std::string DebugString() const;
#if BUILDFLAG(ENABLE_BASE_TRACING)
// Write this object into a trace.
void WriteIntoTrace(perfetto::TracedValue) const;
#endif // BUILDFLAG(ENABLE_BASE_TRACING)
private:
using ListStorage = std::vector<Value>;
BASE_EXPORT friend bool operator==(const List& lhs, const List& rhs);
BASE_EXPORT friend bool operator!=(const List& lhs, const List& rhs);
BASE_EXPORT friend bool operator<(const List& lhs, const List& rhs);
BASE_EXPORT friend bool operator>(const List& lhs, const List& rhs);
BASE_EXPORT friend bool operator<=(const List& lhs, const List& rhs);
BASE_EXPORT friend bool operator>=(const List& lhs, const List& rhs);
explicit List(const std::vector<Value>& storage);
std::vector<Value> storage_;
};
// Note: Do not add more types. See the file-level comment above for why.
// Comparison operators so that Values can easily be used with standard
// library algorithms and associative containers.
BASE_EXPORT friend bool operator==(const Value& lhs, const Value& rhs);
BASE_EXPORT friend bool operator!=(const Value& lhs, const Value& rhs);
BASE_EXPORT friend bool operator<(const Value& lhs, const Value& rhs);
BASE_EXPORT friend bool operator>(const Value& lhs, const Value& rhs);
BASE_EXPORT friend bool operator<=(const Value& lhs, const Value& rhs);
BASE_EXPORT friend bool operator>=(const Value& lhs, const Value& rhs);
BASE_EXPORT friend bool operator==(const Value& lhs, bool rhs);
friend bool operator==(bool lhs, const Value& rhs) { return rhs == lhs; }
friend bool operator!=(const Value& lhs, bool rhs) { return !(lhs == rhs); }
friend bool operator!=(bool lhs, const Value& rhs) { return !(lhs == rhs); }
template <typename T>
friend bool operator==(const Value& lhs, const T* rhs) = delete;
template <typename T>
friend bool operator==(const T* lhs, const Value& rhs) = delete;
template <typename T>
friend bool operator!=(const Value& lhs, const T* rhs) = delete;
template <typename T>
friend bool operator!=(const T* lhs, const Value& rhs) = delete;
BASE_EXPORT friend bool operator==(const Value& lhs, int rhs);
friend bool operator==(int lhs, const Value& rhs) { return rhs == lhs; }
friend bool operator!=(const Value& lhs, int rhs) { return !(lhs == rhs); }
friend bool operator!=(int lhs, const Value& rhs) { return !(lhs == rhs); }
BASE_EXPORT friend bool operator==(const Value& lhs, double rhs);
friend bool operator==(double lhs, const Value& rhs) { return rhs == lhs; }
friend bool operator!=(const Value& lhs, double rhs) { return !(lhs == rhs); }
friend bool operator!=(double lhs, const Value& rhs) { return !(lhs == rhs); }
// Note: std::u16string_view overload intentionally omitted: Value internally
// stores strings as UTF-8. While it is possible to implement a comparison
// operator that would not require first creating a new UTF-8 string from the
// UTF-16 string argument, it is simpler to just not implement it at all for a
// rare use case.
BASE_EXPORT friend bool operator==(const Value& lhs, std::string_view rhs);
friend bool operator==(std::string_view lhs, const Value& rhs) {
return rhs == lhs;
}
friend bool operator!=(const Value& lhs, std::string_view rhs) {
return !(lhs == rhs);
}
friend bool operator!=(std::string_view lhs, const Value& rhs) {
return !(lhs == rhs);
}
friend bool operator==(const Value& lhs, const char* rhs) {
return lhs == std::string_view(rhs);
}
friend bool operator==(const char* lhs, const Value& rhs) {
return rhs == lhs;
}
friend bool operator!=(const Value& lhs, const char* rhs) {
return !(lhs == rhs);
}
friend bool operator!=(const char* lhs, const Value& rhs) {
return !(lhs == rhs);
}
friend bool operator==(const Value& lhs, const std::string& rhs) {
return lhs == std::string_view(rhs);
}
friend bool operator==(const std::string& lhs, const Value& rhs) {
return rhs == lhs;
}
friend bool operator!=(const Value& lhs, const std::string& rhs) {
return !(lhs == rhs);
}
friend bool operator!=(const std::string& lhs, const Value& rhs) {
return !(lhs == rhs);
}
// Note: Blob support intentionally omitted as an experiment for potentially
// wholly removing Blob support from Value itself in the future.
BASE_EXPORT friend bool operator==(const Value& lhs, const Value::Dict& rhs);
friend bool operator==(const Value::Dict& lhs, const Value& rhs) {
return rhs == lhs;
}
friend bool operator!=(const Value& lhs, const Value::Dict& rhs) {
return !(lhs == rhs);
}
friend bool operator!=(const Value::Dict& lhs, const Value& rhs) {
return !(lhs == rhs);
}
BASE_EXPORT friend bool operator==(const Value& lhs, const Value::List& rhs);
friend bool operator==(const Value::List& lhs, const Value& rhs) {
return rhs == lhs;
}
friend bool operator!=(const Value& lhs, const Value::List& rhs) {
return !(lhs == rhs);
}
friend bool operator!=(const Value::List& lhs, const Value& rhs) {
return !(lhs == rhs);
}
// Estimates dynamic memory usage. Requires tracing support
// (enable_base_tracing gn flag), otherwise always returns 0. See
// base/trace_event/memory_usage_estimator.h for more info.
size_t EstimateMemoryUsage() const;
// Serializes to a string for logging and debug purposes.
std::string DebugString() const;
#if BUILDFLAG(ENABLE_BASE_TRACING)
// Write this object into a trace.
void WriteIntoTrace(perfetto::TracedValue) const;
#endif // BUILDFLAG(ENABLE_BASE_TRACING)
template <typename Visitor>
auto Visit(Visitor&& visitor) const {
return absl::visit(std::forward<Visitor>(visitor), data_);
}
private:
// For access to DoubleStorage.
friend class ValueView;
// Special case for doubles, which are aligned to 8 bytes on some
// 32-bit architectures. In this case, a simple declaration as a
// double member would make the whole union 8 byte-aligned, which
// would also force 4 bytes of wasted padding space before it in
// the Value layout.
//
// To override this, store the value as an array of 32-bit integers, and
// perform the appropriate bit casts when reading / writing to it.
class BASE_EXPORT DoubleStorage {
public:
explicit DoubleStorage(double v);
DoubleStorage(const DoubleStorage&) = default;
DoubleStorage& operator=(const DoubleStorage&) = default;
// Provide an implicit conversion to double to simplify the use of visitors
// with `Value::Visit()`. Otherwise, visitors would need a branch for
// handling `DoubleStorage` like:
//
// value.Visit([] (const auto& member) {
// using T = std::decay_t<decltype(member)>;
// if constexpr (std::is_same_v<T, Value::DoubleStorage>) {
// SomeFunction(double{member});
// } else {
// SomeFunction(member);
// }
// });
operator double() const { return base::bit_cast<double>(v_); }
private:
friend bool operator==(const DoubleStorage& lhs, const DoubleStorage& rhs) {
return double{lhs} == double{rhs};
}
friend bool operator!=(const DoubleStorage& lhs, const DoubleStorage& rhs) {
return !(lhs == rhs);
}
friend bool operator<(const DoubleStorage& lhs, const DoubleStorage& rhs) {
return double{lhs} < double{rhs};
}
friend bool operator>(const DoubleStorage& lhs, const DoubleStorage& rhs) {
return rhs < lhs;
}
friend bool operator<=(const DoubleStorage& lhs, const DoubleStorage& rhs) {
return !(rhs < lhs);
}
friend bool operator>=(const DoubleStorage& lhs, const DoubleStorage& rhs) {
return !(lhs < rhs);
}
alignas(4) std::array<char, sizeof(double)> v_;
};
// Internal constructors, allowing the simplify the implementation of Clone().
explicit Value(absl::monostate);
explicit Value(DoubleStorage storage);
// A helper for static functions used for cloning a Value or a ValueView.
class CloningHelper;
absl::variant<absl::monostate,
bool,
int,
DoubleStorage,
std::string,
BlobStorage,
Dict,
List>
data_;
};
// Adapter so `Value::Dict` or `Value::List` can be directly passed to JSON
// serialization methods without having to clone the contents and transfer
// ownership of the clone to a `Value` wrapper object.
//
// Like `std::string_view` and `span<T>`, this adapter does NOT retain
// ownership. Any underlying object that is passed by reference (i.e.
// `std::string`, `Value::BlobStorage`, `Value::Dict`, `Value::List`, or
// `Value`) MUST remain live as long as there is a `ValueView` referencing it.
//
// While it might be nice to just use the `absl::variant` type directly, the
// need to use `std::reference_wrapper` makes it clunky. `absl::variant` and
// `std::reference_wrapper` both support implicit construction, but C++ only
// allows at most one user-defined conversion in an implicit conversion
// sequence. If this adapter and its implicit constructors did not exist,
// callers would need to use `std::ref` or `std::cref` to pass `Value::Dict` or
// `Value::List` to a function with a `ValueView` parameter.
class BASE_EXPORT GSL_POINTER ValueView {
public:
ValueView() = default;
ValueView(bool value) : data_view_(value) {}
template <typename T>
ValueView(const T*) = delete;
ValueView(int value) : data_view_(value) {}
ValueView(double value)
: data_view_(absl::in_place_type_t<Value::DoubleStorage>(), value) {}
ValueView(std::string_view value) : data_view_(value) {}
ValueView(const char* value) : ValueView(std::string_view(value)) {}
ValueView(const std::string& value) : ValueView(std::string_view(value)) {}
// Note: UTF-16 is intentionally not supported. ValueView is intended to be a
// low-cost view abstraction, but Value internally represents strings as
// UTF-8, so it would not be possible to implement this without allocating an
// entirely new UTF-8 string.
ValueView(const Value::BlobStorage& value) : data_view_(value) {}
ValueView(const Value::Dict& value) : data_view_(value) {}
ValueView(const Value::List& value) : data_view_(value) {}
ValueView(const Value& value);
// This is the only 'getter' method provided as `ValueView` is not intended
// to be a general replacement of `Value`.
template <typename Visitor>
auto Visit(Visitor&& visitor) const {
return absl::visit(std::forward<Visitor>(visitor), data_view_);
}
// Returns a clone of the underlying Value.
Value ToValue() const;
private:
using ViewType =
absl::variant<absl::monostate,
bool,
int,
Value::DoubleStorage,
std::string_view,
std::reference_wrapper<const Value::BlobStorage>,
std::reference_wrapper<const Value::Dict>,
std::reference_wrapper<const Value::List>>;
public:
using DoubleStorageForTest = Value::DoubleStorage;
const ViewType& data_view_for_test() const { return data_view_; }
private:
ViewType data_view_;
};
// This interface is implemented by classes that know how to serialize
// Value objects.
class BASE_EXPORT ValueSerializer {
public:
virtual ~ValueSerializer();
virtual bool Serialize(ValueView root) = 0;
};
// This interface is implemented by classes that know how to deserialize Value
// objects.
class BASE_EXPORT ValueDeserializer {
public:
virtual ~ValueDeserializer();
// This method deserializes the subclass-specific format into a Value object.
// If the return value is non-NULL, the caller takes ownership of returned
// Value.
//
// If the return value is nullptr, and if `error_code` is non-nullptr,
// `*error_code` will be set to an integer value representing the underlying
// error. See "enum ErrorCode" below for more detail about the integer value.
//
// If `error_message` is non-nullptr, it will be filled in with a formatted
// error message including the location of the error if appropriate.
virtual std::unique_ptr<Value> Deserialize(int* error_code,
std::string* error_message) = 0;
// The integer-valued error codes form four groups:
// - The value 0 means no error.
// - Values between 1 and 999 inclusive mean an error in the data (i.e.
// content). The bytes being deserialized are not in the right format.
// - Values 1000 and above mean an error in the metadata (i.e. context). The
// file could not be read, the network is down, etc.
// - Negative values are reserved.
//
// These values are persisted to logs. Entries should not be renumbered and
// numeric values should never be reused.
enum ErrorCode {
kErrorCodeNoError = 0,
// kErrorCodeInvalidFormat is a generic error code for "the data is not in
// the right format". Subclasses of ValueDeserializer may return other
// values for more specific errors.
kErrorCodeInvalidFormat = 1,
// kErrorCodeFirstMetadataError is the minimum value (inclusive) of the
// range of metadata errors.
kErrorCodeFirstMetadataError = 1000,
};
// The `error_code` argument can be one of the ErrorCode values, but it is
// not restricted to only being 0, 1 or 1000. Subclasses of ValueDeserializer
// can define their own error code values.
static inline bool ErrorCodeIsDataError(int error_code) {
return (kErrorCodeInvalidFormat <= error_code) &&
(error_code < kErrorCodeFirstMetadataError);
}
};
// Stream operator so Values can be pretty printed by gtest.
BASE_EXPORT std::ostream& operator<<(std::ostream& out, const Value& value);
BASE_EXPORT std::ostream& operator<<(std::ostream& out,
const Value::Dict& dict);
BASE_EXPORT std::ostream& operator<<(std::ostream& out,
const Value::List& list);
// Stream operator so that enum class Types can be used in log statements.
BASE_EXPORT std::ostream& operator<<(std::ostream& out,
const Value::Type& type);
} // namespace base
#endif // BASE_VALUES_H_