Commit | Line | Data |
---|---|---|
2ba45a60 DM |
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 | */ | |
f6fa7814 DM |
33 | |
34 | #define FF_PAD_STRUCTURE(name, size, ...) \ | |
35 | struct ff_pad_helper_##name { __VA_ARGS__ }; \ | |
36 | typedef struct name { \ | |
2ba45a60 | 37 | __VA_ARGS__ \ |
f6fa7814 DM |
38 | char reserved_padding[size - sizeof(struct ff_pad_helper_##name)]; \ |
39 | } name; | |
2ba45a60 DM |
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 | */ | |
f6fa7814 DM |
81 | |
82 | FF_PAD_STRUCTURE(AVBPrint, 1024, | |
2ba45a60 DM |
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]; | |
f6fa7814 | 88 | ) |
2ba45a60 DM |
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 | */ | |
f6fa7814 | 185 | static inline int av_bprint_is_complete(const AVBPrint *buf) |
2ba45a60 DM |
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 */ |