blob: c09b1ac1e1aa77686780694e7f45c4ad59b7dc5d
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 */ |
220 |