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