Loading...
Searching...
No Matches
AVBPrint
libavutil » Data Structures

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.

Referenced by av_vbprintf().

## av_bprint_chars()

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

Append char c n times to a print buffer.

Referenced by av_bprint_chars().

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

Referenced by av_bprint_append_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.

Referenced by av_bprint_strftime().

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

Referenced by av_bprint_get_buffer().

## av_bprint_clear()

void av_bprint_clear | ( | AVBPrint * | buf | ) |

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

Referenced by av_bprint_clear().

## av_bprint_is_complete()

int av_bprint_is_complete | ( | const AVBPrint * | buf | ) |

inline static

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.

Referenced by av_bprint_is_complete().

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