FFmpeg
bprint.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2012 Nicolas George
3  *
4  * This file is part of FFmpeg.
5  *
6  * FFmpeg is free software; you can redistribute it and/or
7  * modify it under the terms of the GNU Lesser General Public
8  * License as published by the Free Software Foundation; either
9  * version 2.1 of the License, or (at your option) any later version.
10  *
11  * FFmpeg is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14  * Lesser General Public License for more details.
15  *
16  * You should have received a copy of the GNU Lesser General Public
17  * License along with FFmpeg; if not, write to the Free Software
18  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
19  */
20 
21 /**
22  * @file
23  * @ingroup lavu_avbprint
24  * AVBPrint public header
25  */
26 
27 #ifndef AVUTIL_BPRINT_H
28 #define AVUTIL_BPRINT_H
29 
30 #include <stdarg.h>
31 
32 #include "attributes.h"
33 #include "avstring.h"
34 
35 /**
36  * @defgroup lavu_avbprint AVBPrint
37  * @ingroup lavu_data
38  *
39  * A buffer to print data progressively
40  * @{
41  */
42 
43 /**
44  * Define a structure with extra padding to a fixed size
45  * This helps ensuring binary compatibility with future versions.
46  */
47 
48 #define FF_PAD_STRUCTURE(name, size, ...) \
49 struct ff_pad_helper_##name { __VA_ARGS__ }; \
50 typedef struct name { \
51  __VA_ARGS__ \
52  char reserved_padding[size - sizeof(struct ff_pad_helper_##name)]; \
53 } name;
54 
55 /**
56  * Buffer to print data progressively
57  *
58  * The string buffer grows as necessary and is always 0-terminated.
59  * The content of the string is never accessed, and thus is
60  * encoding-agnostic and can even hold binary data.
61  *
62  * Small buffers are kept in the structure itself, and thus require no
63  * memory allocation at all (unless the contents of the buffer is needed
64  * after the structure goes out of scope). This is almost as lightweight as
65  * declaring a local `char buf[512]`.
66  *
67  * The length of the string can go beyond the allocated size: the buffer is
68  * then truncated, but the functions still keep account of the actual total
69  * length.
70  *
71  * In other words, AVBPrint.len can be greater than AVBPrint.size and records
72  * the total length of what would have been to the buffer if there had been
73  * enough memory.
74  *
75  * Append operations do not need to be tested for failure: if a memory
76  * allocation fails, data stop being appended to the buffer, but the length
77  * is still updated. This situation can be tested with
78  * av_bprint_is_complete().
79  *
80  * The AVBPrint.size_max field determines several possible behaviours:
81  * - `size_max = -1` (= `UINT_MAX`) or any large value will let the buffer be
82  * reallocated as necessary, with an amortized linear cost.
83  * - `size_max = 0` prevents writing anything to the buffer: only the total
84  * length is computed. The write operations can then possibly be repeated in
85  * a buffer with exactly the necessary size
86  * (using `size_init = size_max = len + 1`).
87  * - `size_max = 1` is automatically replaced by the exact size available in the
88  * structure itself, thus ensuring no dynamic memory allocation. The
89  * internal buffer is large enough to hold a reasonable paragraph of text,
90  * such as the current paragraph.
91  */
92 
93 FF_PAD_STRUCTURE(AVBPrint, 1024,
94  char *str; /**< string so far */
95  unsigned len; /**< length so far */
96  unsigned size; /**< allocated memory */
97  unsigned size_max; /**< maximum allocated memory */
98  char reserved_internal_buffer[1];
99 )
100 
101 /**
102  * @name Max size special values
103  * Convenience macros for special values for av_bprint_init() size_max
104  * parameter.
105  * @{
106  */
107 
108 /**
109  * Buffer will be reallocated as necessary, with an amortized linear cost.
110  */
111 #define AV_BPRINT_SIZE_UNLIMITED ((unsigned)-1)
112 /**
113  * Use the exact size available in the AVBPrint structure itself.
114  *
115  * Thus ensuring no dynamic memory allocation. The internal buffer is large
116  * enough to hold a reasonable paragraph of text, such as the current paragraph.
117  */
118 #define AV_BPRINT_SIZE_AUTOMATIC 1
119 /**
120  * Do not write anything to the buffer, only calculate the total length.
121  *
122  * The write operations can then possibly be repeated in a buffer with
123  * exactly the necessary size (using `size_init = size_max = AVBPrint.len + 1`).
124  */
125 #define AV_BPRINT_SIZE_COUNT_ONLY 0
126 /** @} */
127 
128 /**
129  * Init a print buffer.
130  *
131  * @param buf buffer to init
132  * @param size_init initial size (including the final 0)
133  * @param size_max maximum size;
134  * - `0` means do not write anything, just count the length
135  * - `1` is replaced by the maximum value for automatic storage
136  * any large value means that the internal buffer will be
137  * reallocated as needed up to that limit
138  * - `-1` is converted to `UINT_MAX`, the largest limit possible.
139  * Check also `AV_BPRINT_SIZE_*` macros.
140  */
141 void av_bprint_init(AVBPrint *buf, unsigned size_init, unsigned size_max);
142 
143 /**
144  * Init a print buffer using a pre-existing buffer.
145  *
146  * The buffer will not be reallocated.
147  *
148  * @param buf buffer structure to init
149  * @param buffer byte buffer to use for the string data
150  * @param size size of buffer
151  */
152 void av_bprint_init_for_buffer(AVBPrint *buf, char *buffer, unsigned size);
153 
154 /**
155  * Append a formatted string to a print buffer.
156  */
157 void av_bprintf(AVBPrint *buf, const char *fmt, ...) av_printf_format(2, 3);
158 
159 /**
160  * Append a formatted string to a print buffer.
161  */
162 void av_vbprintf(AVBPrint *buf, const char *fmt, va_list vl_arg);
163 
164 /**
165  * Append char c n times to a print buffer.
166  */
167 void av_bprint_chars(AVBPrint *buf, char c, unsigned n);
168 
169 /**
170  * Append data to a print buffer.
171  *
172  * param buf bprint buffer to use
173  * param data pointer to data
174  * param size size of data
175  */
176 void av_bprint_append_data(AVBPrint *buf, const char *data, unsigned size);
177 
178 struct tm;
179 /**
180  * Append a formatted date and time to a print buffer.
181  *
182  * param buf bprint buffer to use
183  * param fmt date and time format string, see strftime()
184  * param tm broken-down time structure to translate
185  *
186  * @note due to poor design of the standard strftime function, it may
187  * produce poor results if the format string expands to a very long text and
188  * the bprint buffer is near the limit stated by the size_max option.
189  */
190 void av_bprint_strftime(AVBPrint *buf, const char *fmt, const struct tm *tm);
191 
192 /**
193  * Allocate bytes in the buffer for external use.
194  *
195  * @param[in] buf buffer structure
196  * @param[in] size required size
197  * @param[out] mem pointer to the memory area
198  * @param[out] actual_size size of the memory area after allocation;
199  * can be larger or smaller than size
200  */
201 void av_bprint_get_buffer(AVBPrint *buf, unsigned size,
202  unsigned char **mem, unsigned *actual_size);
203 
204 /**
205  * Reset the string to "" but keep internal allocated data.
206  */
207 void av_bprint_clear(AVBPrint *buf);
208 
209 /**
210  * Test if the print buffer is complete (not truncated).
211  *
212  * It may have been truncated due to a memory allocation failure
213  * or the size_max limit (compare size and size_max if necessary).
214  */
215 static inline int av_bprint_is_complete(const AVBPrint *buf)
216 {
217  return buf->len < buf->size;
218 }
219 
220 /**
221  * Finalize a print buffer.
222  *
223  * The print buffer can no longer be used afterwards,
224  * but the len and size fields are still valid.
225  *
226  * @arg[out] ret_str if not NULL, used to return a permanent copy of the
227  * buffer contents, or NULL if memory allocation fails;
228  * if NULL, the buffer is discarded and freed
229  * @return 0 for success or error code (probably AVERROR(ENOMEM))
230  */
231 int av_bprint_finalize(AVBPrint *buf, char **ret_str);
232 
233 /**
234  * Escape the content in src and append it to dstbuf.
235  *
236  * @param dstbuf already inited destination bprint buffer
237  * @param src string containing the text to escape
238  * @param special_chars string containing the special characters which
239  * need to be escaped, can be NULL
240  * @param mode escape mode to employ, see AV_ESCAPE_MODE_* macros.
241  * Any unknown value for mode will be considered equivalent to
242  * AV_ESCAPE_MODE_BACKSLASH, but this behaviour can change without
243  * notice.
244  * @param flags flags which control how to escape, see AV_ESCAPE_FLAG_* macros
245  */
246 void av_bprint_escape(AVBPrint *dstbuf, const char *src, const char *special_chars,
247  enum AVEscapeMode mode, int flags);
248 
249 /** @} */
250 
251 #endif /* AVUTIL_BPRINT_H */
AV_BPRINT_SIZE_UNLIMITED
#define AV_BPRINT_SIZE_UNLIMITED
av_bprint_is_complete
static int av_bprint_is_complete(const AVBPrint *buf)
Test if the print buffer is complete (not truncated).
Definition: bprint.h:215
av_bprint_init
void av_bprint_init(AVBPrint *buf, unsigned size_init, unsigned size_max)
Definition: bprint.c:69
data
const char data[16]
Definition: mxf.c:146
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.
Definition: bprint.c:85
size_max
unsigned unsigned size_max
Definition: bprint.h:141
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.
Definition: bprint.c:263
av_printf_format
#define av_printf_format(fmtpos, attrpos)
Definition: attributes.h:161
FF_PAD_STRUCTURE
#define FF_PAD_STRUCTURE(name, size,...)
Define a structure with extra padding to a fixed size This helps ensuring binary compatibility with f...
Definition: bprint.h:48
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.
Definition: bprint.c:176
c
Undefined Behavior In the C some operations are like signed integer dereferencing freed accessing outside allocated Undefined Behavior must not occur in a C it is not safe even if the output of undefined operations is unused The unsafety may seem nit picking but Optimizing compilers have in fact optimized code on the assumption that no undefined Behavior occurs Optimizing code based on wrong assumptions can and has in some cases lead to effects beyond the output of computations The signed integer overflow problem in speed critical code Code which is highly optimized and works with signed integers sometimes has the problem that often the output of the computation does not c
Definition: undefined.txt:32
av_bprint_finalize
int av_bprint_finalize(AVBPrint *buf, char **ret_str)
Finalize a print buffer.
Definition: bprint.c:235
size
int size
Definition: twinvq_data.h:10344
attributes.h
size_init
unsigned size_init
Definition: bprint.h:141
av_bprintf
void av_bprintf(AVBPrint *buf, const char *fmt,...) av_printf_format(2
Append a formatted string to a print buffer.
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.
Definition: bprint.c:218
len
int len
Definition: vorbis_enc_data.h:426
ret_str
static const char * ret_str(int v)
Definition: seek.c:34
buffer
the frame and frame reference mechanism is intended to as much as expensive copies of that data while still allowing the filters to produce correct results The data is stored in buffers represented by AVFrame structures Several references can point to the same frame buffer
Definition: filter_design.txt:49
av_vbprintf
void void av_vbprintf(AVBPrint *buf, const char *fmt, va_list vl_arg)
Append a formatted string to a print buffer.
Definition: bprint.c:117
mode
mode
Definition: ebur128.h:83
av_bprint_clear
void av_bprint_clear(AVBPrint *buf)
Reset the string to "" but keep internal allocated data.
Definition: bprint.c:227
src
INIT_CLIP pixel * src
Definition: h264pred_template.c:418
convert_header.str
string str
Definition: convert_header.py:20
flags
#define flags(name, subs,...)
Definition: cbs_av1.c:561
av_bprint_chars
void av_bprint_chars(AVBPrint *buf, char c, unsigned n)
Append char c n times to a print buffer.
Definition: bprint.c:140
AVEscapeMode
AVEscapeMode
Definition: avstring.h:324
avstring.h
av_bprint_append_data
void av_bprint_append_data(AVBPrint *buf, const char *data, unsigned size)
Append data to a print buffer.
Definition: bprint.c:158