capped append, assign and insert

[GitSparTV]

Hello, I've found a few cases when I have to write excessively long expressions while using this library, I want to share them and propose new methods.

Currently append, assign and insert will throw an exception if the final size is greater than the capacity. Due to this I had to write something like this in my code:

boost::static_string<128> str;

str.assign(some_runtime_info, 0, str.max_size() - str.size());
str.append(" "sv, 0, str.max_size() - str.size());
str.append(something_else, 0, str.max_size() - str.size());

In this example str is a small name for a variable, but in reality it might be a long chain of nested structures.
Notice I had to append single char as a string_view so I can cap it to the buffer size.
That's because str.append(std::min(str.max_size() - str.size(), 1), ' '); is longer.

I propose to add additional methods named capped_append/capped_assign/capped_insert that will add characters up to string capacity.
I saw there is capped_length, so chose it. It could be safe_append, trim_append, cap_append, clip_append, limit_append, bounded_append, truncating_append, fit_append, max_append, shrink_append, you name it.

std::inplace_vector has somewhat similar API: emplace_back, try_emplace_back, unchecked_emplace_back. Their naming will not be suitable because try_* method is trying to emplace single item (single char in terms of std::inplace_vector<char, N>) – my problem wasn't "try to emplace a whole string or ignore" type of situation. And unchecked_* method is not what I propose, however, it could be discussed as well.

I'm also willing to contribute a PR for these methods if you are open for them and we agree on the design

[gennaroprota]

Thanks for your proposal and offer, but that would mean adding something like roughly 30 functions to the already large API surface. That's a cost every maintainer, future reader, documentation page, and every overload-resolution diagnostic would pay for. For what is IMHO a very little benefit. What if we add an available() member returning max_size() - size()? In that case, you'd have e.g.:

str.append( v, 0, str.available() );

which seems quite readable.

[GitSparTV]

Yeah, that would be easier.
What remains is str.append(std::min(str.available(), 1), ' '); and the need to mention the variable twice (better than 3 though, I can live with it).

[gennaroprota]

You could have your project-specific helper:

template <typename S>
S& capped_append(S& s,
                 typename S::size_type count,
                 typename S::value_type ch)
{
    return s.append((std::min)(count, s.available()), ch);
}

The same pattern generalizes to the string-view-like forms with one more overload:

template <typename S, typename V>
S& capped_append(S& s, const V& v)
{
    return s.append(v, 0, s.available());
}

Although, if you have those overloads, you don't even need available() :-).