An unsorted tag

Summary:
[Folly] An `unsorted` tag.

For contexts in which it is desired explicitly to allow, as an optimization, the passing of unsorted containers, where such would ordinarily be assumed to be a pessimization or assumed to be incorrect.

Reviewed By: igorsugak

Differential Revision: D6782860

fbshipit-source-id: 0bc7002306497e8bb0a62c4589d4f243da062ff8

folly/Utility.h

@@ -270,7 +270,7 @@ constexpr initlist_construct_t initlist_construct{};
  *
  *  void takes_numbers(std::vector<int> alist) {
  *    std::sort(alist.begin(), alist.end());
- *    takes_numbers_assume_sorted(folly::presorted, alist);
+ *    takes_numbers(folly::presorted, alist);
  *  }
  *
  *  void takes_numbers(folly::presorted_t, std::vector<int> alist) {
@@ -283,6 +283,27 @@ constexpr initlist_construct_t initlist_construct{};
 struct presorted_t {};
 constexpr presorted_t presorted{};
 
+/**
+ * A generic tag type to indicate that some constructor or method accepts an
+ * unsorted container. Useful in contexts which might have some reason to assume
+ * a container to be sorted.
+ *
+ * Example:
+ *
+ *  void takes_numbers(std::vector<int> alist) {
+ *    takes_numbers(folly::unsorted, alist);
+ *  }
+ *
+ *  void takes_numbers(folly::unsorted_t, std::vector<int> alist) {
+ *    std::sort(alist.begin(), alist.end());
+ *    for (i : alist) {
+ *      // some behavior which is defined and safe only when alist is sorted ...
+ *    }
+ *  }
+ */
+struct unsorted_t {};
+constexpr unsorted_t unsorted{};
+
 /**
  * A simple function object that passes its argument through unchanged.
  *