1// Copyright 2016 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.
4
5#ifndef MOJO_PUBLIC_CPP_BINDINGS_WTF_MAP_H_
6#define MOJO_PUBLIC_CPP_BINDINGS_WTF_MAP_H_
7
8#include <stddef.h>
9#include <utility>
10
11#include "base/macros.h"
12#include "mojo/public/cpp/bindings/lib/template_util.h"
13#include "mojo/public/cpp/bindings/lib/wtf_clone_equals_util.h"
14#include "mojo/public/cpp/bindings/type_converter.h"
15#include "third_party/WebKit/Source/wtf/HashMap.h"
16#include "third_party/WebKit/Source/wtf/text/StringHash.h"
17
18namespace mojo {
19
20// Represents a map backed by WTF::HashMap. Comparing with WTF::HashMap,
21// mojo::WTFMap is move-only and can be null.
22//
23// It is easy to convert between WTF::HashMap<K, V> and mojo::WTFMap<K, V>:
24//   - constructor WTFMap(WTF::HashMap<K, V>&&) takes the contents of a
25//     WTF::HashMap<K, V>;
26//   - method PassStorage() passes the underlying WTF::HashMap.
27//
28// NOTE: WTF::HashMap disallows certain key values. For integer types, those are
29// 0 and -1 (max value instead of -1 for unsigned). For string, that is null.
30template <typename Key, typename Value>
31class WTFMap {
32 public:
33  using Iterator = typename WTF::HashMap<Key, Value>::iterator;
34  using ConstIterator = typename WTF::HashMap<Key, Value>::const_iterator;
35
36  // Constructs an empty map.
37  WTFMap() : is_null_(false) {}
38  // Constructs a null map.
39  WTFMap(std::nullptr_t null_pointer) : is_null_(true) {}
40
41  ~WTFMap() {}
42
43  WTFMap(WTF::HashMap<Key, Value>&& other)
44      : map_(std::move(other)), is_null_(false) {}
45  WTFMap(WTFMap&& other) : is_null_(true) { Take(&other); }
46
47  WTFMap& operator=(WTF::HashMap<Key, Value>&& other) {
48    is_null_ = false;
49    map_ = std::move(other);
50    return *this;
51  }
52  WTFMap& operator=(WTFMap&& other) {
53    Take(&other);
54    return *this;
55  }
56
57  WTFMap& operator=(std::nullptr_t null_pointer) {
58    is_null_ = true;
59    map_.clear();
60    return *this;
61  }
62
63  static bool IsValidKey(const Key& key) {
64    return WTF::HashMap<Key, Value>::isValidKey(key);
65  }
66
67  // Copies the contents of some other type of map into a new WTFMap using a
68  // TypeConverter.
69  template <typename U>
70  static WTFMap From(const U& other) {
71    return TypeConverter<WTFMap, U>::Convert(other);
72  }
73
74  // Copies the contents of the WTFMap into some other type of map.
75  template <typename U>
76  U To() const {
77    return TypeConverter<U, WTFMap>::Convert(*this);
78  }
79
80  // Indicates whether the map is null (which is distinct from empty).
81  bool is_null() const { return is_null_; }
82
83  // Indicates whether the map is empty (which is distinct from null).
84  bool empty() const { return map_.isEmpty() && !is_null_; }
85
86  // Indicates the number of keys in the map, which will be zero if the map is
87  // null.
88  size_t size() const { return map_.size(); }
89
90  // Inserts a key-value pair into the map. Like WTF::HashMap::add(), this does
91  // not insert |value| if |key| is already a member of the map.
92  void insert(const Key& key, const Value& value) {
93    is_null_ = false;
94    map_.add(key, value);
95  }
96  void insert(const Key& key, Value&& value) {
97    is_null_ = false;
98    map_.add(key, std::move(value));
99  }
100
101  // Returns a reference to the value associated with the specified key,
102  // crashing the process if the key is not present in the map.
103  Value& at(const Key& key) { return map_.find(key)->value; }
104  const Value& at(const Key& key) const { return map_.find(key)->value; }
105
106  // Returns a reference to the value associated with the specified key,
107  // creating a new entry if the key is not already present in the map. A
108  // newly-created value will be value-initialized (meaning that it will be
109  // initialized by the default constructor of the value type, if any, or else
110  // will be zero-initialized).
111  Value& operator[](const Key& key) {
112    is_null_ = false;
113    if (!map_.contains(key))
114      map_.add(key, Value());
115    return at(key);
116  }
117
118  // Sets the map to empty (even if previously it was null).
119  void SetToEmpty() {
120    is_null_ = false;
121    map_.clear();
122  }
123
124  // Returns a const reference to the WTF::HashMap managed by this class. If
125  // this object is null, the return value will be an empty map.
126  const WTF::HashMap<Key, Value>& storage() const { return map_; }
127
128  // Passes the underlying storage and resets this map to null.
129  WTF::HashMap<Key, Value> PassStorage() {
130    is_null_ = true;
131    return std::move(map_);
132  }
133
134  // Swaps the contents of this WTFMap with another WTFMap of the same type
135  // (including nullness).
136  void Swap(WTFMap<Key, Value>* other) {
137    std::swap(is_null_, other->is_null_);
138    map_.swap(other->map_);
139  }
140
141  // Swaps the contents of this WTFMap with an WTF::HashMap containing keys and
142  // values of the same type. Since WTF::HashMap cannot represent the null
143  // state, the WTF::HashMap will be empty if WTFMap is null. The WTFMap will
144  // always be left in a non-null state.
145  void Swap(WTF::HashMap<Key, Value>* other) {
146    is_null_ = false;
147    map_.swap(*other);
148  }
149
150  // Returns a new WTFMap that contains a copy of the contents of this map. If
151  // the key/value type defines a Clone() method, it will be used; otherwise
152  // copy constructor/assignment will be used.
153  //
154  // Please note that calling this method will fail compilation if the key/value
155  // type cannot be cloned (which usually means that it is a Mojo handle type or
156  // a type containing Mojo handles).
157  WTFMap Clone() const {
158    WTFMap result;
159    result.is_null_ = is_null_;
160    result.map_ = internal::Clone(map_);
161    return result;
162  }
163
164  // Indicates whether the contents of this map are equal to those of another
165  // WTFMap (including nullness). If the key/value type defines an Equals()
166  // method, it will be used; otherwise == operator will be used.
167  bool Equals(const WTFMap& other) const {
168    if (is_null() != other.is_null())
169      return false;
170    return internal::Equals(map_, other.map_);
171  }
172
173  ConstIterator begin() const { return map_.begin(); }
174  Iterator begin() { return map_.begin(); }
175
176  ConstIterator end() const { return map_.end(); }
177  Iterator end() { return map_.end(); }
178
179  // Returns the iterator pointing to the entry for |key|, if present, or else
180  // returns end().
181  ConstIterator find(const Key& key) const { return map_.find(key); }
182  Iterator find(const Key& key) { return map_.find(key); }
183
184  explicit operator bool() const { return !is_null_; }
185
186 private:
187  void Take(WTFMap* other) {
188    operator=(nullptr);
189    Swap(other);
190  }
191
192  WTF::HashMap<Key, Value> map_;
193  bool is_null_;
194
195  DISALLOW_COPY_AND_ASSIGN(WTFMap);
196};
197
198}  // namespace mojo
199
200#endif  // MOJO_PUBLIC_CPP_BINDINGS_WTF_MAP_H_
201