If you've already checked by hand, the compiler will elide the internal check entirely.
That's quite a claim to make here. When looking at vector<T>::at, this is certainly not the case, unless compilers made significant improvements over the last few years.
I have spent a lot of time tuning the implementation of Outcome to be optimiser friendly. I have also been looking at the disassembly of these objects in use in real world code for over a year. Unless you do a system call, a call to an extern function, or an atomic operation, the optimiser does a really great job at converting sequences of (with the if() hidden inside the outcome implementation): if(has_value) something1(value()); else something2(error()); if(has_value) something3(value()); else something4(error()); if(has_value) something5(value()); else something6(error()); ... into: if(has_value) { something1(value()); something3(value()); something5(value()); } else { something2(error()); something4(error()); something6(error()); } So, I repeat my claim about eliding the internal check. The optimiser is clever, if you don't give it cause not to eliminate code, it'll eliminate code very effectively, especially clang 4.0+ and GCC 6.0+. Besides, the checking of current state is not the expensive part, it's usually free on an out-of-order CPU as compare and branch usually uses non-busy execution ports whilst the CPU is stalled on memory. It's any branch misprediction which costs real time, typically 20 cycles or so on recent Intel chips. As a general rule, jumps to addresses later than current are predicted to not happen, so I intentionally placed the empty state value before valued, errored and excepted. That causes branches to equally mispredict for any of the valued, errored and excepted states, thus creating predictable execution times by creating a 20 cycle stall for all states but empty for when the state of an outcome is not deduced by the compiler. So I have paid attention to this stuff. My choices may be disagreeable to some or many, but it's not like they weren't thought through.
When I open its "landing page", I get no idea about the following: - What is the purpose of the library? - Why/when should I use it?
It quite literally tells you both on the landing page. https://ned14.github.io/boost.outcome/index.html.
From an empirical study of a non representative group, it seems it is not as literal as you would like it to be. One thing is that the points I mentioned are not visually distinguishable at first sight, there are three paragraphs with lots of prose.
The first paragraph reads: "This is the Outcome library. It is a C++ 14 library intended to aid ultra-lightweight error handling in large C++ codebases, providing a more expressive and type safe alternative to integer error codes or enums."
Apart from the trigger word "ultra-lightweight", what the library actually does is at the very end in a long sentence.
The second: "Unlike alternative implementations, it works perfectly with exceptions and RTTI disabled and is thus suitable for low-latency/games/finance/SG14 users. One could view Outcome as a minimum overhead universal outcome transport mechanism for C++, hence being named "Outcome"."
This sentence starts with "Unlike alternative implementations", I don't even know what to expect from this library, at this point, I really don't care about the alternatives yet, speaking of which, which alternatives? The key feature you wanted to highlight here is probably "works with exceptions and RTTI disabled".
The next two paragraphs follow the same scheme.
So in a nutshell:
The Outcome library implements a set of types to be used for lightweight error transport. The main features include: - Type safe alternative to integer or enum based error codes - Works with exceptions and RTTI disabled - Suitable for real-time and low latency applications - Efficient implementation - Rich set of different types to support different use cases
And then you can go on with everything else you want to say, possibly with links pointing into the documentation on where potential users are able to find more about the various topics you just advertised. (Just a braindump of mine, not claiming this is the ultimate solution.)
I used to have bullet points, but a previous round of Reddit and Boost feedback reduced the landing page to what is currently there on the basis of less information is more. You may have missed that Andrzej has already volunteered to restructure the landing page and intro into more bitesize chunks. You can track that issue at https://github.com/ned14/boost.outcome/issues/41. I have appended your notes to that issue. Thank you for the feedback. Niall -- ned Productions Limited Consulting http://www.nedproductions.biz/ http://ie.linkedin.com/in/nialldouglas/