/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- * vim: set ts=8 sts=2 et sw=2 tw=80: * This Source Code Form is subject to the terms of the Mozilla Public * License, v. 2.0. If a copy of the MPL was not distributed with this * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ /* A type suitable for returning either a value or an error from a function. */ #ifndef mozilla_Result_h #define mozilla_Result_h #include <algorithm> #include <cstdint> #include <cstring> #include <type_traits> #include "mozilla/Assertions.h" #include "mozilla/Attributes.h" #include "mozilla/CompactPair.h" #include "mozilla/MaybeStorageBase.h" namespace mozilla { /** * Empty struct, indicating success for operations that have no return value. * For example, if you declare another empty struct `struct OutOfMemory {};`, * then `Result<Ok, OutOfMemory>` represents either success or OOM. */ struct Ok {}; /** * A tag used to differentiate between GenericErrorResult created by the Err * function (completely new error) and GenericErrorResult created by the * Result::propagateErr function (propagated error). This can be used to track * error propagation and eventually produce error stacks for logging/debugging * purposes. */ struct ErrorPropagationTag {}; template <typename E> class GenericErrorResult; template <typename V, typename E> class Result; namespace detail { enum class PackingStrategy { Variant, NullIsOk, LowBitTagIsError, PackedVariant, ZeroIsEmptyError, }; template <typename T> struct UnusedZero; template <typename V, typename E, PackingStrategy Strategy> class ResultImplementation; template <typename V> struct EmptyWrapper : V { constexpr EmptyWrapper() = default; explicit constexpr EmptyWrapper(const V&) {} explicit constexpr EmptyWrapper(std::in_place_t) {} constexpr V* addr() { return this; } constexpr const V* addr() const { return this; } }; // The purpose of AlignedStorageOrEmpty is to make an empty class look like // std::aligned_storage_t for the purposes of the PackingStrategy::NullIsOk // specializations of ResultImplementation below. We can't use // std::aligned_storage_t itself with an empty class, since it would no longer // be empty. template <typename V> using AlignedStorageOrEmpty = std::conditional_t<std::is_empty_v<V>, EmptyWrapper<V>, MaybeStorageBase<V>>; template <typename V, typename E> class ResultImplementationNullIsOkBase { protected: using ErrorStorageType = typename UnusedZero<E>::StorageType; static constexpr auto kNullValue = UnusedZero<E>::nullValue; static_assert(std::is_trivially_copyable_v<ErrorStorageType>); // XXX This can't be statically asserted in general, if ErrorStorageType is // not a basic type. With C++20 bit_cast, we could probably re-add such as // assertion. static_assert(kNullValue == decltype(kNullValue)(0)); CompactPair<AlignedStorageOrEmpty<V>, ErrorStorageType> mValue; public: explicit constexpr ResultImplementationNullIsOkBase(const V& aSuccessValue) : mValue(aSuccessValue, kNullValue) {} explicit constexpr ResultImplementationNullIsOkBase(V&& aSuccessValue) : mValue(std::move(aSuccessValue), kNullValue) {} template <typename... Args> explicit constexpr ResultImplementationNullIsOkBase(std::in_place_t, Args&&... aArgs) : mValue(std::piecewise_construct, std::tuple(std::in_place, std::forward<Args>(aArgs)...), std::tuple(kNullValue)) {} explicit constexpr ResultImplementationNullIsOkBase(E aErrorValue) : mValue(std::piecewise_construct, std::tuple<>(), std::tuple(UnusedZero<E>::Store(std::move(aErrorValue)))) { MOZ_ASSERT(mValue.second() != kNullValue); } constexpr ResultImplementationNullIsOkBase( ResultImplementationNullIsOkBase&& aOther) : mValue(std::piecewise_construct, std::tuple<>(), std::tuple(aOther.mValue.second())) { if constexpr (!std::is_empty_v<V>) { if (isOk()) { new (mValue.first().addr()) V(std::move(*aOther.mValue.first().addr())); } } } ResultImplementationNullIsOkBase& operator=( ResultImplementationNullIsOkBase&& aOther) { if constexpr (!std::is_empty_v<V>) { if (isOk()) { mValue.first().addr()->~V(); } } mValue.second() = std::move(aOther.mValue.second()); if constexpr (!std::is_empty_v<V>) { if (isOk()) { new (mValue.first().addr()) V(std::move(*aOther.mValue.first().addr())); } } return *this; } constexpr bool isOk() const { return mValue.second() == kNullValue; } constexpr const V& inspect() const { return *mValue.first().addr(); } constexpr V unwrap() { return std::move(*mValue.first().addr()); } constexpr void updateAfterTracing(V&& aValue) { MOZ_ASSERT(isOk()); if (!std::is_empty_v<V>) { mValue.first().addr()->~V(); new (mValue.first().addr()) V(std::move(aValue)); } } constexpr decltype(auto) inspectErr() const { return UnusedZero<E>::Inspect(mValue.second()); } constexpr E unwrapErr() { return UnusedZero<E>::Unwrap(mValue.second()); } constexpr void updateErrorAfterTracing(E&& aErrorValue) { mValue.second() = UnusedZero<E>::Store(std::move(aErrorValue)); } }; template <typename V, typename E, bool IsVTriviallyDestructible = std::is_trivially_destructible_v<V>> class ResultImplementationNullIsOk; template <typename V, typename E> class ResultImplementationNullIsOk<V, E, true> : public ResultImplementationNullIsOkBase<V, E> { public: using ResultImplementationNullIsOkBase<V, E>::ResultImplementationNullIsOkBase; }; template <typename V, typename E> class ResultImplementationNullIsOk<V, E, false> : public ResultImplementationNullIsOkBase<V, E> { public: using ResultImplementationNullIsOkBase<V, E>::ResultImplementationNullIsOkBase; ResultImplementationNullIsOk(ResultImplementationNullIsOk&&) = default; ResultImplementationNullIsOk& operator=(ResultImplementationNullIsOk&&) = default; ~ResultImplementationNullIsOk() { if (this->isOk()) { this->mValue.first().addr()->~V(); } } }; /** * Specialization for when the success type is one of integral, pointer, or * enum, where 0 is unused, and the error type is an empty struct. */ template <typename V, typename E> class ResultImplementation<V, E, PackingStrategy::ZeroIsEmptyError> { static_assert(std::is_integral_v<V> || std::is_pointer_v<V> || std::is_enum_v<V>); static_assert(std::is_empty_v<E>); V mValue; public: static constexpr PackingStrategy Strategy = PackingStrategy::ZeroIsEmptyError; explicit constexpr ResultImplementation(V aValue) : mValue(aValue) {} explicit constexpr ResultImplementation(E aErrorValue) : mValue(V(0)) {} constexpr bool isOk() const { return mValue != V(0); } constexpr V inspect() const { return mValue; } constexpr V unwrap() { return inspect(); } constexpr E inspectErr() const { return E(); } constexpr E unwrapErr() { return inspectErr(); } constexpr void updateAfterTracing(V&& aValue) { this->~ResultImplementation(); new (this) ResultImplementation(std::move(aValue)); } constexpr void updateErrorAfterTracing(E&& aErrorValue) { this->~ResultImplementation(); new (this) ResultImplementation(std::move(aErrorValue)); } }; /** * Specialization for when the success type is default-constructible and the * error type is a value type which can never have the value 0 (as determined by * UnusedZero<>). */ template <typename V, typename E> class ResultImplementation<V, E, PackingStrategy::NullIsOk> : public ResultImplementationNullIsOk<V, E> { public: static constexpr PackingStrategy Strategy = PackingStrategy::NullIsOk; using ResultImplementationNullIsOk<V, E>::ResultImplementationNullIsOk; }; template <size_t S> using UnsignedIntType = std::conditional_t< S == 1, std::uint8_t, std::conditional_t< S == 2, std::uint16_t, std::conditional_t<S == 3 || S == 4, std::uint32_t, std::conditional_t<S <= 8, std::uint64_t, void>>>>; /** * Specialization for when alignment permits using the least significant bit * as a tag bit. */ template <typename V, typename E> class ResultImplementation<V, E, PackingStrategy::LowBitTagIsError> { static_assert(std::is_trivially_copyable_v<V> && std::is_trivially_destructible_v<V>); static_assert(std::is_trivially_copyable_v<E> && std::is_trivially_destructible_v<E>); static constexpr size_t kRequiredSize = std::max(sizeof(V), sizeof(E)); using StorageType = UnsignedIntType<kRequiredSize>; #if defined(__clang__) alignas(std::max(alignof(V), alignof(E))) StorageType mBits; #else // Some gcc versions choke on using std::max with alignas, see // https://gcc.gnu.org/bugzilla/show_bug.cgi?id=94929 (and this seems to have // regressed in some gcc 9.x version before being fixed again) Keeping the // code above since we would eventually drop this when we no longer support // gcc versions with the bug. alignas(alignof(V) > alignof(E) ? alignof(V) : alignof(E)) StorageType mBits; #endif public: static constexpr PackingStrategy Strategy = PackingStrategy::LowBitTagIsError; explicit constexpr ResultImplementation(V aValue) : mBits(0) { if constexpr (!std::is_empty_v<V>) { std::memcpy(&mBits, &aValue, sizeof(V)); MOZ_ASSERT((mBits & 1) == 0); } else { (void)aValue; } } explicit constexpr ResultImplementation(E aErrorValue) : mBits(1) { if constexpr (!std::is_empty_v<E>) { std::memcpy(&mBits, &aErrorValue, sizeof(E)); MOZ_ASSERT((mBits & 1) == 0); mBits |= 1; } else { (void)aErrorValue; } } constexpr bool isOk() const { return (mBits & 1) == 0; } constexpr V inspect() const { V res; std::memcpy(&res, &mBits, sizeof(V)); return res; } constexpr V unwrap() { return inspect(); } constexpr E inspectErr() const { const auto bits = mBits ^ 1; E res; std::memcpy(&res, &bits, sizeof(E)); return res; } constexpr E unwrapErr() { return inspectErr(); } constexpr void updateAfterTracing(V&& aValue) { this->~ResultImplementation(); new (this) ResultImplementation(std::move(aValue)); } constexpr void updateErrorAfterTracing(E&& aErrorValue) { this->~ResultImplementation(); new (this) ResultImplementation(std::move(aErrorValue)); } }; // Return true if any of the struct can fit in a word. template <typename V, typename E> struct IsPackableVariant { struct VEbool { explicit constexpr VEbool(V&& aValue) : v(std::move(aValue)), ok(true) {} explicit constexpr VEbool(E&& aErrorValue) : e(std::move(aErrorValue)), ok(false) {} V v; E e; bool ok; }; struct EVbool { explicit constexpr EVbool(V&& aValue) : v(std::move(aValue)), ok(true) {} explicit constexpr EVbool(E&& aErrorValue) : e(std::move(aErrorValue)), ok(false) {} E e; V v; bool ok; }; using Impl = std::conditional_t<sizeof(VEbool) <= sizeof(EVbool), VEbool, EVbool>; static const bool value = sizeof(Impl) <= sizeof(uintptr_t); }; /** * Specialization for when both type are not using all the bytes, in order to * use one byte as a tag. */ template <typename V, typename E> class ResultImplementation<V, E, PackingStrategy::PackedVariant> { using Impl = typename IsPackableVariant<V, E>::Impl; Impl data; public: static constexpr PackingStrategy Strategy = PackingStrategy::PackedVariant; explicit constexpr ResultImplementation(V aValue) : data(std::move(aValue)) {} explicit constexpr ResultImplementation(E aErrorValue) : data(std::move(aErrorValue)) {} constexpr bool isOk() const { return data.ok; } constexpr const V& inspect() const { return data.v; } constexpr V unwrap() { return std::move(data.v); } constexpr const E& inspectErr() const { return data.e; } constexpr E unwrapErr() { return std::move(data.e); } constexpr void updateAfterTracing(V&& aValue) { MOZ_ASSERT(data.ok); this->~ResultImplementation(); new (this) ResultImplementation(std::move(aValue)); } constexpr void updateErrorAfterTracing(E&& aErrorValue) { MOZ_ASSERT(!data.ok); this->~ResultImplementation(); new (this) ResultImplementation(std::move(aErrorValue)); } }; // To use nullptr as a special value, we need the counter part to exclude zero // from its range of valid representations. // // By default assume that zero can be represented. template <typename T> struct UnusedZero { static const bool value = false; }; // This template can be used as a helper for specializing UnusedZero for scoped // enum types which never use 0 as an error value, e.g. // // namespace mozilla::detail { // // template <> // struct UnusedZero<MyEnumType> : UnusedZeroEnum<MyEnumType> {}; // // } // namespace mozilla::detail // template <typename T> struct UnusedZeroEnum { using StorageType = std::underlying_type_t<T>; static constexpr bool value = true; static constexpr StorageType nullValue = 0; static constexpr T Inspect(const StorageType& aValue) { return static_cast<T>(aValue); } static constexpr T Unwrap(StorageType aValue) { return static_cast<T>(aValue); } static constexpr StorageType Store(T aValue) { return static_cast<StorageType>(aValue); } }; // A bit of help figuring out which of the above specializations to use. // // We begin by safely assuming types don't have a spare bit, unless they are // empty. template <typename T> struct HasFreeLSB { static const bool value = std::is_empty_v<T>; }; // As an incomplete type, void* does not have a spare bit. template <> struct HasFreeLSB<void*> { static const bool value = false; }; // The lowest bit of a properly-aligned pointer is always zero if the pointee // type is greater than byte-aligned. That bit is free to use if it's masked // out of such pointers before they're dereferenced. template <typename T> struct HasFreeLSB<T*> { static const bool value = (alignof(T) & 1) == 0; }; // Select one of the previous result implementation based on the properties of // the V and E types. template <typename V, typename E> struct SelectResultImpl { static const PackingStrategy value = (UnusedZero<V>::value && std::is_empty_v<E>) ? PackingStrategy::ZeroIsEmptyError : (HasFreeLSB<V>::value && HasFreeLSB<E>::value) ? PackingStrategy::LowBitTagIsError : (UnusedZero<E>::value && sizeof(E) <= sizeof(uintptr_t)) ? PackingStrategy::NullIsOk : (std::is_default_constructible_v<V> && std::is_default_constructible_v<E> && IsPackableVariant<V, E>::value) ? PackingStrategy::PackedVariant : PackingStrategy::Variant; using Type = ResultImplementation<V, E, value>; }; template <typename T> struct IsResult : std::false_type {}; template <typename V, typename E> struct IsResult<Result<V, E>> : std::true_type {}; } // namespace detail template <typename V, typename E> constexpr auto ToResult(Result<V, E>&& aValue) -> decltype(std::forward<Result<V, E>>(aValue)) { return std::forward<Result<V, E>>(aValue); } /** * Result<V, E> represents the outcome of an operation that can either succeed * or fail. It contains either a success value of type V or an error value of * type E. * * All Result methods are const, so results are basically immutable. * This is just like Variant<V, E> but with a slightly different API, and the * following cases are optimized so Result can be stored more efficiently: * * - If both the success and error types do not use their least significant bit, * are trivially copyable and destructible, Result<V, E> is guaranteed to be as * large as the larger type. This is determined via the HasFreeLSB trait. By * default, empty classes (in particular Ok) and aligned pointer types are * assumed to have a free LSB, but you can specialize this trait for other * types. If the success type is empty, the representation is guaranteed to be * all zero bits on success. Do not change this representation! There is JIT * code that depends on it. (Implementation note: The lowest bit is used as a * tag bit: 0 to indicate the Result's bits are a success value, 1 to indicate * the Result's bits (with the 1 masked out) encode an error value) * * - Else, if the error type can't have a all-zero bits representation and is * not larger than a pointer, a CompactPair is used to represent this rather * than a Variant. This has shown to be better optimizable, and the template * code is much simpler than that of Variant, so it should also compile faster. * Whether an error type can't be all-zero bits, is determined via the * UnusedZero trait. MFBT doesn't declare any public type UnusedZero, but * nsresult is declared UnusedZero in XPCOM. * * The purpose of Result is to reduce the screwups caused by using `false` or * `nullptr` to indicate errors. * What screwups? See <https://bugzilla.mozilla.org/show_bug.cgi?id=912928> for * a partial list. * * Result<const V, E> or Result<V, const E> are not meaningful. The success or * error values in a Result instance are non-modifiable in-place anyway. This * guarantee must also be maintained when evolving Result. They can be * unwrap()ped, but this loses const qualification. However, Result<const V, E> * or Result<V, const E> may be misleading and prevent movability. Just use * Result<V, E>. (Result<const V*, E> may make sense though, just Result<const * V* const, E> is not possible.) */ template <typename V, typename E> class [[nodiscard]] Result final { // See class comment on Result<const V, E> and Result<V, const E>. static_assert(!std::is_const_v<V>); static_assert(!std::is_const_v<E>); static_assert(!std::is_reference_v<V>); static_assert(!std::is_reference_v<E>); using Impl = typename detail::SelectResultImpl<V, E>::Type; Impl mImpl; // Are you getting this error? // > error: implicit instantiation of undefined template // > 'mozilla::detail::ResultImplementation<$V,$E, // > mozilla::detail::PackingStrategy::Variant>' // You need to include "ResultVariant.h"! public: static constexpr detail::PackingStrategy Strategy = Impl::Strategy; using ok_type = V; using err_type = E; /** Create a success result. */ MOZ_IMPLICIT constexpr Result(V&& aValue) : mImpl(std::move(aValue)) { MOZ_ASSERT(isOk()); } /** Create a success result. */ MOZ_IMPLICIT constexpr Result(const V& aValue) : mImpl(aValue) { MOZ_ASSERT(isOk()); } /** Create a success result in-place. */ template <typename... Args> explicit constexpr Result(std::in_place_t, Args&&... aArgs) : mImpl(std::in_place, std::forward<Args>(aArgs)...) { MOZ_ASSERT(isOk()); } /** Create an error result. */ explicit constexpr Result(const E& aErrorValue) : mImpl(aErrorValue) { MOZ_ASSERT(isErr()); } explicit constexpr Result(E&& aErrorValue) : mImpl(std::move(aErrorValue)) { MOZ_ASSERT(isErr()); } /** * Create a (success/error) result from another (success/error) result with * different but convertible value and error types. */ template <typename V2, typename E2, typename = std::enable_if_t<std::is_convertible_v<V2, V> && std::is_convertible_v<E2, E>>> MOZ_IMPLICIT constexpr Result(Result<V2, E2>&& aOther) : mImpl(aOther.isOk() ? Impl{aOther.unwrap()} : Impl{aOther.unwrapErr()}) {} /** * Implementation detail of MOZ_TRY(). * Create an error result from another error result. */ template <typename E2> MOZ_IMPLICIT constexpr Result(GenericErrorResult<E2>&& aErrorResult) : mImpl(std::move(aErrorResult.mErrorValue)) { static_assert(std::is_convertible_v<E2, E>, "E2 must be convertible to E"); MOZ_ASSERT(isErr()); } /** * Implementation detail of MOZ_TRY(). * Create an error result from another error result. */ template <typename E2> MOZ_IMPLICIT constexpr Result(const GenericErrorResult<E2>& aErrorResult) : mImpl(aErrorResult.mErrorValue) { static_assert(std::is_convertible_v<E2, E>, "E2 must be convertible to E"); MOZ_ASSERT(isErr()); } Result(const Result&) = delete; Result(Result&&) = default; Result& operator=(const Result&) = delete; Result& operator=(Result&&) = default; /** True if this Result is a success result. */ constexpr bool isOk() const { return mImpl.isOk(); } /** True if this Result is an error result. */ constexpr bool isErr() const { return !mImpl.isOk(); } /** Take the success value from this Result, which must be a success result. */ constexpr V unwrap() { MOZ_ASSERT(isOk()); return mImpl.unwrap(); } /** * Take the success value from this Result, which must be a success result. * If it is an error result, then return the aValue. */ constexpr V unwrapOr(V aValue) { return MOZ_LIKELY(isOk()) ? mImpl.unwrap() : std::move(aValue); } /** Take the error value from this Result, which must be an error result. */ constexpr E unwrapErr() { MOZ_ASSERT(isErr()); return mImpl.unwrapErr(); } /** Used only for GC tracing. If used in Rooted<Result<...>>, V must have a * GCPolicy for tracing it. */ constexpr void updateAfterTracing(V&& aValue) { mImpl.updateAfterTracing(std::move(aValue)); } /** Used only for GC tracing. If used in Rooted<Result<...>>, E must have a * GCPolicy for tracing it. */ constexpr void updateErrorAfterTracing(E&& aErrorValue) { mImpl.updateErrorAfterTracing(std::move(aErrorValue)); } /** See the success value from this Result, which must be a success result. */ constexpr decltype(auto) inspect() const { static_assert(!std::is_reference_v< std::invoke_result_t<decltype(&Impl::inspect), Impl>> || std::is_const_v<std::remove_reference_t< std::invoke_result_t<decltype(&Impl::inspect), Impl>>>); MOZ_ASSERT(isOk()); return mImpl.inspect(); } /** See the error value from this Result, which must be an error result. */ constexpr decltype(auto) inspectErr() const { static_assert( !std::is_reference_v< std::invoke_result_t<decltype(&Impl::inspectErr), Impl>> || std::is_const_v<std::remove_reference_t< std::invoke_result_t<decltype(&Impl::inspectErr), Impl>>>); MOZ_ASSERT(isErr()); return mImpl.inspectErr(); } /** Propagate the error value from this Result, which must be an error result. * * This can be used to propagate an error from a function call to the caller * with a different value type, but the same error type: * * Result<T1, E> Func1() { * Result<T2, E> res = Func2(); * if (res.isErr()) { return res.propagateErr(); } * } */ constexpr GenericErrorResult<E> propagateErr() { MOZ_ASSERT(isErr()); return GenericErrorResult<E>{mImpl.unwrapErr(), ErrorPropagationTag{}}; } /** * Map a function V -> V2 over this result's success variant. If this result * is an error, do not invoke the function and propagate the error. * * Mapping over success values invokes the function to produce a new success * value: * * // Map Result<int, E> to another Result<int, E> * Result<int, E> res(5); * Result<int, E> res2 = res.map([](int x) { return x * x; }); * MOZ_ASSERT(res.isOk()); * MOZ_ASSERT(res2.unwrap() == 25); * * // Map Result<const char*, E> to Result<size_t, E> * Result<const char*, E> res("hello, map!"); * Result<size_t, E> res2 = res.map(strlen); * MOZ_ASSERT(res.isOk()); * MOZ_ASSERT(res2.unwrap() == 11); * * Mapping over an error does not invoke the function and propagates the * error: * * Result<V, int> res(5); * MOZ_ASSERT(res.isErr()); * Result<V2, int> res2 = res.map([](V v) { ... }); * MOZ_ASSERT(res2.isErr()); * MOZ_ASSERT(res2.unwrapErr() == 5); */ template <typename F> constexpr auto map(F f) -> Result<std::invoke_result_t<F, V>, E> { using RetResult = Result<std::invoke_result_t<F, V>, E>; return MOZ_LIKELY(isOk()) ? RetResult(f(unwrap())) : RetResult(unwrapErr()); } /** * Map a function E -> E2 over this result's error variant. If this result is * a success, do not invoke the function and move the success over. * * Mapping over error values invokes the function to produce a new error * value: * * // Map Result<V, int> to another Result<V, int> * Result<V, int> res(5); * Result<V, int> res2 = res.mapErr([](int x) { return x * x; }); * MOZ_ASSERT(res2.isErr()); * MOZ_ASSERT(res2.unwrapErr() == 25); * * // Map Result<V, const char*> to Result<V, size_t> * Result<V, const char*> res("hello, mapErr!"); * Result<V, size_t> res2 = res.mapErr(strlen); * MOZ_ASSERT(res2.isErr()); * MOZ_ASSERT(res2.unwrapErr() == 14); * * Mapping over a success does not invoke the function and moves the success: * * Result<int, E> res(5); * MOZ_ASSERT(res.isOk()); * Result<int, E2> res2 = res.mapErr([](E e) { ... }); * MOZ_ASSERT(res2.isOk()); * MOZ_ASSERT(res2.unwrap() == 5); */ template <typename F> constexpr auto mapErr(F f) { using RetResult = Result<V, std::invoke_result_t<F, E>>; return MOZ_UNLIKELY(isErr()) ? RetResult(f(unwrapErr())) : RetResult(unwrap()); } /** * Map a function E -> Result<V, E2> over this result's error variant. If * this result is a success, do not invoke the function and move the success * over. * * `orElse`ing over error values invokes the function to produce a new * result: * * // `orElse` Result<V, int> error variant to another Result<V, int> * // error variant or Result<V, int> success variant * auto orElse = [](int x) -> Result<V, int> { * if (x != 6) { * return Err(x * x); * } * return V(...); * }; * * Result<V, int> res(5); * auto res2 = res.orElse(orElse); * MOZ_ASSERT(res2.isErr()); * MOZ_ASSERT(res2.unwrapErr() == 25); * * Result<V, int> res3(6); * auto res4 = res3.orElse(orElse); * MOZ_ASSERT(res4.isOk()); * MOZ_ASSERT(res4.unwrap() == ...); * * // `orElse` Result<V, const char*> error variant to Result<V, size_t> * // error variant or Result<V, size_t> success variant * auto orElse = [](const char* s) -> Result<V, size_t> { * if (strcmp(s, "foo")) { * return Err(strlen(s)); * } * return V(...); * }; * * Result<V, const char*> res("hello, orElse!"); * auto res2 = res.orElse(orElse); * MOZ_ASSERT(res2.isErr()); * MOZ_ASSERT(res2.unwrapErr() == 14); * * Result<V, const char*> res3("foo"); * auto res4 = ress.orElse(orElse); * MOZ_ASSERT(res4.isOk()); * MOZ_ASSERT(res4.unwrap() == ...); * * `orElse`ing over a success does not invoke the function and moves the * success: * * Result<int, E> res(5); * MOZ_ASSERT(res.isOk()); * Result<int, E2> res2 = res.orElse([](E e) { ... }); * MOZ_ASSERT(res2.isOk()); * MOZ_ASSERT(res2.unwrap() == 5); */ template <typename F> auto orElse(F f) -> Result<V, typename std::invoke_result_t<F, E>::err_type> { return MOZ_UNLIKELY(isErr()) ? f(unwrapErr()) : unwrap(); } /** * Given a function V -> Result<V2, E>, apply it to this result's success * value and return its result. If this result is an error value, it is * propagated. * * This is sometimes called "flatMap" or ">>=" in other contexts. * * `andThen`ing over success values invokes the function to produce a new * result: * * Result<const char*, Error> res("hello, andThen!"); * Result<HtmlFreeString, Error> res2 = res.andThen([](const char* s) { * return containsHtmlTag(s) * ? Result<HtmlFreeString, Error>(Error("Invalid: contains HTML")) * : Result<HtmlFreeString, Error>(HtmlFreeString(s)); * } * }); * MOZ_ASSERT(res2.isOk()); * MOZ_ASSERT(res2.unwrap() == HtmlFreeString("hello, andThen!"); * * `andThen`ing over error results does not invoke the function, and just * propagates the error result: * * Result<int, const char*> res("some error"); * auto res2 = res.andThen([](int x) { ... }); * MOZ_ASSERT(res2.isErr()); * MOZ_ASSERT(res.unwrapErr() == res2.unwrapErr()); */ template <typename F, typename = std::enable_if_t<detail::IsResult< std::invoke_result_t<F, V&&>>::value>> constexpr auto andThen(F f) -> std::invoke_result_t<F, V&&> { return MOZ_LIKELY(isOk()) ? f(unwrap()) : propagateErr(); } }; /** * A type that auto-converts to an error Result. This is like a Result without * a success type. It's the best return type for functions that always return * an error--functions designed to build and populate error objects. It's also * useful in error-handling macros; see MOZ_TRY for an example. */ template <typename E> class [[nodiscard]] GenericErrorResult { E mErrorValue; template <typename V, typename E2> friend class Result; public: explicit constexpr GenericErrorResult(const E& aErrorValue) : mErrorValue(aErrorValue) {} explicit constexpr GenericErrorResult(E&& aErrorValue) : mErrorValue(std::move(aErrorValue)) {} constexpr GenericErrorResult(const E& aErrorValue, const ErrorPropagationTag&) : GenericErrorResult(aErrorValue) {} constexpr GenericErrorResult(E&& aErrorValue, const ErrorPropagationTag&) : GenericErrorResult(std::move(aErrorValue)) {} }; template <typename E> inline constexpr auto Err(E&& aErrorValue) { return GenericErrorResult<std::decay_t<E>>(std::forward<E>(aErrorValue)); } } // namespace mozilla #endif // mozilla_Result_h