### Install Project with CMake

Source: https://www.boost.org/doc/libs/latest/libs/outcome/doc/html/build.html

Build the project and install it using CMake. This makes the project discoverable via `find_package()` in other CMake projects.

```bash
mkdir build
cd build
cmake ..
cmake --build .
sudo cmake --build . --target install

```

--------------------------------

### Install Outcome with vcpkg

Source: https://www.boost.org/doc/libs/latest/libs/outcome/doc/html/build.html

Install the Outcome library using the vcpkg package manager. This method is cross-platform.

```bash
vcpkg install outcome
```

--------------------------------

### Program Output Example

Source: https://www.boost.org/doc/libs/latest/libs/outcome/doc/html/experimental/outcome.html

This is the expected output when running the `main` function, showing the error domain, message, and a semantic comparison result.

```text
Returned error has a code domain of 'file i/o error domain', a message of 'No such file or directory (c:\\users\\ned\\documents\\boostish\\outcome\\doc\\src\\snippets\\experimental_status_code.cpp:195)'

And semantically comparing it to 'errc::no_such_file_or_directory' = 1
```

--------------------------------

### Build and Run Unit Tests with CMake

Source: https://www.boost.org/doc/libs/latest/libs/outcome/doc/html/build.html

Standard procedure to build the project and run its unit tests using CMake. Ensure cmake 3.3 or later is installed.

```bash
mkdir build
cd build
cmake ..
cmake --build .
ctest

```

--------------------------------

### Example Usage of Constrained Template Macros

Source: https://www.boost.org/doc/libs/latest/libs/outcome/doc/html/reference/macros/template.html

Demonstrates how to use `BOOST_OUTCOME_TEMPLATE` and `BOOST_OUTCOME_TREQUIRES` to define a constructor with specific template requirements. This example shows how to check for valid expression syntax and boolean predicates.

```cpp
BOOST_OUTCOME_TEMPLATE(class ErrorCondEnum)
  BOOST_OUTCOME_TREQUIRES(
    // If this is a valid expression
    BOOST_OUTCOME_TEXPR(error_type(make_error_code(ErrorCondEnum()))),
    // If this predicate is true
    BOOST_OUTCOME_TPRED(predicate::template enable_error_condition_converting_constructor<ErrorCondEnum>)
    // Any additional requirements follow here ...
  )
  constexpr basic_result(ErrorCondEnum &&t, error_condition_converting_constructor_tag /*unused*/ = {});

```

--------------------------------

### Example of eager<int> usage

Source: https://www.boost.org/doc/libs/latest/libs/outcome/doc/html/reference/types/awaitables/eager.html

Demonstrates how to define and use an `eager<int>` coroutine. The result is obtained immediately as if it were a non-coroutine function.

```cpp
eager<int> func(int x)
{
  co_return x + 1;
}
...
// Executes like a non-coroutine function i.e. r is immediately set to 6.
int r = co_await func(5);

```

--------------------------------

### Example of C-style error code handling

Source: https://www.boost.org/doc/libs/latest/libs/outcome/doc/html/motivation/error_codes.html

This C function demonstrates returning integer error codes to indicate success (0) or failure. It shows how to check return values from lower-level functions and return custom error codes.

```cpp
int readInt(const char * filename, int& val)
{
  FILE* fd;
  int r = openFile(filename, /*out*/ fd);
  if (r != 0)
    return r; // return whatever error openFile() returned

  r = readInt(fd, /*out*/ val);
  if (r != 0)
    return READERRC_NOINT; // my error code

  return 0;   // success
}

```

--------------------------------

### BOOST_OUTCOME_TRY with lvalue/xvalue expression

Source: https://www.boost.org/doc/libs/latest/libs/outcome/doc/html/changelog.html

Demonstrates a scenario where BOOST_OUTCOME_TRY can lead to undefined behavior due to premature destruction of a result object when dealing with lvalue or xvalue expressions. This example illustrates the problem that was fixed in later versions.

```cpp
outcome::result<Foo>    get_foo();
outcome::result<Foo>    filter1(outcome::result<Foo> &&);
outcome::result<Foo> && filter2(outcome::result<Foo> &&);

// This works fine, and always has
BOOST_OUTCOME_TRY(auto v, filter1(get_foo()))

// This causes UB due to result<Foo> being destructed before move of value into v
BOOST_OUTCOME_TRY(auto v, filter2(get_foo()))
```

--------------------------------

### C++ Result Type Example with Error Handling

Source: https://www.boost.org/doc/libs/latest/libs/outcome/doc/html/experimental/c-api/from-c/use.html

Demonstrates using the Result type in C++ for a function that returns a positive integer or an error code. Includes checking for errors and specific error codes.

```cpp
result positive_only(int x)
{
  if(x < 0)
  {
    return FAILURE(c_enum_bad_argument);
  }
  return SUCCESS(x);
}

bool test(int x)
{
  result r = positive_only(x);
  if(BOOST_OUTCOME_C_RESULT_HAS_ERROR(r))
  {
    if(outcome_status_code_equal_generic(&r.error, EINVAL))
    {
      fprintf(stderr, "Positive numbers only!\n");
      return false;
    }
  }
  return true;
}


```

--------------------------------

### Build and Run Unit Tests with CMake (Configured)

Source: https://www.boost.org/doc/libs/latest/libs/outcome/doc/html/build.html

Build and test the project with a specific configuration (e.g., Release) using CMake. This is necessary for generators like Visual Studio or Xcode.

```bash
mkdir build
cd build
cmake ..
cmake --build . --config Release
ctest -C Release

```

--------------------------------

### Download Single Header File (fetch)

Source: https://www.boost.org/doc/libs/latest/libs/outcome/doc/html/build.html

Use fetch to download the single-header file for Outcome on BSD systems.

```bash
fetch https://github.com/ned14/outcome/raw/master/single-header/outcome.hpp
```

--------------------------------

### TRY Greedy Implicit Conversion Example

Source: https://www.boost.org/doc/libs/latest/libs/outcome/doc/html/tutorial/essential/result/try_greedy.html

Illustrates how BOOST_OUTCOME_TRY can implicitly convert between result types where direct assignment would fail. This highlights the 'greedier' nature of TRY.

```cpp
outcome::result<int, std::error_code> test(outcome::result<int, std::errc> r)
{
    BOOST_OUTCOME_TRY(r);    // no explicit conversion needed
    return r.value();
}

```

--------------------------------

### Direct file_handle Construction with outcome::result

Source: https://www.boost.org/doc/libs/latest/libs/outcome/doc/html/tutorial/advanced/constructors/metaprogrammg1.html

Demonstrates the direct construction of a `file_handle` within an `outcome::result`. This approach requires explicit error checking after construction.

```cpp
outcome::result<file_handle> fh1 = file_handle::file("hello" /*, file_handle::mode::read */);
  if(!fh1)
  {
    std::cerr << "Opening file 'hello' failed with " << fh1.error().message() << std::endl;
  }

```

--------------------------------

### Add CMake Hunter Packages

Source: https://www.boost.org/doc/libs/latest/libs/outcome/doc/html/build.html

Add quickcpplib and outcome as CMake Hunter packages in your CMakeLists.txt.

```cmake
hunter_add_package(quickcpplib)
find_package(quickcpplib CONFIG REQUIRED)
hunter_add_package(outcome)
find_package(outcome CONFIG REQUIRED)
```

--------------------------------

### Using ForeignExpected with BOOST_OUTCOME_TRY

Source: https://www.boost.org/doc/libs/latest/libs/outcome/doc/html/recipes/foreign-try.html

Demonstrates how `BOOST_OUTCOME_TRY` can be used with a foreign type like `ForeignExpected`. This example shows calling an old function returning `ForeignExpected` from new code using Outcome.

```cpp
ForeignExpected<int> old_code(int a)  // old code
{
  if(0 == a)
    return kBadValue;
  return a;
}

outcome::result<int> new_code(int a)  // new code
{
  BOOST_OUTCOME_TRY(auto x, old_code(a));
  return x;
}

```

--------------------------------

### Main Function with Outcome Handling

Source: https://www.boost.org/doc/libs/latest/libs/outcome/doc/html/experimental/outcome.html

The main function demonstrates calling `open_resource` and handling the `result`. It prints a success message or details about the returned error, including its domain and message.

```cpp
int main(void)
{
  result<void> r = open_resource();
  if(r)
    printf("Success!\n");
  else
  {
    auto e = std::move(r).error();
    // A quick demonstration that the indirection works as indicated
    printf("Returned error has a code domain of '%s', a message of '%s'\n", e.domain().name().c_str(),
           e.message().c_str());
    printf("\nAnd semantically comparing it to 'errc::no_such_file_or_directory' = %d\n",
           e == outcome_e::errc::no_such_file_or_directory);
  }
}
```

--------------------------------

### Coroutine TRY operation example

Source: https://www.boost.org/doc/libs/latest/libs/outcome/doc/html/tutorial/essential/coroutines/try.html

Demonstrates how to use BOOST_OUTCOME_CO_TRY within a C++ coroutine to handle potential errors from the `convert` function. If `convert` returns an error, the coroutine will exit early using `co_return`.

```cpp
eager<result<std::string>> to_string(int x)
{
  if(x >= 0)
  {
    BOOST_OUTCOME_CO_TRY(convert(x));
  }
  co_return "out of range";
}

```

--------------------------------

### Constructing file_handle with make<file_handle>

Source: https://www.boost.org/doc/libs/latest/libs/outcome/doc/html/tutorial/advanced/constructors/metaprogrammg1.html

Illustrates using the `make<file_handle>` type for constructing a `file_handle` within an `outcome::result`. This metaprogramming technique allows for a two-stage invocation, first preparing the construction arguments and then executing the construction.

```cpp
outcome::result<file_handle> fh2 = make<file_handle>{"hello" /*, file_handle::mode::read */}();
  if(!fh2)
  {
    std::cerr << "Opening file 'hello' failed with " << fh2.error().message() << std::endl;
  }

```

--------------------------------

### Download Single Header File (wget)

Source: https://www.boost.org/doc/libs/latest/libs/outcome/doc/html/build.html

Use wget to download the single-header file for Outcome on Linux systems.

```bash
wget https://github.com/ned14/outcome/raw/master/single-header/outcome.hpp
```

--------------------------------

### Hook result construction for Boost.Outcome (pre-v2.2)

Source: https://www.boost.org/doc/libs/latest/libs/outcome/doc/html/tutorial/advanced/hooks/hook_result.html

For Outcome versions before v2.2, insert a specially named free function into a namespace searched by ADL to hook result construction. This example shows how to capture a stack backtrace when a result is constructed with an error.

```cpp
namespace error_code_extended
{
  // Specialise the result construction hook for our localised result
  // We hook any non-copy, non-move, non-inplace construction, capturing a stack backtrace
  // if the result is errored.
  template <class T, class U> inline void hook_result_construction(result<T> *res, U && /*unused*/) noexcept
  {
    if(res->has_error())
    {
      // Grab the next extended info slot in the TLS
      extended_error_info &eei = mythreadlocaldata().next();

      // Write the index just grabbed into the spare uint16_t
      BOOST_OUTCOME_V2_NAMESPACE::hooks::set_spare_storage(res, mythreadlocaldata().current - 1);

      // Capture a backtrace into my claimed extended info slot in the TLS
      eei.items = ::backtrace(eei.backtrace.data(), eei.backtrace.size());
    }
  }
}

```

--------------------------------

### Construct result objects using helper functions

Source: https://www.boost.org/doc/libs/latest/libs/outcome/doc/html/tutorial/essential/result.html

Shows how to create successful or failed result objects using the `outcome::success` and `outcome::failure` helper functions. These functions provide a more concise way to initialize result objects.

```cpp
outcome::result<int> r = outcome::failure(ConversionErrc::EmptyString);
outcome::result<int> s = outcome::success(1);


```

--------------------------------

### httplib::get

Source: https://www.boost.org/doc/libs/latest/libs/outcome/doc/html/tutorial/advanced/interop/httplib.html

Performs a HTTP GET request to the specified URL. It returns the body of the response as a string on success. On failure, it returns a `httplib::failure` struct containing the status code and the failing URL. Catastrophic errors like memory allocation failures may result in C++ exceptions.

```APIDOC
## httplib::get

### Description
Performs a HTTP GET on the url, returning the body if successful, a failure with status_code if unsuccessful at the HTTP level, or a C++ exception throw if something catastrophic happened e.g. bad_alloc.

### Method
GET (conceptual, as this is a library function)

### Endpoint
Not applicable (library function)

### Parameters
#### Path Parameters
- **url** (std::string) - Required - The URL to fetch.

### Response
#### Success Response
- **std::string** - The body of the HTTP response.

#### Failure Response
- **httplib::failure** - Contains `status_code` and `url`.

### Error Handling
- **httplib::failure**: For HTTP-level errors (e.g., 404 Not Found).
- **std::exception**: For catastrophic errors (e.g., `std::bad_alloc`).
```

--------------------------------

### File Opening and Error Handling

Source: https://www.boost.org/doc/libs/latest/libs/outcome/doc/html/experimental/outcome.html

Demonstrates opening a file and returning either a file handle or a `file_io_error`. This snippet showcases basic result usage for I/O operations.

```cpp
result<file_handle, file_io_error> open_file(const char *path)  // models throws(file_io_error)
{
  file_handle ret(::fopen(path, "r"));
  if(ret)
    return ret;
  return file_io_error({errno, __LINE__, __FILE__});
}
```

--------------------------------

### Resource Opening with Error Retries

Source: https://www.boost.org/doc/libs/latest/libs/outcome/doc/html/experimental/outcome.html

Shows how to repeatedly attempt to open a file, handling specific errors like 'resource unavailable'. It returns an error if a different `file_io_error` occurs.

```cpp
result<void> open_resource()  // models throws(std::error)
{
  for(;;)
  {
    result<file_handle, file_io_error> r = open_file("some file");
    if(r)
      break;
    file_io_error e = r.error();
    if(e != outcome_e::errc::resource_unavailable_try_again)
    {
      // NOTE this implicitly converts from `file_io_error` to `error` via the
      // `make_status_code()` free function customisation point defined above.
      return e;
    }
  }
  // success continues here ...
  return outcome_e::success();
}
```

--------------------------------

### Usage of upgraded Filesystem copy_file

Source: https://www.boost.org/doc/libs/latest/libs/outcome/doc/html/tutorial/advanced/payload/copy_file3.html

Demonstrates both non-throwing and throwing use cases for the upgraded `copy_file` function. The non-throwing case checks the result for errors, while the throwing case attempts to observe the value, triggering the custom `outcome_throw_as_system_error_with_payload` to throw a `filesystem_error`.

```cpp
  // Non-throwing use case
  auto o = filesystem2::copy_file("dontexist", "alsodontexist");
  if(!o)
  {
    std::cerr << "Copy file failed with error " << o.error().ec.message()                   //
              << " (path1 = " << o.error().path1 << ", path2 = " << o.error().path2 << ")"  //
              << std::endl;
  }

  // Throwing use case
  try
  {
    // Try to observe the successful value, thus triggering default actions which invokes
    // our outcome_throw_as_system_error_with_payload() above which then throws filesystem_error
    // exactly like the Filesystem TS does for its throwing overload.
    filesystem2::copy_file("dontexist", "alsodontexist").value();
  }
  catch(const filesystem2::filesystem_error &e)
  {
    std::cerr << "Copy file failed with exception " << e.what()                 //
              << " (path1 = " << e.path1() << ", path2 = " << e.path2() << ")"  //
              << std::endl;
  }
  catch(const std::exception &e)
  {
    std::cerr << "Copy file failed with exception " << e.what()  //
              << std::endl;
  }

```

--------------------------------

### Implementation of print_half

Source: https://www.boost.org/doc/libs/latest/libs/outcome/doc/html/tutorial/essential/result/inspecting.html

Implements the `print_half` function, demonstrating how to check for success, extract values, handle specific errors, and propagate failures using `BOOST_OUTCOME_TRY`.

```cpp
outcome::result<void> print_half(const std::string& text)
{
  if (outcome::result<int> r = convert(text))         // #1
  {
    std::cout << (r.value() / 2) << std::endl;        // #2
  }
  else
  {
    if (r.error() == ConversionErrc::TooLong)         // #3
    {
      BOOST_OUTCOME_TRY(auto i, BigInt::fromString(text));  // #4
      std::cout << i.half() << std::endl;
    }
    else
    {
      return r.as_failure();                          // #5
    }
  }
  return outcome::success();                          // #6
}

```

--------------------------------

### Add Git Submodules for CMake Hunter

Source: https://www.boost.org/doc/libs/latest/libs/outcome/doc/html/build.html

Add quickcpplib and outcome as Git submodules to your project directory for use with CMake Hunter.

```bash
cd yourthirdpartyrepodir
git submodule add https://github.com/ned14/quickcpplib
git submodule add https://github.com/ned14/outcome
cd ..
git submodule update --init --recursive
```

--------------------------------

### Basic generator usage

Source: https://www.boost.org/doc/libs/latest/libs/outcome/doc/html/reference/types/awaitables/generator.html

Demonstrates how to define and use a coroutine generator. The generator is created, suspended, and then values are retrieved in a loop until it is exhausted.

```cpp
generator<int> func(int x)
{
  while(x >= 0)
  {
    co_yield x--;
  }
}


auto f = func(5);
while(f)
{
  int r = f();
  ...
```

--------------------------------

### Creating C Result Instances

Source: https://www.boost.org/doc/libs/latest/libs/outcome/doc/html/experimental/c-api/from-c/system_code.html

Macros for creating C status_result instances with success, POSIX error, or system error.

```APIDOC
## Creating a Successful C Result

### Description
Invokes an extern function to create a `status_result` with a successful value of type `T`. Requires a C++ counterpart linked into the final binary.

### Macro
`BOOST_OUTCOME_C_MAKE_RESULT_SYSTEM_SUCCESS(ident, expr)`

## Creating a POSIX Error C Result

### Description
Invokes an extern function to create a `status_result` representing a POSIX `errno`. Requires a C++ counterpart linked into the final binary.

### Macro
`BOOST_OUTCOME_C_MAKE_RESULT_SYSTEM_FAILURE_POSIX(ident, expr)`

## Creating a System Error C Result

### Description
Invokes an extern function to create a `status_result` representing a system error. On POSIX systems, this is `posix_code`; on Windows, it's `win32_code`. Requires a C++ counterpart linked into the final binary.

### Macro
`BOOST_OUTCOME_C_MAKE_RESULT_SYSTEM_FAILURE_SYSTEM(ident, expr)`
```

--------------------------------

### Specialization of make<file_handle>

Source: https://www.boost.org/doc/libs/latest/libs/outcome/doc/html/tutorial/advanced/constructors/metaprogrammg2.html

Specializes `make<T>` for `file_handle`, including member variables for path and mode, and an operator() that returns a `file_handle` instance. Demonstrates default member initializers for arguments.

```cpp
template <> struct make<file_handle>
{
  file_handle::path_type _path;
  file_handle::mode _mode{file_handle::mode::read};
  // Any other args, default initialised if necessary, follow here ...

  outcome::result<file_handle> operator()() const noexcept  //
  {
    return file_handle::file(std::move(_path));
  }
};

```

--------------------------------

### Layer 1 Functions: Throwing and Result

Source: https://www.boost.org/doc/libs/latest/libs/outcome/doc/html/tutorial/essential/outcome.html

Illustrates two functions in Layer 1: one that throws exceptions on failure and another that returns a `result<>`.

```cpp
auto f() -> int;  // throws on failure
auto g() noexcept -> outcome::result<int>;

```

--------------------------------

### `static void on_result_move_construction(T *, U &&) noexcept`

Source: https://www.boost.org/doc/libs/latest/libs/outcome/doc/html/reference/policies/base/on_result_move_construction.html

This is a constructor hook for `basic_result<T, E, NoValuePolicy>`, typically called by the converting move constructors of `basic_result`. It is not invoked by the standard move constructor. Refer to the documentation for each constructor to identify the specific hook it uses.

```APIDOC
## `static void on_result_move_construction(T *, U &&) noexcept`

### Description
One of the constructor hooks for `basic_result<T, E, NoValuePolicy>`, generally invoked by the converting move constructors of `basic_result` (NOT the standard move constructor). See each constructor’s documentation to see which specific hook it invokes.

### Requires
Always available.

### Guarantees
Never throws an exception.
```

--------------------------------

### Templated Free Function with Tagged Overloading

Source: https://www.boost.org/doc/libs/latest/libs/outcome/doc/html/tutorial/advanced/constructors/metaprogrammg3.html

Demonstrates how to implement a templated free function using tagged overloading for object construction, as an alternative to the two-stage pattern.

```cpp
template<class... Args>
inline outcome::result<file_handle> make(std::in_place_type_t<file_handle>, Args&& ... args)
{
  return file_handle::file(std::forward<Args>(args)...);
}
...
// Now you must always write this:
make(std::in_place_type<file_handle>, "hello");

```

--------------------------------

### BOOST_OUTCOME_TRYX in conditional initialization

Source: https://www.boost.org/doc/libs/latest/libs/outcome/doc/html/tutorial/essential/result/try.html

Demonstrates using `BOOST_OUTCOME_TRYX` within an `if` statement's initialization for concise error checking.

```cpp
if (int i = BOOST_OUTCOME_TRYX(BigInt::fromString(text)))
  use_a_non_zero_int(i);
```

--------------------------------

### Using Custom Error Codes

Source: https://www.boost.org/doc/libs/latest/libs/outcome/doc/html/motivation/std_error_code.html

Demonstrates how to create an std::error_code object from a custom enumeration value and assert its equality.

```cpp
std::error_code ec = ConvertErrc::EmptyString;
assert(ec == ConvertErrc::EmptyString);

```

--------------------------------

### Construct result objects using in_place_type

Source: https://www.boost.org/doc/libs/latest/libs/outcome/doc/html/tutorial/essential/result.html

Demonstrates constructing result objects using tagged constructors with `in_place_type`. This is used when implicit conversion is disabled due to potential ambiguity between the success type and the error type.

```cpp
outcome::result<int> r {outcome::in_place_type<std::error_code>, ConversionErrc::EmptyString};
outcome::result<int> s {outcome::in_place_type<int>, 1};


```

--------------------------------

### Calling C FFI function and converting result

Source: https://www.boost.org/doc/libs/latest/libs/outcome/doc/html/recipes/rust.html

Demonstrates how to call an external C FFI function that returns an `outcome_c_result` and convert it into a Rust `Result` using the `to_result` function. It also shows how to access the error message from the resulting Rust `Result`.

```rust
// Make a Rust Result equivalent to the Outcome Result
let res = to_result(unsafe { file_read(db, buffer, 256) });
// Asks Outcome for the message automatically
println!("Message: {}", res.err().unwrap());

```

--------------------------------

### Two-Stage Invocation Pattern

Source: https://www.boost.org/doc/libs/latest/libs/outcome/doc/html/tutorial/advanced/constructors/metaprogrammg3.html

Illustrates the standard two-stage invocation pattern used in Boost.Outcome.

```cpp
make<file_handle>{"hello"}();

```

--------------------------------

### Legacy Hook Usage (Emulation)

Source: https://www.boost.org/doc/libs/latest/libs/outcome/doc/html/reference/functions/hooks/hook_outcome_construction2.html

To enable emulation of the removed hook_outcome_construction, set BOOST_OUTCOME_ENABLE_LEGACY_SUPPORT_FOR to a value less than 220. Use on_outcome_construction in new code.

```c++
#define BOOST_OUTCOME_ENABLE_LEGACY_SUPPORT_FOR 210 // Example value
```

--------------------------------

### Call C++ Function and Handle Result in C

Source: https://www.boost.org/doc/libs/latest/libs/outcome/doc/html/experimental/c-api/from-cxx/example2.html

Demonstrates how to call a C++ function from C using its C-compatible declaration and handle the returned Boost.Outcome result. It checks for success, POSIX errors, and other unknown errors.

```c
void print(int v)
{
  char buffer[4];
  CXX_RESULT_SYSTEM(to_string_rettype) res;

  res = _Z9to_stringPcmi(buffer, sizeof(buffer), v);
  if(CXX_RESULT_HAS_VALUE(res))
  {
    printf("to_string(%d) fills buffer with '%s' of %zu characters\n", v, buffer, res.value);
    return;
  }
  // Is the error returned in the POSIX domain and thus an errno?
  if(CXX_RESULT_ERROR_IS_ERRNO(res))
  {
    fprintf(stderr, "to_string(%d) failed with error code %d (%s)\n", v, (int) res.error.value, strerror((int) res.error.value));
    return;
  }
  fprintf(stderr, "to_string(%d) failed with unknown error code %lld\n", v, (long long) res.error.value);
}

int main(void)
{
  print(9);
  print(99);
  print(999);
  print(9999);
  return 0;
}
```

--------------------------------

### explicit basic_outcome(in_place_type_t<value_type_if_enabled>, Args ...)

Source: https://www.boost.org/doc/libs/latest/libs/outcome/doc/html/reference/types/basic_outcome/explicit_inplace_value_constructor.html

This constructor constructs the outcome's value in place. It calls `void on_outcome_in_place_construction(T *, in_place_type_t<U>, Args &&...) noexcept` with `this`, `in_place_type<value_type>` and `Args ...`.

```APIDOC
## explicit basic_outcome(in_place_type_t<value_type_if_enabled>, Args ...)

### Description
Explicit inplace value constructor. Calls `void on_outcome_in_place_construction(T *, in_place_type_t<U>, Args &&...) noexcept` with `this`, `in_place_type<value_type>` and `Args ...`.

### Requires
`predicate::enable_inplace_value_constructor<Args ...>` is true.

### Complexity
Same as for the `value_type` constructor which accepts `Args ...`. Constexpr, triviality and noexcept of underlying operations is propagated.

### Guarantees
If an exception is thrown during the operation, the state of the Args is left indeterminate.
```

--------------------------------

### Version Macros

Source: https://www.boost.org/doc/libs/latest/libs/outcome/doc/html/reference/macros/version.html

These macros define the versioning information for the Boost.Outcome library, used for CMake and DLL version stamping, and managing unstable releases and namespace configurations.

```APIDOC
## Version Macros

These macros are part of the Boost.Outcome library and are used for versioning and namespace configuration. They are not overridable.

### Header
`<boost/outcome/config.hpp>`

### Macros

*   **`BOOST_OUTCOME_VERSION_MAJOR <number>`**
    Major version for cmake and DLL version stamping.

*   **`BOOST_OUTCOME_VERSION_MINOR <number>`**
    Minor version for cmake and DLL version stamping.

*   **`BOOST_OUTCOME_VERSION_PATCH <number>`**
    Patch version for cmake and DLL version stamping.

*   **`BOOST_OUTCOME_VERSION_REVISION <number>`**
    Revision version for cmake and DLL version stamping.

*   **`BOOST_OUTCOME_UNSTABLE_VERSION <number>`**
    Defined between stable releases of Outcome. It means the inline namespace will be permuted per-commit to ensure ABI uniqueness such that multiple versions of Outcome in a single process space cannot collide.

*   **`BOOST_OUTCOME_V2 <tokens>`**
    The namespace configuration of this Outcome v2. Consists of a sequence of bracketed tokens later fused by the preprocessor into namespace and C++ module names.

*   **`BOOST_OUTCOME_V2_NAMESPACE <identifier>`**
    The Outcome namespace, which may be permuted per SHA commit. This is not fully qualified.

*   **`BOOST_OUTCOME_V2_NAMESPACE_BEGIN <keywords and identifiers>`**
    Expands into the appropriate namespace markup to enter the Outcome v2 namespace.

*   **`BOOST_OUTCOME_V2_NAMESPACE_EXPORT_BEGIN <keywords and identifiers>`**
    Expands into the appropriate namespace markup to enter the C++ module exported Outcome v2 namespace.

*   **`BOOST_OUTCOME_V2_NAMESPACE_END <keywords and identifiers>`**
    Expands into the appropriate namespace markup to exit the Outcome v2 namespace.
```

--------------------------------

### on_result_in_place_construction

Source: https://www.boost.org/doc/libs/latest/libs/outcome/doc/html/reference/policies/base/on_result_in_place_construction.html

This is a constructor hook for `basic_result<T, E, NoValuePolicy>`, typically invoked by the in-place constructors of `basic_result`. Refer to the documentation of each constructor to determine which specific hook it calls.

```APIDOC
## `static void on_result_in_place_construction(T *, in_place_type_t<U>, Args &&...) noexcept`

### Description
One of the constructor hooks for `basic_result<T, E, NoValuePolicy>`, generally invoked by the in-place constructors of `basic_result`. See each constructor’s documentation to see which specific hook it invokes.

### Requires
Always available.

### Guarantees
Never throws an exception.
```

--------------------------------

### Download Single Header File (curl)

Source: https://www.boost.org/doc/libs/latest/libs/outcome/doc/html/build.html

Use curl to download the single-header file for Outcome.

```bash
curl -O -J -L https://github.com/ned14/outcome/raw/master/single-header/outcome.hpp
```

--------------------------------

### basic_outcome(A1 &&, A2 &&, Args ...)

Source: https://www.boost.org/doc/libs/latest/libs/outcome/doc/html/reference/types/basic_outcome/implicit_inplace_value_error_exception_constructor.html

This constructor implicitly constructs a `basic_outcome` object. It delegates to an appropriate explicit inplace constructor based on the types of `A1`, `A2`, and `Args...`. This constructor requires that `predicate::enable_inplace_value_error_exception_constructor` is true.

```APIDOC
## `basic_outcome(A1 &&, A2 &&, Args ...)`

### Description
Implicit inplace value or error or exception constructor. Delegates to an appropriate explicit inplace constructor depending on input.

### Requires
`predicate::enable_inplace_value_error_exception_constructor` is true.

### Complexity
Same as for the `value_type` or `error_type` or `exception_type` constructor which accepts `A1, A2, Args ...`. Constexpr, triviality and noexcept of underlying operations is propagated.

### Guarantees
If an exception is thrown during the operation, the state of the Args is left indeterminate.
```

--------------------------------

### static void on_outcome_move_construction(T *, U &&) noexcept

Source: https://www.boost.org/doc/libs/latest/libs/outcome/doc/html/reference/policies/base/on_outcome_move_construction.html

This is a constructor hook for `basic_outcome<T, EC, EP, NoValuePolicy>`, typically called by the converting move constructors of `basic_outcome`. It is not invoked by the standard move constructor. Refer to the documentation of each specific constructor for details on which hook it uses.

```APIDOC
## `static void on_outcome_move_construction(T *, U &&) noexcept`

### Description
One of the constructor hooks for `basic_outcome<T, EC, EP, NoValuePolicy>`, generally invoked by the converting move constructors of `basic_outcome` (NOT the standard move constructor). See each constructor’s documentation to see which specific hook it invokes.

### Requires
Always available.

### Guarantees
Never throws an exception.
```

--------------------------------

### Basic Result Implicit Conversion Failure

Source: https://www.boost.org/doc/libs/latest/libs/outcome/doc/html/tutorial/essential/result/try_greedy.html

Demonstrates a scenario where direct assignment between two different result types fails due to implicit conversion limitations. Explicit construction is required.

```cpp
outcome::result<int, std::error_code> test(outcome::result<int, std::errc> r)
{
    return r;  // you need to use explicit construction here
    // i.e. return outcome::result<int>(r);
}

```

--------------------------------

### Filesystem TS copy_file() Throwing Overload

Source: https://www.boost.org/doc/libs/latest/libs/outcome/doc/html/tutorial/advanced/payload/copy_file.html

This is the throwing overload of the `copy_file` API. It throws a `filesystem::filesystem_error` on failure, which includes additional information about the source and destination paths.

```cpp
namespace filesystem
{
  /*! Copies the file at path `from` to path `to`.
  returns True if file was successfully copied.
  throws On failure throws `filesystem_error(ec.message(), from, to, ec)` with
  `ec` being the error code reported by the operating system.
  */
  bool copy_file(const path &from, const path &to);

  /*! Copies the file at path `from` to path `to`.
  returns True if file was successfully copied. If false, `ec` is written with
  the error code reported by the operating system.
  throws May throw an exception if there is some "catastrophic" failure
  e.g. failure to allocate memory.
  */
  bool copy_file(const path &from, const path &to, std::error_code &ec);
}

```

--------------------------------

### C Result System TRY Macro with Cleanup

Source: https://www.boost.org/doc/libs/latest/libs/outcome/doc/html/experimental/c-api/from-c/system_code.html

Similar to BOOST_OUTCOME_C_RESULT_SYSTEM_TRY, but executes 'cleanup' just before exiting the function if a failure is returned.

```c
#define BOOST_OUTCOME_C_RESULT_SYSTEM_TRY(cleanup, expr)
```