AVBPrint

A buffer to print data progressively. More...

Files
file	bprint.h
	AVBPrint public header.

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

Macros
#define	FF_PAD_STRUCTURE(name, size, ...)
	Define a structure with extra padding to a fixed size This helps ensuring binary compatibility with future versions.

Functions
void	av_bprint_init (AVBPrint *buf, unsigned size_init, unsigned size_max)
	Init a print buffer.
void	av_bprint_init_for_buffer (AVBPrint *buf, char *buffer, unsigned size)
	Init a print buffer using a pre-existing buffer.
void	av_bprintf (AVBPrint *buf, const char *fmt,...) av_printf_format(2
	Append a formatted string to a print buffer.
void void	av_vbprintf (AVBPrint *buf, const char *fmt, va_list vl_arg)
	Append a formatted string to a print buffer.
void	av_bprint_chars (AVBPrint *buf, char c, unsigned n)
	Append char c n times to a print buffer.
void	av_bprint_append_data (AVBPrint *buf, const char *data, unsigned size)
	Append data to a print buffer.
void	av_bprint_strftime (AVBPrint *buf, const char *fmt, const struct tm *tm)
	Append a formatted date and time to a print buffer.
void	av_bprint_get_buffer (AVBPrint *buf, unsigned size, unsigned char **mem, unsigned *actual_size)
	Allocate bytes in the buffer for external use.
void	av_bprint_clear (AVBPrint *buf)
	Reset the string to "" but keep internal allocated data.
static int	av_bprint_is_complete (const AVBPrint *buf)
	Test if the print buffer is complete (not truncated).
int	av_bprint_finalize (AVBPrint *buf, char **ret_str)
	Finalize a print buffer.
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.

Max size special values
Convenience macros for special values for av_bprint_init() size_max parameter.
#define	AV_BPRINT_SIZE_UNLIMITED   ((unsigned)-1)
	Buffer will be reallocated as necessary, with an amortized linear cost.
#define	AV_BPRINT_SIZE_AUTOMATIC   1
	Use the exact size available in the AVBPrint structure itself.
#define	AV_BPRINT_SIZE_COUNT_ONLY   0
	Do not write anything to the buffer, only calculate the total length.

Detailed Description

A buffer to print data progressively.

Macro Definition Documentation

FF_PAD_STRUCTURE

#define FF_PAD_STRUCTURE	(		name,
			size,
			...
	)

Value:

struct ff_pad_helper_##name { __VA_ARGS__ }; \
typedef struct name { \
    __VA_ARGS__ \
    char reserved_padding[size - sizeof(struct ff_pad_helper_##name)]; \
} name;

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

Definition at line 48 of file bprint.h.

AV_BPRINT_SIZE_UNLIMITED

#define AV_BPRINT_SIZE_UNLIMITED   ((unsigned)-1)

Buffer will be reallocated as necessary, with an amortized linear cost.

Definition at line 111 of file bprint.h.

AV_BPRINT_SIZE_AUTOMATIC

#define AV_BPRINT_SIZE_AUTOMATIC   1

Use the exact size available in the AVBPrint 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.

Definition at line 118 of file bprint.h.

AV_BPRINT_SIZE_COUNT_ONLY

#define AV_BPRINT_SIZE_COUNT_ONLY   0

Do not write anything to the buffer, only calculate the total length.

The write operations can then possibly be repeated in a buffer with exactly the necessary size (using size_init = size_max = AVBPrint.len + 1).

Definition at line 125 of file bprint.h.

Function Documentation

av_bprint_init()

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.

av_bprint_init_for_buffer()

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. In case size equals zero, the AVBPrint will be initialized to use the internal buffer as if using AV_BPRINT_SIZE_COUNT_ONLY with av_bprint_init().

Parameters

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

av_bprintf()

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

Append a formatted string to a print buffer.

av_vbprintf()

void void av_vbprintf	(	AVBPrint *	buf,
		const char *	fmt,
		va_list	vl_arg
	)

Append a formatted string to a print buffer.

av_bprint_chars()

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

Append char c n times to a print buffer.

av_bprint_append_data()

void av_bprint_append_data	(	AVBPrint *	buf,
		const char *	data,
		unsigned	size
	)

Append data to a print buffer.

Parameters

buf	bprint buffer to use
data	pointer to data
size	size of data

av_bprint_strftime()

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

Append a formatted date and time to a print buffer.

Parameters

buf	bprint buffer to use
fmt	date and time format string, see strftime()
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.

av_bprint_get_buffer()

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

av_bprint_clear()

void av_bprint_clear

(

AVBPrint *

buf

)

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

av_bprint_is_complete()

static int av_bprint_is_complete ( const 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 218 of file bprint.h.

av_bprint_finalize()

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))

av_bprint_escape()

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