The Filesystem TS - Boost.Outcome documentation

# The Filesystem TS

Something which has long annoyed the purists in the C++ leadership is the problem of dual overloads in `error_code` capable standard library APIs.

Consider the `copy_file()` API from the Filesystem TS:

    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);
    }

View this code on Github

Before Outcome, the common design pattern was to provide throwing and non-throwing overloads of every API. As you can see above, the throwing API throws a `filesystem::filesystem_error` exception type which carries additional information, specifically two paths. These paths may refer to the files which were the source of any failure. However the non-throwing overload does not provide this additional information, which can make it more annoying to use the non-throwing overload sometimes.

What if we could replace these two overloads of every API in the Filesystem TS with a single API, and additionally have the non-throwing edition return the exact same additional information as the throwing edition?

Last revised: February 08, 2019 at 22:18:08 UTC