bprint.h File Reference

#include "attributes.h"
#include "avstring.h"

Include dependency graph for bprint.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	AVBPrint
	Buffer to print data progressively. More...

Macros
#define	FF_PAD_STRUCTURE(size, ...)
	Define a structure with extra padding to a fixed size This helps ensuring binary compatibility with future versions. More...
#define	AV_BPRINT_SIZE_UNLIMITED   ((unsigned)-1)
	Convenience macros for special values for av_bprint_init() size_max parameter. More...
#define	AV_BPRINT_SIZE_AUTOMATIC   1
#define	AV_BPRINT_SIZE_COUNT_ONLY   0

Typedefs
typedef struct AVBPrint	AVBPrint
	Buffer to print data progressively. More...

Functions
void	av_bprint_init (AVBPrint *buf, unsigned size_init, unsigned size_max)
	Init a print buffer. More...
void	av_bprint_init_for_buffer (AVBPrint *buf, char *buffer, unsigned size)
	Init a print buffer using a pre-existing buffer. More...
void	av_bprintf (AVBPrint *buf, const char *fmt,...) av_printf_format(2
	Append a formatted string to a print buffer. More...
void void	av_bprint_chars (AVBPrint *buf, char c, unsigned n)
	Append char c n times to a print buffer. More...
void	av_bprint_strftime (AVBPrint *buf, const char *fmt, const struct tm *tm)
	Append a formatted date and time to a print buffer. More...
void	av_bprint_get_buffer (AVBPrint *buf, unsigned size, unsigned char **mem, unsigned *actual_size)
	Allocate bytes in the buffer for external use. More...
void	av_bprint_clear (AVBPrint *buf)
	Reset the string to "" but keep internal allocated data. More...
static int	av_bprint_is_complete (AVBPrint *buf)
	Test if the print buffer is complete (not truncated). More...
int	av_bprint_finalize (AVBPrint *buf, char **ret_str)
	Finalize a print buffer. More...
void	av_bprint_escape (AVBPrint *dstbuf, const char *src, const char *special_chars, enum AVEscapeMode mode, int flags)
	Escape the content in src and append it to dstbuf. More...

Macro Definition Documentation

#define AV_BPRINT_SIZE_AUTOMATIC   1

Definition at line 90 of file bprint.h.

Referenced by configure_input_audio_filter(), make_command_flags_str(), microdvd_init(), parse_psfile(), query_formats(), and writer_print_rational().

#define AV_BPRINT_SIZE_COUNT_ONLY   0

Definition at line 91 of file bprint.h.

#define AV_BPRINT_SIZE_UNLIMITED   ((unsigned)-1)

Convenience macros for special values for av_bprint_init() size_max parameter.

Definition at line 89 of file bprint.h.

Referenced by ass_read_header(), av_escape(), compact_print_str(), ff_ass_add_rect(), ffprobe_show_program_version(), flat_print_str(), ini_print_str(), init(), json_print_int(), json_print_item_str(), json_print_section_header(), lavfi_read_packet(), main(), mov_text_decode_frame(), mpl2_decode_frame(), mpsub_read_header(), realtext_read_header(), sami_read_header(), show_frame(), show_packet(), show_stream(), srt_read_header(), subviewer_decode_frame(), subviewer_read_header(), text_decode_frame(), webvtt_decode_frame(), webvtt_read_header(), writer_open(), writer_print_data(), and xml_print_str().

#define FF_PAD_STRUCTURE	(		size,
			...
	)

Value:

__VA_ARGS__ \
    char reserved_padding[size - sizeof(struct { __VA_ARGS__ })];

Define a structure with extra padding to a fixed size This helps ensuring binary compatibility with future versions.

Definition at line 31 of file bprint.h.

Typedef Documentation

typedef struct AVBPrint AVBPrint

Buffer to print data progressively.

The string buffer grows as necessary and is always 0-terminated. The content of the string is never accessed, and thus is encoding-agnostic and can even hold binary data.

Small buffers are kept in the structure itself, and thus require no memory allocation at all (unless the contents of the buffer is needed after the structure goes out of scope). This is almost as lightweight as declaring a local "char buf[512]".

The length of the string can go beyond the allocated size: the buffer is then truncated, but the functions still keep account of the actual total length.

In other words, buf->len can be greater than buf->size and records the total length of what would have been to the buffer if there had been enough memory.

Append operations do not need to be tested for failure: if a memory allocation fails, data stop being appended to the buffer, but the length is still updated. This situation can be tested with av_bprint_is_complete().

The size_max field determines several possible behaviours:

size_max = -1 (= UINT_MAX) or any large value will let the buffer be reallocated as necessary, with an amortized linear cost.

size_max = 0 prevents writing anything to the buffer: only the total length is computed. The write operations can then possibly be repeated in a buffer with exactly the necessary size (using size_init = size_max = len + 1).

size_max = 1 is automatically replaced by the exact size available in the structure itself, thus ensuring no dynamic memory allocation. The internal buffer is large enough to hold a reasonable paragraph of text, such as the current paragraph.

Function Documentation

void void av_bprint_chars	(	AVBPrint *	buf,
		char	c,
		unsigned	n
	)

Append char c n times to a print buffer.

Definition at line 116 of file bprint.c.

Referenced by av_bprint_escape(), av_bprint_utf8(), avfilter_graph_dump_to_buf(), c_escape_str(), csv_escape_str(), expand_filename_template(), expand_text(), ff_smil_extract_next_chunk(), ff_subtitles_read_chunk(), flat_escape_key_str(), flat_escape_value_str(), get_line(), ini_escape_str(), json_escape_str(), lavfi_read_packet(), main(), make_command_flags_str(), microdvd_decode_frame(), mpl2_event_to_ass(), parse_string(), rt_event_to_ass(), sami_paragraph_to_ass(), subviewer_event_to_ass(), text_event_to_ass(), text_to_ass(), webvtt_event_to_ass(), writer_print_data(), and xml_escape_str().

void av_bprint_clear

(

AVBPrint *

buf

)

Reset the string to "" but keep internal allocated data.

Definition at line 185 of file bprint.c.

Referenced by compact_print_section_header(), default_print_section_header(), draw_text(), expand_text(), ff_subtitles_read_chunk(), flat_print_section_header(), flat_print_str(), get_line(), ini_print_section_header(), ini_print_str(), json_print_item_str(), microdvd_init(), parse_psfile(), realtext_read_header(), sami_paragraph_to_ass(), sami_read_header(), show_frame(), and xml_print_str().

void av_bprint_escape	(	AVBPrint *	dstbuf,
		const char *	src,
		const char *	special_chars,
		enum AVEscapeMode	mode,
		int	flags
	)

Escape the content in src and append it to dstbuf.

Parameters

dstbuf	already inited destination bprint buffer
src	string containing the text to escape
special_chars	string containing the special characters which need to be escaped, can be NULL
mode	escape mode to employ, see AV_ESCAPE_MODE_* macros. Any unknown value for mode will be considered equivalent to AV_ESCAPE_MODE_BACKSLASH, but this behaviour can change without notice.
flags	flags which control how to escape, see AV_ESCAPE_FLAG_* macros

Definition at line 223 of file bprint.c.

Referenced by av_bprint_is_complete(), and av_escape().

int av_bprint_finalize	(	AVBPrint *	buf,
		char **	ret_str
	)

Finalize a print buffer.

The print buffer can no longer be used afterwards, but the len and size fields are still valid.

• [out] ret_str if not NULL, used to return a permanent copy of the buffer contents, or NULL if memory allocation fails; if NULL, the buffer is discarded and freed

  Returns

  0 for success or error code (probably AVERROR(ENOMEM))

Definition at line 193 of file bprint.c.

Referenced by ass_read_header(), av_bprint_escape(), av_bprint_is_complete(), av_escape(), avfilter_graph_dump(), avpriv_bprint_to_extradata(), compact_print_str(), configure_output_audio_filter(), decode_text_chunk(), decode_zbuf(), ff_ass_add_rect(), ffprobe_show_program_version(), flat_print_str(), ini_print_str(), init_report(), jacosub_decode_frame(), json_print_int(), json_print_item_str(), json_print_section_header(), lavfi_read_packet(), main(), microdvd_decode_frame(), mov_text_decode_frame(), mpl2_decode_frame(), mpsub_read_header(), parse_file(), parse_psfile(), parse_string(), print_report(), realtext_decode_frame(), realtext_read_header(), sami_close(), sami_read_header(), show_frame(), show_packet(), show_stream(), srt_read_header(), subviewer_decode_frame(), subviewer_read_header(), text_decode_frame(), uninit(), webvtt_decode_frame(), webvtt_read_header(), writer_close(), writer_print_data(), and xml_print_str().

void av_bprint_get_buffer	(	AVBPrint *	buf,
		unsigned	size,
		unsigned char **	mem,
		unsigned *	actual_size
	)

Allocate bytes in the buffer for external use.

Parameters

[in]	buf	buffer structure
[in]	size	required size
[out]	mem	pointer to the memory area
[out]	actual_size	size of the memory area after allocation; can be larger or smaller than size

Definition at line 176 of file bprint.c.

Referenced by decode_zbuf().

void av_bprint_init	(	AVBPrint *	buf,
		unsigned	size_init,
		unsigned	size_max
	)

Init a print buffer.

Parameters

buf	buffer to init
size_init	initial size (including the final 0)
size_max	maximum size; 0 means do not write anything, just count the length; 1 is replaced by the maximum value for automatic storage; any large value means that the internal buffer will be reallocated as needed up to that limit; -1 is converted to UINT_MAX, the largest limit possible. Check also AV_BPRINT_SIZE_* macros.

Definition at line 68 of file bprint.c.

Referenced by ass_read_header(), av_bprint_escape(), av_escape(), avfilter_graph_dump(), compact_print_str(), config_output(), configure_input_audio_filter(), configure_input_video_filter(), configure_output_audio_filter(), decode_zbuf(), dvdsub_init(), ff_ass_add_rect(), ffprobe_show_program_version(), flat_print_str(), ini_print_str(), init(), init_report(), jacosub_decode_frame(), jacosub_read_header(), json_print_int(), json_print_item_str(), json_print_section_header(), lavfi_read_packet(), main(), make_command_flags_str(), microdvd_decode_frame(), microdvd_init(), mov_text_decode_frame(), mpl2_decode_frame(), mpsub_read_header(), parse_psfile(), parse_string(), print_report(), query_formats(), realtext_decode_frame(), realtext_read_header(), sami_init(), sami_read_header(), show_frame(), show_packet(), show_stream(), srt_read_header(), subviewer_decode_frame(), subviewer_read_header(), text_decode_frame(), webvtt_decode_frame(), webvtt_read_header(), writer_open(), writer_print_data(), writer_print_rational(), and xml_print_str().

void av_bprint_init_for_buffer	(	AVBPrint *	buf,
		char *	buffer,
		unsigned	size
	)

Init a print buffer using a pre-existing buffer.

The buffer will not be reallocated.

Parameters

buf	buffer structure to init
buffer	byte buffer to use for the string data
size	size of buffer

Definition at line 84 of file bprint.c.

Referenced by av_bprint_escape(), and av_get_channel_layout_string().

static int av_bprint_is_complete ( AVBPrint *  buf )

inlinestatic

Test if the print buffer is complete (not truncated).

It may have been truncated due to a memory allocation failure or the size_max limit (compare size and size_max if necessary).

Definition at line 166 of file bprint.h.

Referenced by av_bprint_alloc(), av_escape(), draw_text(), expand_text(), ff_ass_add_rect(), init_report(), lavfi_read_packet(), main(), mov_text_decode_frame(), mpl2_decode_frame(), parse_string(), and text_decode_frame().

void av_bprint_strftime	(	AVBPrint *	buf,
		const char *	fmt,
		const struct tm *	tm
	)

Append a formatted date and time to a print buffer.

param buf bprint buffer to use param fmt date and time format string, see strftime() param tm broken-down time structure to translate

Note

due to poor design of the standard strftime function, it may produce poor results if the format string expands to a very long text and the bprint buffer is near the limit stated by the size_max option.

Definition at line 134 of file bprint.c.

Referenced by av_bprint_escape(), draw_text(), and func_strftime().

void av_bprintf	(	AVBPrint *	buf,
		const char *	fmt,
			...
	)

Append a formatted string to a print buffer.