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 #ifndef AVUTIL_BPRINT_H
22 #define AVUTIL_BPRINT_H
23 
24 #include <stdarg.h>
25 
26 #include "attributes.h"
27 #include "avstring.h"
28 
29 /**
30  * Define a structure with extra padding to a fixed size
31  * This helps ensuring binary compatibility with future versions.
32  */
33 
34 #define FF_PAD_STRUCTURE(name, size, ...) \
35 struct ff_pad_helper_##name { __VA_ARGS__ }; \
36 typedef struct name { \
37  __VA_ARGS__ \
38  char reserved_padding[size - sizeof(struct ff_pad_helper_##name)]; \
39 } name;
40 
41 /**
42  * Buffer to print data progressively
43  *
44  * The string buffer grows as necessary and is always 0-terminated.
45  * The content of the string is never accessed, and thus is
46  * encoding-agnostic and can even hold binary data.
47  *
48  * Small buffers are kept in the structure itself, and thus require no
49  * memory allocation at all (unless the contents of the buffer is needed
50  * after the structure goes out of scope). This is almost as lightweight as
51  * declaring a local "char buf[512]".
52  *
53  * The length of the string can go beyond the allocated size: the buffer is
54  * then truncated, but the functions still keep account of the actual total
55  * length.
56  *
57  * In other words, buf->len can be greater than buf->size and records the
58  * total length of what would have been to the buffer if there had been
59  * enough memory.
60  *
61  * Append operations do not need to be tested for failure: if a memory
62  * allocation fails, data stop being appended to the buffer, but the length
63  * is still updated. This situation can be tested with
64  * av_bprint_is_complete().
65  *
66  * The size_max field determines several possible behaviours:
67  *
68  * size_max = -1 (= UINT_MAX) or any large value will let the buffer be
69  * reallocated as necessary, with an amortized linear cost.
70  *
71  * size_max = 0 prevents writing anything to the buffer: only the total
72  * length is computed. The write operations can then possibly be repeated in
73  * a buffer with exactly the necessary size
74  * (using size_init = size_max = len + 1).
75  *
76  * size_max = 1 is automatically replaced by the exact size available in the
77  * structure itself, thus ensuring no dynamic memory allocation. The
78  * internal buffer is large enough to hold a reasonable paragraph of text,
79  * such as the current paragraph.
80  */
81 
82 FF_PAD_STRUCTURE(AVBPrint, 1024,
83  char *str; /**< string so far */
84  unsigned len; /**< length so far */
85  unsigned size; /**< allocated memory */
86  unsigned size_max; /**< maximum allocated memory */
87  char reserved_internal_buffer[1];
88 )
89 
90 /**
91  * Convenience macros for special values for av_bprint_init() size_max
92  * parameter.
93  */
94 #define AV_BPRINT_SIZE_UNLIMITED ((unsigned)-1)
95 #define AV_BPRINT_SIZE_AUTOMATIC 1
96 #define AV_BPRINT_SIZE_COUNT_ONLY 0
97 
98 /**
99  * Init a print buffer.
100  *
101  * @param buf buffer to init
102  * @param size_init initial size (including the final 0)
103  * @param size_max maximum size;
104  * 0 means do not write anything, just count the length;
105  * 1 is replaced by the maximum value for automatic storage;
106  * any large value means that the internal buffer will be
107  * reallocated as needed up to that limit; -1 is converted to
108  * UINT_MAX, the largest limit possible.
109  * Check also AV_BPRINT_SIZE_* macros.
110  */
111 void av_bprint_init(AVBPrint *buf, unsigned size_init, unsigned size_max);
112 
113 /**
114  * Init a print buffer using a pre-existing buffer.
115  *
116  * The buffer will not be reallocated.
117  *
118  * @param buf buffer structure to init
119  * @param buffer byte buffer to use for the string data
120  * @param size size of buffer
121  */
122 void av_bprint_init_for_buffer(AVBPrint *buf, char *buffer, unsigned size);
123 
124 /**
125  * Append a formatted string to a print buffer.
126  */
127 void av_bprintf(AVBPrint *buf, const char *fmt, ...) av_printf_format(2, 3);
128 
129 /**
130  * Append a formatted string to a print buffer.
131  */
132 void av_vbprintf(AVBPrint *buf, const char *fmt, va_list vl_arg);
133 
134 /**
135  * Append char c n times to a print buffer.
136  */
137 void av_bprint_chars(AVBPrint *buf, char c, unsigned n);
138 
139 /**
140  * Append data to a print buffer.
141  *
142  * param buf bprint buffer to use
143  * param data pointer to data
144  * param size size of data
145  */
146 void av_bprint_append_data(AVBPrint *buf, const char *data, unsigned size);
147 
148 struct tm;
149 /**
150  * Append a formatted date and time to a print buffer.
151  *
152  * param buf bprint buffer to use
153  * param fmt date and time format string, see strftime()
154  * param tm broken-down time structure to translate
155  *
156  * @note due to poor design of the standard strftime function, it may
157  * produce poor results if the format string expands to a very long text and
158  * the bprint buffer is near the limit stated by the size_max option.
159  */
160 void av_bprint_strftime(AVBPrint *buf, const char *fmt, const struct tm *tm);
161 
162 /**
163  * Allocate bytes in the buffer for external use.
164  *
165  * @param[in] buf buffer structure
166  * @param[in] size required size
167  * @param[out] mem pointer to the memory area
168  * @param[out] actual_size size of the memory area after allocation;
169  * can be larger or smaller than size
170  */
171 void av_bprint_get_buffer(AVBPrint *buf, unsigned size,
172  unsigned char **mem, unsigned *actual_size);
173 
174 /**
175  * Reset the string to "" but keep internal allocated data.
176  */
177 void av_bprint_clear(AVBPrint *buf);
178 
179 /**
180  * Test if the print buffer is complete (not truncated).
181  *
182  * It may have been truncated due to a memory allocation failure
183  * or the size_max limit (compare size and size_max if necessary).
184  */
185 static inline int av_bprint_is_complete(const AVBPrint *buf)
186 {
187  return buf->len < buf->size;
188 }
189 
190 /**
191  * Finalize a print buffer.
192  *
193  * The print buffer can no longer be used afterwards,
194  * but the len and size fields are still valid.
195  *
196  * @arg[out] ret_str if not NULL, used to return a permanent copy of the
197  * buffer contents, or NULL if memory allocation fails;
198  * if NULL, the buffer is discarded and freed
199  * @return 0 for success or error code (probably AVERROR(ENOMEM))
200  */
201 int av_bprint_finalize(AVBPrint *buf, char **ret_str);
202 
203 /**
204  * Escape the content in src and append it to dstbuf.
205  *
206  * @param dstbuf already inited destination bprint buffer
207  * @param src string containing the text to escape
208  * @param special_chars string containing the special characters which
209  * need to be escaped, can be NULL
210  * @param mode escape mode to employ, see AV_ESCAPE_MODE_* macros.
211  * Any unknown value for mode will be considered equivalent to
212  * AV_ESCAPE_MODE_BACKSLASH, but this behaviour can change without
213  * notice.
214  * @param flags flags which control how to escape, see AV_ESCAPE_FLAG_* macros
215  */
216 void av_bprint_escape(AVBPrint *dstbuf, const char *src, const char *special_chars,
217  enum AVEscapeMode mode, int flags);
218 
219 #endif /* AVUTIL_BPRINT_H */
AV_BPRINT_SIZE_UNLIMITED
#define AV_BPRINT_SIZE_UNLIMITED
av_bprint_clear
void av_bprint_clear(AVBPrint *buf)
Reset the string to "" but keep internal allocated data.
Definition: bprint.c:227
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
av_bprint_init
void av_bprint_init(AVBPrint *buf, unsigned size_init, unsigned size_max)
Definition: bprint.c:69
n
int n
Definition: avisynth_c.h:760
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:34
ret_str
static const char * ret_str(int v)
Definition: seek.c:34
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
data
const char data[16]
Definition: mxf.c:91
av_bprintf
void av_bprintf(AVBPrint *buf, const char *fmt,...) av_printf_format(2
Append a formatted string to a print buffer.
mem
int mem
Definition: avisynth_c.h:916
fmt
const char * fmt
Definition: avisynth_c.h:861
src
#define src
Definition: vp8dsp.c:254
buf
void * buf
Definition: avisynth_c.h:766
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
size_max
unsigned unsigned size_max
Definition: bprint.h:111
av_printf_format
#define av_printf_format(fmtpos, attrpos)
Definition: attributes.h:155
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_is_complete
static int av_bprint_is_complete(const AVBPrint *buf)
Test if the print buffer is complete (not truncated).
Definition: bprint.h:185
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
size
int size
Definition: twinvq_data.h:11134
attributes.h
av_bprint_finalize
int av_bprint_finalize(AVBPrint *buf, char **ret_str)
Finalize a print buffer.
Definition: bprint.c:235
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
len
int len
Definition: vorbis_enc_data.h:452
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:265
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
mode
mode
Definition: ebur128.h:83
size_init
unsigned size_init
Definition: bprint.h:111
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
flags
#define flags(name, subs,...)
Definition: cbs_av1.c:565
AVEscapeMode
AVEscapeMode
Definition: avstring.h:313
avstring.h