Inconsistent messages about exceptions in the library docs

[akrzemi1]

In the docs for develop branch we read in the Overview.Features section:

Interfaces are provided for using error codes instead of exceptions as needed.

And later:

Works without exceptions

This could be read as "this library does not throw exceptions". But this is far from being true. Consider function url::set_scheme.

It can throw in two situations:

1. When an allocation is needed and this allocation throws. (This is a "lack of resources" situation.) (The type of the exceptions is not well described in the docs.)
2. When the input argument is not a valid scheme under rfc3986. (This is either an "input validation" or a "contract violation" situation depending on how you want to see -- and document -- the contract of the function.)

The documentation of the function seem to say that passing an invalid scheme to the function is a valid thing to do (no contract violation). This means that this function can be used for validating strings: if they represent valid URL schemes.

And this is all fine by itself, but inconsistent with the statement "Interfaces are provided for using error codes instead of exceptions as needed." What does it mean for function url::set_scheme, which doesn't have an overload taking an error code argument?

How can I safely set a scheme name that comes from the external source in the program with exceptions disabled? An invalid input will then terminate my program.

I think the correct summary of the approach to exceptions in this library is:

• Functions that parse strings representing URLs report syntax errors via error codes.
• Functions throw exceptions on resource limits, such as "insufficient memory" or "too long input".
• Member functions throw from mutating operations to protect class invariants.
• Exception throws can be turned into abort() via configuration.

[vinniefalco]

You have a point but this could be easily fixed by simply rewording it to

"Mostly works without exceptions"

[akrzemi1]

I might be missing something here, but to me throwing exceptions for resource shortages and invariant protection look like, "works with exceptions as any other library" (which is fine, by the way).

Or maybe the following would be more accurate.

We have low-level functions, like pct_decode that signal errors via error codes, and high-level abstractions, like url, that throw exceptions.

[vinniefalco]

Well, no you aren't missing anything. I agree that the docs need to be updated (we are working on that now). The current description on the overview page was written before we started using result return types for everything, instead of sometimes passing error_code& as an out-param. It will be updated before the review period starts (maybe the night before, lol).

[alandefreitas]

I'm reopening this since it came up in the review again.

There is one thing that I do not understand though. I read that:

1. The library is tailored for environments that do not use exceptions
2. url guarantees that it maintains its invariant of always storing a
   string that represents a valid url.

So given the following code executed on a platform with exceptions
disabled, what happens?

void test(url my_url)
{
my_url.set_port("twenty-one");
}

is it going to kill the program? If so, is this considered a satisfactory
solution? I use exceptions in my job, so this is a rather theoretical issue
for me, but if I were using urls in no-exceptions environment, I think I
would expect an interface like:

error_code ec;
my_url.set_port("twenty-one", ec);

Or something similar.

[alandefreitas]

I believe reopening this issue no longer makes sense at this moment because the documentation has changed and the promises about exceptions that motivate the issue are no longer in the documentation.

[vinniefalco]

we still have to think about try_set_port and try_set_scheme

[alandefreitas]

bool
url_base::
try_set_port(
    string_view s)
{
    op_t op(*this, &s);
    auto rt = grammar::parse(s,
        detail::port_rule{});
    if (!rt)
        return false;
    auto t = *rt;
    auto dest =
        set_port_impl(t.str.size(), op);
    std::memcpy(dest,
        t.str.data(), t.str.size());
    if(t.has_number)
        impl_.port_number_ = t.number;
    else
        impl_.port_number_ = 0;
    return true;
}

or

result<void>
url_base::
try_set_port(
    string_view s);

?

[vinniefalco]

hmm that is a difficult question

[akrzemi1]

I would say that if all other functions return result<T> for signalling potential failure, then use result<void> for consistency, even if result<void> try_set_result() looks awkward by itself.

Is result<T> now the preferred way of signalling failures in the library?