Class google::cloud::StatusOr (2.10.1)

StatusOr <T> represents either a usable T value or a Status object explaining why a T value is not present. Typical usage of StatusOr <T> looks like usage of a smart pointer, or even a std::optional<T> , in that you first check its validity using a conversion to bool (or by calling StatusOr::ok() ), then you may dereference the object to access the contained value.

It is undefined behavior (UB) to dereference a StatusOr <T> that is not "ok". For example:

 StatusOr<Foo> foo = FetchFoo();
if (!foo) {  // Same as !foo.ok()
  // handle error and probably look at foo.status()
} else {
  foo->DoSomethingFooey();  // UB if !foo
} 

Alternatively, you may call the StatusOr::value() member function, which is defined to: (1) throw an exception if there is no T value, or (2) crash the program if exceptions are disabled. It is never UB to call value() .

 StatusOr<Foo> foo = FetchFoo();
foo.value().DoSomethingFooey();  // May throw/crash if there is no value 

Functions that can fail will often return a StatusOr <T> instead of returning an error code and taking a T out-param, or rather than directly returning the T and throwing an exception on error. StatusOr <T> is used so that callers can choose whether they want to explicitly check for errors, crash the program, or throw exceptions.

Since constructors do not have a return value, they should be designed in such a way that they cannot fail by moving the object's complex initialization logic into a separate factory function that itself can return a StatusOr <T> . For example:

 class Bar {
 public:
  Bar(Arg arg);
  ...
};
StatusOr<Bar> MakeBar() {
  ... complicated logic that might fail
  return Bar(std::move(arg));
} 

StatusOr <T> supports equality comparisons if the underlying type T does.

Post-conditions ok() == false and status() == rhs .

Post-conditions ok() == true and value() == rhs .