]> git.sesse.net Git - ffmpeg/blob - libavutil/bprint.h
Merge commit '4cf84e254ae75b524e1cacae499a97d7cc9e5906'
[ffmpeg] / libavutil / bprint.h
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 */