[FFmpeg-devel] [PATCH] lavu: header and documentation for AVWriter

[Andreas Rheinhardt]

Nicolas George:
> The actual implementation, tests and uses in the rest of
> FFmpeg code will be committed separately once the API is
> settled.
> 

I think you misunderstood JB: He did not say that the headers are pushed
without the implementation, he just said that the headers should be
discussed and approved before you code the actual implementation:

> 
> You provide a full header and documentation, and then get it discussed.
> When there is a consensus for approval of the headers, then, you can code the core of it that matches the headers.
> That avoids the "I spent time for nothing" issue.

> diff --git a/libavutil/writer.h b/libavutil/writer.h
> new file mode 100644
> index 0000000000..55e2cf3ea6
> --- /dev/null
> +++ b/libavutil/writer.h
> @@ -0,0 +1,484 @@
> +/*
> + * Copyright (c) 2022 The FFmpeg project
> + *
> + * This file is part of FFmpeg.
> + *
> + * FFmpeg is free software; you can redistribute it and/or
> + * modify it under the terms of the GNU Lesser General Public
> + * License as published by the Free Software Foundation; either
> + * version 2.1 of the License, or (at your option) any later version.
> + *
> + * FFmpeg is distributed in the hope that it will be useful,
> + * but WITHOUT ANY WARRANTY; without even the implied warranty of
> + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
> + * Lesser General Public License for more details.
> + *
> + * You should have received a copy of the GNU Lesser General Public
> + * License along with FFmpeg; if not, write to the Free Software
> + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
> + */
> +
> +#ifndef AVUTIL_WRITER_H
> +#define AVUTIL_WRITER_H
> +
> +#include <stdio.h>
> +#include <stddef.h>
> +#include <stdarg.h>
> +
> +#include "extendable.h"

Where is this header?

> +#include "bprint.h"
> +
> +/**
> + * @defgroup av_writer AVWriter
> + *
> + * Object-oriented API to write strings and binary data.
> + *
> + * @{
> + */
> +
> +typedef struct AVWriterMethods AVWriterMethods;
> +
> +/**
> + * Opaque object to write strings and binary data.
> + *
> + * AVWriter is meant to allow to build and return strings (and blocks of
> + * binary data) efficiently between functions.
> + * For example, a function that serialize something into a string will
> + * actually write into an AVWriter, and the caller will choose the way the
> + * data will be stored or processed on the fly.
> + *
> + * For a quick introduction on how to use AVWriter in simple cases, see
> + * doc/avwriter_intro.md.
> + *
> + * There are various pre-defined types of AVWriter, see below:
> + *
> + * - av_dynbuf_writer() writes the data into a buffer that is grown with
> + *   av_realloc() if it does not fit in the initial buffer; it is the
> + *   recommended choice.
> + *
> + * - av_buf_writer() writes the data into a pre-existing finite buffer.
> + *
> + * - av_stdio_writer() writes the data into a FILE*.
> + *
> + * - av_log_writer() writes the data to av_log().
> + *
> + * AVWriter objects are passed by value. It allows creating a writer on the
> + * fly, without extra variable or error checking. The structure can never
> + * change.
> + */
> +typedef struct AVWriter {
> +    const AVWriterMethods *methods;
> +    void *obj;
> +} AVWriter;
> +
> +/**
> + * Write a data buffer to an AVWriter.
> + */
> +void av_writer_write(AVWriter wr, const char *buf, size_t size);
> +
> +/**
> + * Write a 0-terminated string to an AVWriter.
> + */
> +void av_writer_print(AVWriter wr, const char *str);
> +
> +/**
> + * Write a formatted string to an AVWriter.
> + * Note: do not use libc-specific extensions to the format string.
> + */
> +void av_writer_printf(AVWriter wr, const char *fmt, ...);
> +
> +/**
> + * Write a formatted to string an AVWriter using a va_list.

s/to string/string to/

> + */
> +void av_writer_vprintf(AVWriter wr, const char *fmt, va_list va);