[FFmpeg-devel] The case for a good string API

[Nicolas George]

Hi.

I will try again proposing a good string API for the project. But this
time, instead of showing the implementation code, I will ask about the
principle.

So, please, read the argument, and give your opinion on the principle.
If we agree on the principle, we can discuss the code then.


* Why we need a better string API

Strings are not the bulk of what we do, but for the user interface of
things we have a LOT of functions that return strings: to describe a
color space or a channel layout or a set of options.

When the returned string is short, we use the good old
“char *buf, size_t buf_size”. When it is long, we return a
dynamically-allocated buffer. When the string is almost always short but
can actually be very long, and the conversion is used in speed-critical
code, we are screwed.

With a good string API, we could use the same API everywhere, it would
automatically use the most efficient memory scheme.

Furthermore, if all our object→string functions have the same prototype,
it makes it easier to use these functions as standardized callbacks and
opens a whole lot of new possibilities of serialization features.

Moreover, a good string API would bring quite a few extra benefits, with
a few examples: easier to build strings from parts, less verbose and
more robust error checking, the ability to use directly the string or
buffering API of another library or language.

So, even though strings are not the core of our thing, I think we should
have a good string API, just like we have an API for efficient FFTs
(which is the core of our thing). But let us discuss it further:


* Objections and counter-objections

- A string API adds complexity.

Indeed, that is true. But the added complexity is clearly isolated in
one or a few source files. In the rest of the code, it removes
complexity (see less verbose error checking, easier to build strings
from parts above).

String conversion functions can happen once per short frame, for example
in the ashowinfo filter. We have pools for frames and for buffers: we
already consider that avoid once-per-frame memory allocations is worth
the added complexity. A string API is just a step in the same direction.

- An unusual API is annoying for people who will use it.

Unless we messed up, if they use strings more than just a little, the
benefits of the API is way worth the cost of learning.

But some people use strings just a little. For them, who would be happy
with a plain C string, we should make sure the required learning is very
very limited. And we can:
“instead of ‘buf, sizeof(buf)’, write ‘string_from_buffer(buf)”.
That is all, in one short line I have documented how to use the API with
the old patterns.

There is a little more to write for people who want a dynamic buffer for
an unlimited string (error checks are always annoying), but we can keep
it under three minutes.


* What string API we should use

We have AVBprint, but the API is ugly, and it only brings a few of the
benefits I promised. I have a proposal: AVWriter.

I posted it last spring, here is an introduction on how to use it (with
the implementation in the same thread):

https://ffmpeg.org/pipermail/ffmpeg-devel/2021-April/279383.html


* Conclusion

Well, I am convinced, but what about you?

1. Do you think FFmpeg needs a good string API? If not, please explain
why?

2. Assuming we agree ‘yes’ on the previous question, do you think
AVWriter is a good candidate? If not, what else would you propose?

Regards,

-- 
  Nicolas George
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: not available
URL: <https://ffmpeg.org/pipermail/ffmpeg-devel/attachments/20211222/075d061b/attachment.sig>