1/*
2 *  Copyright 2015 The WebRTC Project Authors. All rights reserved.
3 *
4 *  Use of this source code is governed by a BSD-style license
5 *  that can be found in the LICENSE file in the root of the source
6 *  tree. An additional intellectual property rights grant can be found
7 *  in the file PATENTS.  All contributing project authors may
8 *  be found in the AUTHORS file in the root of the source tree.
9 */
10
11#ifndef WEBRTC_BASE_OPTIONAL_H_
12#define WEBRTC_BASE_OPTIONAL_H_
13
14#include <algorithm>
15#include <utility>
16
17#include "webrtc/base/checks.h"
18
19namespace rtc {
20
21// Simple std::experimental::optional-wannabe. It either contains a T or not.
22// In order to keep the implementation simple and portable, this implementation
23// actually contains a (default-constructed) T even when it supposedly doesn't
24// contain a value; use e.g. rtc::scoped_ptr<T> instead if that's too
25// expensive.
26//
27// A moved-from Optional<T> may only be destroyed, and assigned to if T allows
28// being assigned to after having been moved from. Specifically, you may not
29// assume that it just doesn't contain a value anymore.
30//
31// Examples of good places to use Optional:
32//
33// - As a class or struct member, when the member doesn't always have a value:
34//     struct Prisoner {
35//       std::string name;
36//       Optional<int> cell_number;  // Empty if not currently incarcerated.
37//     };
38//
39// - As a return value for functions that may fail to return a value on all
40//   allowed inputs. For example, a function that searches an array might
41//   return an Optional<size_t> (the index where it found the element, or
42//   nothing if it didn't find it); and a function that parses numbers might
43//   return Optional<double> (the parsed number, or nothing if parsing failed).
44//
45// Examples of bad places to use Optional:
46//
47// - As a return value for functions that may fail because of disallowed
48//   inputs. For example, a string length function should not return
49//   Optional<size_t> so that it can return nothing in case the caller passed
50//   it a null pointer; the function should probably use RTC_[D]CHECK instead,
51//   and return plain size_t.
52//
53// - As a return value for functions that may fail to return a value on all
54//   allowed inputs, but need to tell the caller what went wrong. Returning
55//   Optional<double> when parsing a single number as in the example above
56//   might make sense, but any larger parse job is probably going to need to
57//   tell the caller what the problem was, not just that there was one.
58//
59// TODO(kwiberg): Get rid of this class when the standard library has
60// std::optional (and we're allowed to use it).
61template <typename T>
62class Optional final {
63 public:
64  // Construct an empty Optional.
65  Optional() : has_value_(false) {}
66
67  // Construct an Optional that contains a value.
68  explicit Optional(const T& val) : value_(val), has_value_(true) {}
69  explicit Optional(T&& val) : value_(std::move(val)), has_value_(true) {}
70
71  // Copy and move constructors.
72  // TODO(kwiberg): =default the move constructor when MSVC supports it.
73  Optional(const Optional&) = default;
74  Optional(Optional&& m)
75      : value_(std::move(m.value_)), has_value_(m.has_value_) {}
76
77  // Assignment.
78  // TODO(kwiberg): =default the move assignment op when MSVC supports it.
79  Optional& operator=(const Optional&) = default;
80  Optional& operator=(Optional&& m) {
81    value_ = std::move(m.value_);
82    has_value_ = m.has_value_;
83    return *this;
84  }
85
86  friend void swap(Optional& m1, Optional& m2) {
87    using std::swap;
88    swap(m1.value_, m2.value_);
89    swap(m1.has_value_, m2.has_value_);
90  }
91
92  // Conversion to bool to test if we have a value.
93  explicit operator bool() const { return has_value_; }
94
95  // Dereferencing. Only allowed if we have a value.
96  const T* operator->() const {
97    RTC_DCHECK(has_value_);
98    return &value_;
99  }
100  T* operator->() {
101    RTC_DCHECK(has_value_);
102    return &value_;
103  }
104  const T& operator*() const {
105    RTC_DCHECK(has_value_);
106    return value_;
107  }
108  T& operator*() {
109    RTC_DCHECK(has_value_);
110    return value_;
111  }
112
113  // Dereference with a default value in case we don't have a value.
114  const T& value_or(const T& default_val) const {
115    return has_value_ ? value_ : default_val;
116  }
117
118  // Equality tests. Two Optionals are equal if they contain equivalent values,
119  // or
120  // if they're both empty.
121  friend bool operator==(const Optional& m1, const Optional& m2) {
122    return m1.has_value_ && m2.has_value_ ? m1.value_ == m2.value_
123                                          : m1.has_value_ == m2.has_value_;
124  }
125  friend bool operator!=(const Optional& m1, const Optional& m2) {
126    return m1.has_value_ && m2.has_value_ ? m1.value_ != m2.value_
127                                          : m1.has_value_ != m2.has_value_;
128  }
129
130 private:
131  // Invariant: Unless *this has been moved from, value_ is default-initialized
132  // (or copied or moved from a default-initialized T) if !has_value_.
133  T value_;
134  bool has_value_;
135};
136
137}  // namespace rtc
138
139#endif  // WEBRTC_BASE_OPTIONAL_H_
140