{"id":13598513,"url":"https://github.com/bitwizeshift/result","last_synced_at":"2025-04-09T17:22:30.443Z","repository":{"id":43577381,"uuid":"315811645","full_name":"bitwizeshift/result","owner":"bitwizeshift","description":"A lightweight C++11-compatible error-handling mechanism","archived":false,"fork":false,"pushed_at":"2022-09-23T00:54:52.000Z","size":2974,"stargazers_count":294,"open_issues_count":2,"forks_count":17,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-02T11:47:22.225Z","etag":null,"topics":["cpp11","cpp14","cpp17","error-handling","expected","header-only","modern-cpp","no-dependencies","proposals","result","result-type","zero-overhead"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bitwizeshift.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null},"funding":{"github":["bitwizeshift"],"custom":"https://www.buymeacoffee.com/dsq3XCcBE"}},"created_at":"2020-11-25T02:52:45.000Z","updated_at":"2025-04-01T09:03:26.000Z","dependencies_parsed_at":"2023-01-18T14:33:41.248Z","dependency_job_id":null,"html_url":"https://github.com/bitwizeshift/result","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitwizeshift%2Fresult","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitwizeshift%2Fresult/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitwizeshift%2Fresult/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitwizeshift%2Fresult/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bitwizeshift","download_url":"https://codeload.github.com/bitwizeshift/result/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248075252,"owners_count":21043554,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cpp11","cpp14","cpp17","error-handling","expected","header-only","modern-cpp","no-dependencies","proposals","result","result-type","zero-overhead"],"created_at":"2024-08-01T17:00:53.223Z","updated_at":"2025-04-09T17:22:30.424Z","avatar_url":"https://github.com/bitwizeshift.png","language":"C++","readme":"[![A Modern C++ Result Type](doc/feature-preview-banner.gif)](https://github.com/bitwizeshift/result/releases)\n\n[![Ubuntu Build Status](https://github.com/bitwizeshift/result/workflows/Ubuntu/badge.svg?branch=master)](https://github.com/bitwizeshift/result/actions?query=workflow%3AUbuntu)\n[![macOS Build Status](https://github.com/bitwizeshift/result/workflows/macOS/badge.svg?branch=master)](https://github.com/bitwizeshift/result/actions?query=workflow%3AmacOS)\n[![Windows Build Status](https://github.com/bitwizeshift/result/workflows/Windows/badge.svg?branch=master)](https://github.com/bitwizeshift/result/actions?query=workflow%3AWindows)\n[![Codacy Badge](https://app.codacy.com/project/badge/Grade/e163a49b3b2e4f1e953c32b7cbbb2f28)](https://www.codacy.com/gh/bitwizeshift/result/dashboard?utm_source=github.com\u0026amp;utm_medium=referral\u0026amp;utm_content=bitwizeshift/result\u0026amp;utm_campaign=Badge_Grade)\n[![Coverage Status](https://coveralls.io/repos/github/bitwizeshift/result/badge.svg?branch=master)](https://coveralls.io/github/bitwizeshift/result?branch=master)\n[![Github Issues](https://img.shields.io/github/issues/bitwizeshift/result.svg)](http://github.com/bitwizeshift/result/issues)\n\u003cbr\u003e\n[![Github Releases](https://img.shields.io/github/v/release/bitwizeshift/result.svg?include_prereleases)](https://github.com/bitwizeshift/result/releases)\n[![GitHub Sponsors](https://img.shields.io/badge/GitHub-Sponsors-ff69b4)](https://github.com/sponsors/bitwizeshift)\n\u003cbr\u003e\n[![Try online](https://img.shields.io/badge/try-online-blue.svg)](https://godbolt.org/z/qG11qK)\n\n**Result** is a modern, simple, and light-weight error-handling alternative to\nexceptions with a rich feature-set.\n\n## Features\n\n✔️ Offers a coherent, light-weight alternative to exceptions \\\n✔️ Compatible with \u003ckbd\u003eC++11\u003c/kbd\u003e (with more features in \u003ckbd\u003eC++14\u003c/kbd\u003e and \u003ckbd\u003eC++17\u003c/kbd\u003e) \\\n✔️ Single-header, **header-only** solution -- easily drops into any project \\\n✔️ Zero overhead abstractions -- don't pay for what you don't use. \\\n✔️ No dependencies \\\n✔️ Support for value-type, reference-type, and `void`-type values in `result` \\\n✔️ Monadic composition functions like `map`, `flat_map`, and `map_error` for\n      easy functional use \\\n✔️ Optional support to disable all exceptions and rename the `cpp` `namespace` \\\n✔️ [Comprehensively unit tested](https://coveralls.io/github/bitwizeshift/result?branch=master) for both static\n      behavior and runtime validation \\\n✔️ [Incurs minimal cost when optimized](https://godbolt.org/z/TsonT1), especially for trivial types\n\nCheck out the [tutorial](doc/tutorial.md) to see what other features **Result**\noffers.\n\nIf you're interested in how `cpp::result` deviates from `std::expected`\nproposals, please see [this page](doc/deviations-from-proposal.md).\n\n## Teaser\n\n```cpp\nenum class narrow_error{ none, loss_of_data };\n\ntemplate \u003ctypename To, typename From\u003e\nauto try_narrow(const From\u0026 from) noexcept -\u003e cpp::result\u003cTo,narrow_error\u003e\n{\n  const auto to = static_cast\u003cTo\u003e(from);\n\n  if (static_cast\u003cFrom\u003e(to) != from) {\n    return cpp::fail(narrow_error::loss_of_data);\n  }\n\n  return to;\n}\n\nstruct {\n  template \u003ctypename T\u003e\n  auto operator()(const T\u0026 x) -\u003e std::string {\n    return std::to_string(x);\n  }\n} to_string;\n\nauto main() -\u003e int {\n  assert(try_narrow\u003cstd::uint8_t\u003e(42LL).map(to_string) == \"42\");\n}\n```\n\n\u003ckbd\u003e[Try online](https://godbolt.org/z/448vf9)\u003c/kbd\u003e\n\n## Quick References\n\n* [🔍 Why `result`?](#why-result) \\\n  A background on the problem **Result** solves\n* [💾 Installation](doc/installing.md) \\\n  For a quick guide on how to install/use this in other projects\n* [📚 Tutorial](doc/tutorial.md) \\\n  A quick pocket-guide to using **Result**\n* [📄 API Reference](https://bitwizeshift.github.io/result/api/latest/) \\\n  For doxygen-generated API information\n* [🚀 Contributing](.github/CONTRIBUTING.md) \\\n  How to contribute to the **Result** project\n* [💼 Attribution](doc/legal.md) \\\n  Information about how to attribute this project\n* [❓ FAQ](doc/faq.md) \\\n  A list of frequently asked questions\n\n## Why `result`?\n\nError cases in C++ are often difficult to discern from the API. Any function\nnot marked `noexcept` can be assumed to throw an exception, but the exact _type_\nof exception, and if it even derives from `std::exception`, is ambiguous.\nNothing in the language forces which exceptions may propagate from an API, which\ncan make dealing with such APIs complicated.\n\nOften it is more desirable to achieve `noexcept` functions where possible, since\nthis allows for better optimizations in containers (e.g. optimal moves/swaps)\nand less cognitive load on consumers.\n\nHaving a `result\u003cT, E\u003e` type on your API not only semantically encodes that\na function is _able to_ fail, it also indicates to the caller _how_ the function\nmay fail, and what discrete, testable conditions may cause it to fail -- which\nis what this library intends to solve.\n\nAs a simple example, compare these two identical functions:\n\n```cpp\n// (1)\nauto to_uint32(const std::string\u0026 x) -\u003e std::uint32_t;\n\n// (2)\nenum class parse_error { overflow=1, underflow=2, bad_input=3};\nauto to_uint32(const std::string\u0026 x) noexcept -\u003e result\u003cstd::uint32_t,parse_error\u003e;\n```\n\nIn `(1)`, it is ambiguous _what_ (if anything) this function may throw on\nfailure, or how this error case may be accounted for.\n\nIn `(2)`, on the other hand, it is explicit that `to_uint32` _cannot_ throw --\nso there is no need for a `catch` handler. It's also clear that it may fail for\nwhatever reasons are in `parse_error`, which discretely enumerates any possible\ncase for failure.\n\n## Compiler Compatibility\n\n**Result** is compatible with any compiler capable of compiling valid\n\u003ckbd\u003eC++11\u003c/kbd\u003e. Specifically, this has been tested and is known to work\nwith:\n\n* GCC 5, 6, 7, 8, 9, 10\n* Clang 3.5, 3.6, 3.7, 3.8, 3.9, 4, 5, 6, 7, 8, 9, 10, 11\n* Apple Clang (Xcode) 10.3, 11.2, 11.3, 12.3\n* Visual Studio 2017\u003csup\u003e[1]\u003c/sup\u003e, 2019\n\nLatest patch level releases are assumed in the versions listed above.\n\n**Note:** Visual Studios 2015 is not currently supported due to an internal\ncompiler error experienced in the default constructor of `result`. Support for\nthis will be added at a later time.\n\n\u003csup\u003e[1] Visual Studios 2017 is officially supported, though toolchain 14.16\nhas some issues properly compiling `map_error` due to insufficient support for\nSFINAE.\u003c/sup\u003e\n\n## License\n\n\u003cimg align=\"right\" src=\"http://opensource.org/trademarks/opensource/OSI-Approved-License-100x137.png\"\u003e\n\n**Result** is licensed under the\n[MIT License](http://opensource.org/licenses/MIT):\n\n\u003e Copyright \u0026copy; 2017-2021 Matthew Rodusek\n\u003e\n\u003e Permission is hereby granted, free of charge, to any person obtaining a copy\n\u003e of this software and associated documentation files (the \"Software\"), to deal\n\u003e in the Software without restriction, including without limitation the rights\n\u003e to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n\u003e copies of the Software, and to permit persons to whom the Software is\n\u003e furnished to do so, subject to the following conditions:\n\u003e\n\u003e The above copyright notice and this permission notice shall be included in all\n\u003e copies or substantial portions of the Software.\n\u003e\n\u003e THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n\u003e IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n\u003e FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n\u003e AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n\u003e LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n\u003e OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n\u003e SOFTWARE.\n\n## References\n\n* [P0323R9](http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p0323r9.html):\n  `std::expected` proposal was used as an inspiration for the general template\n  structure.\n* [bit::stl](https://github.com/bitwizeshift/bit-stl/blob/20f41988d64e1c4820175e32b4b7478bcc3998b7/include/bit/stl/utilities/expected.hpp): the original version that seeded this repository, based off an earlier proposal version.\n","funding_links":["https://github.com/sponsors/bitwizeshift","https://www.buymeacoffee.com/dsq3XCcBE"],"categories":["C++"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitwizeshift%2Fresult","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbitwizeshift%2Fresult","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitwizeshift%2Fresult/lists"}