API Documentation

template<typename T = Ok> class Result

Represents a result type that can contain either a value or an error.

The Result class is used to handle operations that can produce either a value or an error. It provides a way to propagate and handle errors in a controlled manner.

Use the Result class when you have operations that can succeed and return a value, or fail and return an error. This allows you to handle both cases explicitly and make informed decisions based on the outcome.

class Image;

result::Result<Image> load_image(const std::filesystem::path& path);

int main() {
  const auto res = load_image(image_path);
  if (res.is_ok()) {
    const auto& image = res.unwrap();
    // Do something with the image.
  } else {
    const auto& error = res.unwrap_err();
    // Handle the error case.
  }
}

Template Parameters:: T – The type of the value.

Public Functions

Result()

Constructs a new empty result.

This constructor creates a new result object that is initialized with an error by default.

result::Result<> res;
assert(res.is_err());

// Print "the result is uninitialized".
std::cout << res.unwrap_err().what() << std::endl;

Result(const T &val)

Constructs a new result that contains a value.

result::Result<int> res = 200;
assert(res.is_ok());

// Print "200".
std::cout << res.unwrap() << std::endl;

Parameters:: val – The value.

Result(const errors::Error &err)

Constructs a new result that contains an error.

result::Result<int> res = errors::make("undefined error");
assert(res.is_err());

// Print "undefined error".
std::cout << res.unwrap_err().what() << std::endl;

Parameters:: err – The error.

template<typename U> explicit operator Result<U>() const

Explicitly converts the result into another result with a different value type.

This conversion operator allows explicit casting of the result into another result with a different value type. If the result contains a value, that value will be explicitly casted into the target value type. If the result contains an error, the error will be copied. See also result::Result::as.

using IntRes = result::Result<int>;

result::Result<double> square_root(double val) {
  if (value < 0) return errors::make("value must be positive");
  return std::sqrt(value);
}

int main() {
  IntRes res = static_cast<IntRes>(square_root(100.0));
  assert(res.is_ok());

  // Print "10".
  std::cout << res.unwrap() << std::endl;

  res = static_cast<IntRes>(square_root(-100.0));
  assert(res.is_err());

  // Print "value must be positive".
  std::cout << res.unwrap_err().what() << std::endl;
}

Template Parameters:: U – The target value type.
Returns:: A converted result.

template<typename U> Result<U> as() const

Converts the result into another result with a different value type.

This function allows converting the result into another result with a different value type. If the result contains a value, it will be explicitly casted into the target value type. If the result contains an error, the error will be copied.

result::Result<double> square_root(double val) {
  if (value < 0) return errors::make("value must be positive");
  return std::sqrt(value);
}

int main() {
  result::Result<int> res = square_root(100.0).as<int>();
  assert(res.is_ok());

  // Print "10".
  std::cout << res.unwrap() << std::endl;

  res = square_root(-100.0).as<int>();
  assert(res.is_err());

  // Print "value must be positive".
  std::cout << res.unwrap_err().what() << std::endl;
}

Template Parameters:: U – The target value type.
Returns:: A converted result.

inline bool is_ok() const

Checks if the result contains a value.

Returns:: true if the result contains a value, false otherwise.

inline bool is_err() const

Checks if the result contains an error.

Returns:: true if the result contains an error, false otherwise.

const T &unwrap() const

Gets the value from the result.

This function retrieves the value stored in the result object. If the result contains a value, it returns a constant reference to the value. If the result does not contain a value, it throws an exception of type errors::Error.

result::Result<int> res = 200;

// Print "200".
std::cout << res.unwrap() << std::endl;

res = errors::make("undefined error");

// Throws `errors::Error`.
// std::cout << res.unwrap() << std::endl;

Throws:: errors::Error – If the result does not contain a value.
Returns:: A constant reference to the stored value.

const errors::Error &unwrap_err() const

Gets the error from the result.

This function retrieves the error stored in the result object. If the result contains an error, it returns a constant reference to the error. If the result does not contain an error, it throws an exception of type errors::Error.

result::Result<int> res = errors::make("undefined error");

// Print "undefined error".
std::cout << res.unwrap_err().what() << std::endl;

res = 200;

// Throws `errors::Error`.
// std::cout << res.unwrap_err().what() << std::endl;

Throws:: errors::Error – If the result does not contain an error.
Returns:: A constant reference to the stored error.

struct Ok

Represents a successful (OK) status.

The Ok struct is used in conjunction with result::Result to indicate a successful status. It serves as a marker type to set the status of the result to OK when no specific value is needed.

result::Result<> res = result::Ok{};
assert(res.is_ok());