base: Add comments warning about using insert() a lot on flat_set.

base/containers/flat_set.h

 // Copyright 2017 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #ifndef BASE_CONTAINERS_FLAT_SET_H_
 #define BASE_CONTAINERS_FLAT_SET_H_
 
 #include <algorithm>
 #include <functional>
 #include <utility>
@@ skipping 24 matching lines @@
 //  * Sets where mutating happens in big bulks: use erase(std::remove()) idiom
 //    for erasing many elements. Insertion is harder - consider set operations
 //    or building a new vector. Set operations can be slow if one of the sets
 //    is considerably bigger. Also be aware that beating performance of
 //    sort + unique (implementation of flat_set's constructor) is hard, clever
 //    merge of many sets might not win. Generally avoid inserting into flat set
 //    without benchmarks.
 //  * Copying and iterating.
 //  * Set operations (union/intersect etc).
 //
+// Prefer to build a new flat_set from a std::vector (or similar) instead of
+// calling insert() repeatedly, which would have O(size^2) complexity.
+//
 // TODO(dyaroshev): develop standalone benchmarks to find performance boundaries
 // for different types of sets crbug.com/682215.
 //
 // If you do write a benchmark that significantly depends on using sets please
 // share your results at:
 // https://groups.google.com/a/chromium.org/forum/#!searchin/chromium-dev/vector$20based/chromium-dev/4uQMma9vj9w/HaQ-WvMOAwAJ
 //
 // Important usability aspects:
 //   * flat_set implements std::set interface from C++11 where possible. It
 //     also has reserve(), capacity() and shrink_to_fit() from std::vector.
@@ skipping 127 matching lines @@
   const_reverse_iterator rend() const;
   const_reverse_iterator crend() const;
 
   // --------------------------------------------------------------------------
   // Insert operations.
   //
   // Assume that every operation invalidates iterators and references.
   // Insertion of one element can take O(size). See the Notes section in the
   // class comments on why we do not currently implement range insertion.
   // Capacity of flat_set grows in an implementation-defined manner.
+  //
+  // NOTE: Prefer to build a new flat_set from a std::vector (or similar)
+  // instead of calling insert() repeatedly.
 
   std::pair<iterator, bool> insert(const value_type& val);
   std::pair<iterator, bool> insert(value_type&& val);
 
   iterator insert(const_iterator position_hint, const value_type& x);
   iterator insert(const_iterator position_hint, value_type&& x);
 
   template <class... Args>
   std::pair<iterator, bool> emplace(Args&&... args);
 
@@ skipping 445 matching lines @@
 // General operations.
 
 template <class Key, class Compare>
 void flat_set<Key, Compare>::swap(flat_set& other) {
   std::swap(impl_, other.impl_);
 }
 
 }  // namespace  base
 
 #endif  // BASE_CONTAINERS_FLAT_SET_H_