The future of CC

[JacksonAllan]

With the release of v1.4.0 and addition of dynamic strings, Convenient Containers now includes all the containers originally planned for it. Nevertheless, the library’s development will continue. The purpose of this discussion is to outline – in no particular order – my ideas for future improvements to the library, including some breaking API changes.

---

Reconsidering the single-header approach

When CC was first released in late 2022, the library consisted of just 3,244 lines of code contained within 171 KB. Today – after the addition of three more containers (ordered maps, ordered sets, and strings) – it contains 8,383 lines of code and weighs a whopping 452 KB. While documentation, in-code comments, whitespace, and C++ compatibility code account for much of that space, I think it is nevertheless time to consider switching from a single-header approach to a headers-only approach. This switch could bring several advantages:

• A probable compile speed boost for users not using all of CC’s container types.
• The ability to add new containers (e.g. binary heaps) and other features without concerns about their impact on compile speed.
• The elimination of duplicate documentation (currently, the same documentation appears in both the API Reference and the header itself).

Of course, the drawback of this switch is that it would make distributing and installing the library slightly more difficult.

Better compiler errors

Currently, incorrect use of CC’s API results in a barrage of unhelpful compiler notes and errors spanning multiple levels of macros. Often, the source of the error – i.e. the line making the API call in the user’s code – is buried somewhere within or near the bottom of this barrage. This situation could be improved by explicitly type-checking API macro arguments at the top of each macro and emitting a clear error, in conjunction with the relevant line number from the user’s code, in the case of a mismatch. While this approach would not eliminate the unhelpful diagnostics, it would at least ensure that the topmost error displayed to the user is usually clear and relevant.

Better documentation

The API Reference has become rather long and cumbersome. Hence, it may be worth switching to a multipage documentation format more in keeping with cppreference.com’s style, for example. This switch would allow easier navigation and the addition of examples of each API call in use. It would probably occur in conjunction with the removal of the duplicate documentation inside the library header itself, as mentioned above.

Introducing full const correctness into API macros

Currently, API macros mostly ignore the issue of const container-handle arguments. Consequently, const pointers to containers usually cannot be passed into these macros without generating compiler warnings, even if the macro does not mutate the container. This is a rough edge that ought to be corrected.

Safety features

Currently, CC’s policy on memory safety is “trust the programmer”, in keeping with C’s standard library. However, in light of the current push towards memory safety, it would be good to provide basic safety features such as bounds checking and argument validation. Of course, for the sake of performance, these features should be optional, only enabled by a compile-time flag.

Algorithms and other utilities

CC’s API is a good match for generic algorithms, e.g. for sorting or shuffling vectors and lists. Other utilities – such as a generic printing macro along the same lines as the newly introduced push_fmt and insert_fmt – would also be widely useful, even if not specifically related to containers.

Dropping support for C++11 in favor of C++17

Currently, for C++ compatibility, CC uses template functions to emulate C’s _Generic. However, templates compile slowly. The unit test suite takes significantly longer to build in C++ than it does in C. Although C++ compile times are not a top priority, they could probably be improved by instead using if constexpr, in conjunction with lambda functions, as the mechanism for emulating _Generic. Since if constexpr is only available from C++17 onward, this would mean dropping support for C++11. Even if this change is made, the minimum requirement for compiling in C will remain C11.

Relaxing the restriction on container-handle arguments with potential side effects

CC’s current policy is to ensure that all API macro parameters are safe from multiple evaluation except the first parameter – the pointer to the container handle. This exception allows the library to avoid relying on any implementation-defined behavior. To provide extra safety, the library applies an internal mechanism to warn the user if he or she supplies a container-handle argument that may have side effects. However, this mechanism produces false positives, and for the sake of consistency, it is applied to all API macros, even those that only evaluate the container handle once. This approach can interfere with natural use of the library, particularly in the case of containers of containers:

map( int, vec( float ) ) our_map;
init( &our_map );

vec( float ) our_vec;
init( &our_vec );
push( &our_vec, 1.23f );

// Insert the vector into the map.
insert( &our_map, 456, our_vec );

// Generates a warning because the compiler can't tell that the first argument of the
// outermost get has no side effects:
printf( "%f", *get( get( &our_map, 456 ), 0 ) );

// The "proper", albeit cumbersome, way to achieve the same thing without a warning:
vec( float ) *itr = get( &our_map, 456 );
printf( "%f", *get( itr, 0 ) );

Therefore, it is worth considering relaxing this mechanism by at least removing it from API macros that only evaluate the container handle once, such as get in the above example.

Revising API macro names

As discussed earlier, the names of CC’s API macro could be made more descriptive or consistent.

---

Finally, it might be fun to take a quick look at the growth in interest in CC since its inception, as (crudely) reflected by GitHub stars:

This graph suggests an increase in interest over the last year. The library has also begun popping up in other people’s articles and blog posts, such as here, here, and here (where it is rather flatteringly described as "probably as close as one can get to state of the art when it comes to generic collections in C"!). Hopefully, introducing some or all of the above improvements – in addition to publishing some long-overdue articles documenting the techniques that power the library and situating it in the broader landscape of C generics – can help sustain this apparent growth.