I have just made the 0.12 release of CapyPDF. It does not really have new features, but the API has been overhauled. It is almost guaranteed that no code developed against 0.11 will work without code changes. Such is the joy of not having any users.
Experimental C++ wrapper
CapyPDF has a plain C API. This makes it stable and easy to use from any programming language. That also makes it cumbersome to use. Here is what you need to write to create a PDF file that has a single rectangle:
Given that this is C, you can't really do better. However I was asked if I could create something more ergonomic for C++ users. This seemed like an interesting challenge, so I did some experimentation, which ships with the 0.12 release.
The requirements
The C++ wrapper should fulfill the following requirements:
- Fully type safe
- No manual memory management
- Ideally a single header
- Zero overhead
- Fast to compile
- All objects are move-only
- IDE code completion friendly
- Does not need to maintain API or ABI stability (those who need that have to use the C API anyway)
The base
After trying a bunch of different things I eventually came up with this design:
Basically it just stores an underlying CapyPDF object type and a helper class used to deallocate it. The operators merely mean that the object can be cast to a pointer of the underlying type. Typically you want conversion operators to be explicit but these are not, because being implicit removes a ton of boilerplate code.
For example let's look what the Color object wrapper looks like. First you need the deleter:
The class definition itself is simple:
The class has no other members than the one from the base class. The last thing we need before we can start calling into CapyPDF functions is an error handler. Because all functions in the API have the exact same form, this can be done with a single macro:
This makes the constructor look like this:
Method calls bring all of these things together.
Because the wrapper types are implicitly convertible to the underlying pointer types you can pass them directly to the C API functions. Otherwise the wrapper code would be filled with .get() method calls or the like.
The end result
With all that done, the C code from the beginning of this post can be written like this:
Despite using templates, inheritance and stdlib types the end result can be proven to have zero overhead:
After this what remains is mostly the boring work of typing out all the wrapper calls.
