Unsafe pre-sorted construction for sorted-vector containers

[folly.git] / folly / Utility.h

diff --git a/folly/Utility.h b/folly/Utility.h
index 1969a9644b20e63c9a0e92e5878c6b3df62de375..94141c181c4f56b4980c59e2938d9a0ebf27598c 100644 (file)
--- a/folly/Utility.h
+++ b/folly/Utility.h
@@ -1,5 +1,5 @@
 /*
- * Copyright 2017 Facebook, Inc.
+ * Copyright 2016-present Facebook, Inc.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -262,6 +262,28 @@ inline in_place_index_tag<I> in_place_index(in_place_index_tag<I> = {}) {
 struct initlist_construct_t {};
 constexpr initlist_construct_t initlist_construct{};
 
+/**
+ * A generic tag type to indicate that some constructor or method is in some way
+ * unsafe and should be used only with extreme care and with full test coverage,
+ * if ever.
+ *
+ * Example:
+ *
+ *  void takes_numbers(std::vector<int> alist) {
+ *    std::sort(alist.begin(), alist.end());
+ *    takes_numbers_assume_sorted(folly::unsafe, alist);
+ *  }
+ *
+ *  void takes_numbers_assume_sorted(folly::unsafe_t, std::vector<int> alist) {
+ *    assert(std::is_sorted(alist.begin(), alist.end())); // debug mode only
+ *    for (i : alist) {
+ *      // some behavior which is defined and safe only when alist is sorted ...
+ *    }
+ *  }
+ */
+struct unsafe_t {};
+constexpr unsafe_t unsafe{};
+
 /**
  * A simple function object that passes its argument through unchanged.
  *