Move optional.h to webrtc/api/

webrtc/rtc_base/optional.h

 /*
  *  Copyright 2015 The WebRTC Project Authors. All rights reserved.
  *
  *  Use of this source code is governed by a BSD-style license
  *  that can be found in the LICENSE file in the root of the source
  *  tree. An additional intellectual property rights grant can be found
  *  in the file PATENTS.  All contributing project authors may
  *  be found in the AUTHORS file in the root of the source tree.
  */
 
+// This header is for backwards compatibility only, and will be removed soon.
+// Include webrtc/api/optional.h instead.
+
 #ifndef WEBRTC_RTC_BASE_OPTIONAL_H_
 #define WEBRTC_RTC_BASE_OPTIONAL_H_
 
-#include <algorithm>
-#include <memory>
-#include <utility>
-
-#ifdef UNIT_TEST
-#include <iomanip>
-#include <ostream>
-#endif  // UNIT_TEST
-
-#include "webrtc/api/array_view.h"
-#include "webrtc/rtc_base/checks.h"
-#include "webrtc/rtc_base/sanitizer.h"
-
-namespace rtc {
-
-namespace optional_internal {
-
-#if RTC_HAS_ASAN
-
-// This is a non-inlined function. The optimizer can't see inside it.  It
-// prevents the compiler from generating optimized code that reads value_ even
-// if it is unset. Although safe, this causes memory sanitizers to complain.
-void* FunctionThatDoesNothingImpl(void*);
-
-template <typename T>
-inline T* FunctionThatDoesNothing(T* x) {
-  return reinterpret_cast<T*>(
-      FunctionThatDoesNothingImpl(reinterpret_cast<void*>(x)));
-}
-
-#else
-
-template <typename T>
-inline T* FunctionThatDoesNothing(T* x) { return x; }
-
-#endif
-
-}  // namespace optional_internal
-
-// Simple std::optional-wannabe. It either contains a T or not.
-//
-// A moved-from Optional<T> may only be destroyed, and assigned to if T allows
-// being assigned to after having been moved from. Specifically, you may not
-// assume that it just doesn't contain a value anymore.
-//
-// Examples of good places to use Optional:
-//
-// - As a class or struct member, when the member doesn't always have a value:
-//     struct Prisoner {
-//       std::string name;
-//       Optional<int> cell_number;  // Empty if not currently incarcerated.
-//     };
-//
-// - As a return value for functions that may fail to return a value on all
-//   allowed inputs. For example, a function that searches an array might
-//   return an Optional<size_t> (the index where it found the element, or
-//   nothing if it didn't find it); and a function that parses numbers might
-//   return Optional<double> (the parsed number, or nothing if parsing failed).
-//
-// Examples of bad places to use Optional:
-//
-// - As a return value for functions that may fail because of disallowed
-//   inputs. For example, a string length function should not return
-//   Optional<size_t> so that it can return nothing in case the caller passed
-//   it a null pointer; the function should probably use RTC_[D]CHECK instead,
-//   and return plain size_t.
-//
-// - As a return value for functions that may fail to return a value on all
-//   allowed inputs, but need to tell the caller what went wrong. Returning
-//   Optional<double> when parsing a single number as in the example above
-//   might make sense, but any larger parse job is probably going to need to
-//   tell the caller what the problem was, not just that there was one.
-//
-// - As a non-mutable function argument. When you want to pass a value of a
-//   type T that can fail to be there, const T* is almost always both fastest
-//   and cleanest. (If you're *sure* that the the caller will always already
-//   have an Optional<T>, const Optional<T>& is slightly faster than const T*,
-//   but this is a micro-optimization. In general, stick to const T*.)
-//
-// TODO(kwiberg): Get rid of this class when the standard library has
-// std::optional (and we're allowed to use it).
-template <typename T>
-class Optional final {
- public:
-  // Construct an empty Optional.
-  Optional() : has_value_(false), empty_('\0') {
-    PoisonValue();
-  }
-
-  // Construct an Optional that contains a value.
-  explicit Optional(const T& value) : has_value_(true) {
-    new (&value_) T(value);
-  }
-  explicit Optional(T&& value) : has_value_(true) {
-    new (&value_) T(std::move(value));
-  }
-
-  // Copy constructor: copies the value from m if it has one.
-  Optional(const Optional& m) : has_value_(m.has_value_) {
-    if (has_value_)
-      new (&value_) T(m.value_);
-    else
-      PoisonValue();
-  }
-
-  // Move constructor: if m has a value, moves the value from m, leaving m
-  // still in a state where it has a value, but a moved-from one (the
-  // properties of which depends on T; the only general guarantee is that we
-  // can destroy m).
-  Optional(Optional&& m) : has_value_(m.has_value_) {
-    if (has_value_)
-      new (&value_) T(std::move(m.value_));
-    else
-      PoisonValue();
-  }
-
-  ~Optional() {
-    if (has_value_)
-      value_.~T();
-    else
-      UnpoisonValue();
-  }
-
-  // Copy assignment. Uses T's copy assignment if both sides have a value, T's
-  // copy constructor if only the right-hand side has a value.
-  Optional& operator=(const Optional& m) {
-    if (m.has_value_) {
-      if (has_value_) {
-        value_ = m.value_;  // T's copy assignment.
-      } else {
-        UnpoisonValue();
-        new (&value_) T(m.value_);  // T's copy constructor.
-        has_value_ = true;
-      }
-    } else {
-      reset();
-    }
-    return *this;
-  }
-
-  // Move assignment. Uses T's move assignment if both sides have a value, T's
-  // move constructor if only the right-hand side has a value. The state of m
-  // after it's been moved from is as for the move constructor.
-  Optional& operator=(Optional&& m) {
-    if (m.has_value_) {
-      if (has_value_) {
-        value_ = std::move(m.value_);  // T's move assignment.
-      } else {
-        UnpoisonValue();
-        new (&value_) T(std::move(m.value_));  // T's move constructor.
-        has_value_ = true;
-      }
-    } else {
-      reset();
-    }
-    return *this;
-  }
-
-  // Swap the values if both m1 and m2 have values; move the value if only one
-  // of them has one.
-  friend void swap(Optional& m1, Optional& m2) {
-    if (m1.has_value_) {
-      if (m2.has_value_) {
-        // Both have values: swap.
-        using std::swap;
-        swap(m1.value_, m2.value_);
-      } else {
-        // Only m1 has a value: move it to m2.
-        m2.UnpoisonValue();
-        new (&m2.value_) T(std::move(m1.value_));
-        m1.value_.~T();  // Destroy the moved-from value.
-        m1.has_value_ = false;
-        m2.has_value_ = true;
-        m1.PoisonValue();
-      }
-    } else if (m2.has_value_) {
-      // Only m2 has a value: move it to m1.
-      m1.UnpoisonValue();
-      new (&m1.value_) T(std::move(m2.value_));
-      m2.value_.~T();  // Destroy the moved-from value.
-      m1.has_value_ = true;
-      m2.has_value_ = false;
-      m2.PoisonValue();
-    }
-  }
-
-  // Destroy any contained value. Has no effect if we have no value.
-  void reset() {
-    if (!has_value_)
-      return;
-    value_.~T();
-    has_value_ = false;
-    PoisonValue();
-  }
-
-  template <class... Args>
-  void emplace(Args&&... args) {
-    if (has_value_)
-      value_.~T();
-    else
-      UnpoisonValue();
-    new (&value_) T(std::forward<Args>(args)...);
-    has_value_ = true;
-  }
-
-  // Conversion to bool to test if we have a value.
-  explicit operator bool() const { return has_value_; }
-  bool has_value() const { return has_value_; }
-
-  // Dereferencing. Only allowed if we have a value.
-  const T* operator->() const {
-    RTC_DCHECK(has_value_);
-    return &value_;
-  }
-  T* operator->() {
-    RTC_DCHECK(has_value_);
-    return &value_;
-  }
-  const T& operator*() const {
-    RTC_DCHECK(has_value_);
-    return value_;
-  }
-  T& operator*() {
-    RTC_DCHECK(has_value_);
-    return value_;
-  }
-  const T& value() const {
-    RTC_DCHECK(has_value_);
-    return value_;
-  }
-  T& value() {
-    RTC_DCHECK(has_value_);
-    return value_;
-  }
-
-  // Dereference with a default value in case we don't have a value.
-  const T& value_or(const T& default_val) const {
-    // The no-op call prevents the compiler from generating optimized code that
-    // reads value_ even if !has_value_, but only if FunctionThatDoesNothing is
-    // not completely inlined; see its declaration.).
-    return has_value_ ? *optional_internal::FunctionThatDoesNothing(&value_)
-                      : default_val;
-  }
-
-  // Dereference and move value.
-  T MoveValue() {
-    RTC_DCHECK(has_value_);
-    return std::move(value_);
-  }
-
-  // Equality tests. Two Optionals are equal if they contain equivalent values,
-  // or if they're both empty.
-  friend bool operator==(const Optional& m1, const Optional& m2) {
-    return m1.has_value_ && m2.has_value_ ? m1.value_ == m2.value_
-                                          : m1.has_value_ == m2.has_value_;
-  }
-  friend bool operator==(const Optional& opt, const T& value) {
-    return opt.has_value_ && opt.value_ == value;
-  }
-  friend bool operator==(const T& value, const Optional& opt) {
-    return opt.has_value_ && value == opt.value_;
-  }
-
-  friend bool operator!=(const Optional& m1, const Optional& m2) {
-    return m1.has_value_ && m2.has_value_ ? m1.value_ != m2.value_
-                                          : m1.has_value_ != m2.has_value_;
-  }
-  friend bool operator!=(const Optional& opt, const T& value) {
-    return !opt.has_value_ || opt.value_ != value;
-  }
-  friend bool operator!=(const T& value, const Optional& opt) {
-    return !opt.has_value_ || value != opt.value_;
-  }
-
- private:
-  // Tell sanitizers that value_ shouldn't be touched.
-  void PoisonValue() {
-    rtc::AsanPoison(rtc::MakeArrayView(&value_, 1));
-    rtc::MsanMarkUninitialized(rtc::MakeArrayView(&value_, 1));
-  }
-
-  // Tell sanitizers that value_ is OK to touch again.
-  void UnpoisonValue() {
-    rtc::AsanUnpoison(rtc::MakeArrayView(&value_, 1));
-  }
-
-  bool has_value_;  // True iff value_ contains a live value.
-  union {
-    // empty_ exists only to make it possible to initialize the union, even when
-    // it doesn't contain any data. If the union goes uninitialized, it may
-    // trigger compiler warnings.
-    char empty_;
-    // By placing value_ in a union, we get to manage its construction and
-    // destruction manually: the Optional constructors won't automatically
-    // construct it, and the Optional destructor won't automatically destroy
-    // it. Basically, this just allocates a properly sized and aligned block of
-    // memory in which we can manually put a T with placement new.
-    T value_;
-  };
-};
-
-#ifdef UNIT_TEST
-namespace optional_internal {
-
-// Checks if there's a valid PrintTo(const T&, std::ostream*) call for T.
-template <typename T>
-struct HasPrintTo {
- private:
-  struct No {};
-
-  template <typename T2>
-  static auto Test(const T2& obj)
-      -> decltype(PrintTo(obj, std::declval<std::ostream*>()));
-
-  template <typename>
-  static No Test(...);
-
- public:
-  static constexpr bool value =
-      !std::is_same<decltype(Test<T>(std::declval<const T&>())), No>::value;
-};
-
-// Checks if there's a valid operator<<(std::ostream&, const T&) call for T.
-template <typename T>
-struct HasOstreamOperator {
- private:
-  struct No {};
-
-  template <typename T2>
-  static auto Test(const T2& obj)
-      -> decltype(std::declval<std::ostream&>() << obj);
-
-  template <typename>
-  static No Test(...);
-
- public:
-  static constexpr bool value =
-      !std::is_same<decltype(Test<T>(std::declval<const T&>())), No>::value;
-};
-
-// Prefer using PrintTo to print the object.
-template <typename T>
-typename std::enable_if<HasPrintTo<T>::value, void>::type OptionalPrintToHelper(
-    const T& value,
-    std::ostream* os) {
-  PrintTo(value, os);
-}
-
-// Fall back to operator<<(std::ostream&, ...) if it exists.
-template <typename T>
-typename std::enable_if<HasOstreamOperator<T>::value && !HasPrintTo<T>::value,
-                        void>::type
-OptionalPrintToHelper(const T& value, std::ostream* os) {
-  *os << value;
-}
-
-inline void OptionalPrintObjectBytes(const unsigned char* bytes,
-                                     size_t size,
-                                     std::ostream* os) {
-  *os << "<optional with " << size << "-byte object [";
-  for (size_t i = 0; i != size; ++i) {
-    *os << (i == 0 ? "" : ((i & 1) ? "-" : " "));
-    *os << std::hex << std::setw(2) << std::setfill('0')
-        << static_cast<int>(bytes[i]);
-  }
-  *os << "]>";
-}
-
-// As a final back-up, just print the contents of the objcets byte-wise.
-template <typename T>
-typename std::enable_if<!HasOstreamOperator<T>::value && !HasPrintTo<T>::value,
-                        void>::type
-OptionalPrintToHelper(const T& value, std::ostream* os) {
-  OptionalPrintObjectBytes(reinterpret_cast<const unsigned char*>(&value),
-                           sizeof(value), os);
-}
-
-}  // namespace optional_internal
-
-// PrintTo is used by gtest to print out the results of tests. We want to ensure
-// the object contained in an Optional can be printed out if it's set, while
-// avoiding touching the object's storage if it is undefined.
-template <typename T>
-void PrintTo(const rtc::Optional<T>& opt, std::ostream* os) {
-  if (opt) {
-    optional_internal::OptionalPrintToHelper(*opt, os);
-  } else {
-    *os << "<empty optional>";
-  }
-}
-
-#endif  // UNIT_TEST
-
-}  // namespace rtc
+#include "webrtc/api/optional.h"
 
 #endif  // WEBRTC_RTC_BASE_OPTIONAL_H_