Adding VariableLengthArray and PMR namespace

[thirtytwobits]

Providing a polyfill of much of the pmr namespace for C++14.

Adding VariableLengthArray as an allocator-aware vector. CETL's VLA differs from vector in three respects:

1. it supports the CETL-specific reallocation extension to PMR::memory_resource
2. it will tightly fit into a maximum size when elements are pushed without calling reserve first.
3. it avoids undefined behaviour when exceptions are disabled.

An unintended benefit: this works with C++17/AppleClang which does not support PMR.

Reviewer Notes

As always, feel free to skip the vscode/cmake stuff. There was a major refactor of this as I learned more about cmake and I enabled sharing modules with dependent projects (i.e. libcyphal).

This is a huge change. Sorry. Circumstances prevented me from getting PMR in before VLA. If the review is too daunting I can split it up into three stages but it would take some time to get each building independently. One way to make this easier is to review everything under the PMR namespace first and ignore VLA to start with then come back to the VLA.

There are known missing comments, unittests, and CI fix-ups that I'll be working on in parallel.

[pavel-kirienko]

Is there some place on the web where the docs could be deployed for review?

[thirtytwobits]

Is there some place on the web where the docs could be deployed for review?

I fixed the CI enough that the latest run uploaded an archive of the docs.

Also: The CI revealed that std::vector can refuse to shrink_to_fit when exceptions are disabled. I'll need to fixup the tests to account for this.

[pavel-kirienko]

• I would strongly prefer to have VariableLengthArray::at(std::size_t) defined similarly to https://github.com/OpenCyphal/nunavut/blob/f0cc6cdd7ab665b7d2612872339ec35cd560e278/src/nunavut/lang/cpp/support/variable_length_array.hpp#L1330C49-L1353. Both for the main template and its bool specialization.
• Doc pages omit the full path to header files; the resulting #include directive is invalid. Example:
  

Not sure I understand the purpose of clang-format-check.py when the same could be achieved in fewer lines of code via a custom cmake target (unless I'm missing something), but I presume it is comparatively unimportant. I mostly skipped all of the copious scaffolding and focused on the docs & code.

[thirtytwobits]

clang-format-check.py when the same could be achieved in fewer lines of code via a custom cmake target

Do tell! I'd love to get rid of this if I could but I didn't want to try to parse xml in cmake.

[thirtytwobits]

would strongly prefer to have VariableLengthArray::at(std::size_t) defined similarly to...

Sorry, but I'm not going to put a production abort() into the code. You can implement an external helper:

template<typename VLAType>
const typename VLAType::value_type& at(const VLAType& container, std::size_t pos)
{
    if (pos >= container.size())
    {
#if __cpp_exceptions
        throw std::out_of_range("VariableLengthArray::at");
#else
        std::abort();
#endif
    }
    return container[pos];
}

[pavel-kirienko]

I normally use https://github.com/marketplace/actions/clang-format-lint together with a format build target that invokes clang-format when necessary, also there are IDE integrations for on-the-fly reformatting. If you want to keep the formatting check strictly a part of CMake project, then perhaps invoking clang-format with clang-format --dry-run --Werror <paths...> is what you need?

[pavel-kirienko]

Sorry, but I'm not going to put a production abort() into the code. You can implement an external helper:

How about the old at_or_null? For the bool specialization it would become:

std::optional<reference> at_or_null(const size_type);
std::optional<const_reference> at_or_null(const size_type) const;

[thirtytwobits]

Sorry, but I'm not going to put a production abort() into the code. You can implement an external helper:

How about the old at_or_null? For the bool specialization it would become:

std::optional<reference> at_or_null(const size_type);
std::optional<const_reference> at_or_null(const size_type) const;

Yes. I was planning on doing that when I added optional to CETL.

[thirtytwobits]

Sorry for the rebase but I wanted squash all the crap I've been picking away at so I can add the few substantive changes still pending on top of a single "fix CI" change.

[thirtytwobits]

@pavel-kirienko ? Can you approve?

[sonarqubecloud]

Kudos, SonarCloud Quality Gate passed!   

0 Bugs
0 Vulnerabilities
0 Security Hotspots
0 Code Smells

91.4% Coverage
0.6% Duplication