[PATCH] D105014: added some example code for llvm::Expected<T>

[Christian Kühnel via Phabricator via llvm-commits]

This revision was automatically updated to reflect the committed changes.
Closed by commit rGcd8f979fe48c: added some example code for llvm::Expected<T> (authored by kuhnel).

Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D105014/new/

https://reviews.llvm.org/D105014

Files:
  llvm/include/llvm/Support/Error.h
  llvm/include/llvm/Testing/Support/Error.h


Index: llvm/include/llvm/Testing/Support/Error.h
===================================================================
--- llvm/include/llvm/Testing/Support/Error.h
+++ llvm/include/llvm/Testing/Support/Error.h
@@ -165,6 +165,27 @@
 #define ASSERT_THAT_ERROR(Err, Matcher)                                        \
   ASSERT_THAT(llvm::detail::TakeError(Err), Matcher)
 
+/// Helper macro for checking the result of an 'Expected<T>'
+///
+///   @code{.cpp}
+///     // function to be tested
+///     Expected<int> myDivide(int A, int B);
+///
+///     TEST(myDivideTests, GoodAndBad) {
+///       // test good case
+///       // if you only care about success or failure:
+///       EXPECT_THAT_EXPECTED(myDivide(10, 5), Succeeded());
+///       // if you also care about the value:
+///       EXPECT_THAT_EXPECTED(myDivide(10, 5), HasValue(2));
+///
+///       // test the error case
+///       EXPECT_THAT_EXPECTED(myDivide(10, 0), Failed());
+///       // also check the error message
+///       EXPECT_THAT_EXPECTED(myDivide(10, 0),
+///           FailedWithMessage("B must not be zero!"));
+///     }
+///   @endcode
+
 #define EXPECT_THAT_EXPECTED(Err, Matcher)                                     \
   EXPECT_THAT(llvm::detail::TakeExpected(Err), Matcher)
 #define ASSERT_THAT_EXPECTED(Err, Matcher)                                     \
Index: llvm/include/llvm/Support/Error.h
===================================================================
--- llvm/include/llvm/Support/Error.h
+++ llvm/include/llvm/Support/Error.h
@@ -436,6 +436,39 @@
 /// Error cannot be copied, this class replaces getError() with
 /// takeError(). It also adds an bool errorIsA<ErrT>() method for testing the
 /// error class type.
+///
+/// Example usage of 'Expected<T>' as a function return type:
+///
+///   @code{.cpp}
+///     Expected<int> myDivide(int A, int B) {
+///       if (B == 0) {
+///         // return an Error
+///         return createStringError(inconvertibleErrorCode(),
+///                                  "B must not be zero!");
+///       }
+///       // return an integer
+///       return A / B;
+///     }
+///   @endcode
+///
+///   Checking the results of to a function returning 'Expected<T>':
+///   @code{.cpp}
+///     if (auto E = Result.takeError()) {
+///       // We must consume the error. Typically one of:
+///       // - return the error to our caller
+///       // - toString(), when logging
+///       // - consumeError(), to silently swallow the error
+///       // - handleErrors(), to distinguish error types
+///       errs() << "Problem with division " << toString(std::move(E)) << "\n";
+///       return;
+///     }
+///     // use the result
+///     outs() << "The answer is " << *Result << "\n";
+///   @endcode
+///
+///  For unit-testing a function returning an 'Expceted<T>', see the
+///  'EXPECT_THAT_EXPECTED' macros in llvm/Testing/Support/Error.h
+
 template <class T> class LLVM_NODISCARD Expected {
   template <class T1> friend class ExpectedAsOutParameter;
   template <class OtherT> friend class Expected;


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D105014.355813.patch
Type: text/x-patch
Size: 3058 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20210701/e9c04756/attachment.bin>