FFmpeg
avstring.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2007 Mans Rullgard
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_AVSTRING_H
22 #define AVUTIL_AVSTRING_H
23 
24 #include <stddef.h>
25 #include <stdint.h>
26 #include "attributes.h"
27 #include "version.h"
28 
29 /**
30  * @addtogroup lavu_string
31  * @{
32  */
33 
34 /**
35  * Return non-zero if pfx is a prefix of str. If it is, *ptr is set to
36  * the address of the first character in str after the prefix.
37  *
38  * @param str input string
39  * @param pfx prefix to test
40  * @param ptr updated if the prefix is matched inside str
41  * @return non-zero if the prefix matches, zero otherwise
42  */
43 int av_strstart(const char *str, const char *pfx, const char **ptr);
44 
45 /**
46  * Return non-zero if pfx is a prefix of str independent of case. If
47  * it is, *ptr is set to the address of the first character in str
48  * after the prefix.
49  *
50  * @param str input string
51  * @param pfx prefix to test
52  * @param ptr updated if the prefix is matched inside str
53  * @return non-zero if the prefix matches, zero otherwise
54  */
55 int av_stristart(const char *str, const char *pfx, const char **ptr);
56 
57 /**
58  * Locate the first case-independent occurrence in the string haystack
59  * of the string needle. A zero-length string needle is considered to
60  * match at the start of haystack.
61  *
62  * This function is a case-insensitive version of the standard strstr().
63  *
64  * @param haystack string to search in
65  * @param needle string to search for
66  * @return pointer to the located match within haystack
67  * or a null pointer if no match
68  */
69 char *av_stristr(const char *haystack, const char *needle);
70 
71 /**
72  * Locate the first occurrence of the string needle in the string haystack
73  * where not more than hay_length characters are searched. A zero-length
74  * string needle is considered to match at the start of haystack.
75  *
76  * This function is a length-limited version of the standard strstr().
77  *
78  * @param haystack string to search in
79  * @param needle string to search for
80  * @param hay_length length of string to search in
81  * @return pointer to the located match within haystack
82  * or a null pointer if no match
83  */
84 char *av_strnstr(const char *haystack, const char *needle, size_t hay_length);
85 
86 /**
87  * Copy the string src to dst, but no more than size - 1 bytes, and
88  * null-terminate dst.
89  *
90  * This function is the same as BSD strlcpy().
91  *
92  * @param dst destination buffer
93  * @param src source string
94  * @param size size of destination buffer
95  * @return the length of src
96  *
97  * @warning since the return value is the length of src, src absolutely
98  * _must_ be a properly 0-terminated string, otherwise this will read beyond
99  * the end of the buffer and possibly crash.
100  */
101 size_t av_strlcpy(char *dst, const char *src, size_t size);
102 
103 /**
104  * Append the string src to the string dst, but to a total length of
105  * no more than size - 1 bytes, and null-terminate dst.
106  *
107  * This function is similar to BSD strlcat(), but differs when
108  * size <= strlen(dst).
109  *
110  * @param dst destination buffer
111  * @param src source string
112  * @param size size of destination buffer
113  * @return the total length of src and dst
114  *
115  * @warning since the return value use the length of src and dst, these
116  * absolutely _must_ be a properly 0-terminated strings, otherwise this
117  * will read beyond the end of the buffer and possibly crash.
118  */
119 size_t av_strlcat(char *dst, const char *src, size_t size);
120 
121 /**
122  * Append output to a string, according to a format. Never write out of
123  * the destination buffer, and always put a terminating 0 within
124  * the buffer.
125  * @param dst destination buffer (string to which the output is
126  * appended)
127  * @param size total size of the destination buffer
128  * @param fmt printf-compatible format string, specifying how the
129  * following parameters are used
130  * @return the length of the string that would have been generated
131  * if enough space had been available
132  */
133 size_t av_strlcatf(char *dst, size_t size, const char *fmt, ...) av_printf_format(3, 4);
134 
135 /**
136  * Get the count of continuous non zero chars starting from the beginning.
137  *
138  * @param s the string whose length to count
139  * @param len maximum number of characters to check in the string, that
140  * is the maximum value which is returned by the function
141  */
142 static inline size_t av_strnlen(const char *s, size_t len)
143 {
144  size_t i;
145  for (i = 0; i < len && s[i]; i++)
146  ;
147  return i;
148 }
149 
150 /**
151  * Print arguments following specified format into a large enough auto
152  * allocated buffer. It is similar to GNU asprintf().
153  * @param fmt printf-compatible format string, specifying how the
154  * following parameters are used.
155  * @return the allocated string
156  * @note You have to free the string yourself with av_free().
157  */
158 char *av_asprintf(const char *fmt, ...) av_printf_format(1, 2);
159 
160 #if FF_API_D2STR
161 /**
162  * Convert a number to an av_malloced string.
163  * @deprecated use av_asprintf() with "%f" or a more specific format
164  */
166 char *av_d2str(double d);
167 #endif
168 
169 /**
170  * Unescape the given string until a non escaped terminating char,
171  * and return the token corresponding to the unescaped string.
172  *
173  * The normal \ and ' escaping is supported. Leading and trailing
174  * whitespaces are removed, unless they are escaped with '\' or are
175  * enclosed between ''.
176  *
177  * @param buf the buffer to parse, buf will be updated to point to the
178  * terminating char
179  * @param term a 0-terminated list of terminating chars
180  * @return the malloced unescaped string, which must be av_freed by
181  * the user, NULL in case of allocation failure
182  */
183 char *av_get_token(const char **buf, const char *term);
184 
185 /**
186  * Split the string into several tokens which can be accessed by
187  * successive calls to av_strtok().
188  *
189  * A token is defined as a sequence of characters not belonging to the
190  * set specified in delim.
191  *
192  * On the first call to av_strtok(), s should point to the string to
193  * parse, and the value of saveptr is ignored. In subsequent calls, s
194  * should be NULL, and saveptr should be unchanged since the previous
195  * call.
196  *
197  * This function is similar to strtok_r() defined in POSIX.1.
198  *
199  * @param s the string to parse, may be NULL
200  * @param delim 0-terminated list of token delimiters, must be non-NULL
201  * @param saveptr user-provided pointer which points to stored
202  * information necessary for av_strtok() to continue scanning the same
203  * string. saveptr is updated to point to the next character after the
204  * first delimiter found, or to NULL if the string was terminated
205  * @return the found token, or NULL when no token is found
206  */
207 char *av_strtok(char *s, const char *delim, char **saveptr);
208 
209 /**
210  * Locale-independent conversion of ASCII isdigit.
211  */
212 static inline av_const int av_isdigit(int c)
213 {
214  return c >= '0' && c <= '9';
215 }
216 
217 /**
218  * Locale-independent conversion of ASCII isgraph.
219  */
220 static inline av_const int av_isgraph(int c)
221 {
222  return c > 32 && c < 127;
223 }
224 
225 /**
226  * Locale-independent conversion of ASCII isspace.
227  */
228 static inline av_const int av_isspace(int c)
229 {
230  return c == ' ' || c == '\f' || c == '\n' || c == '\r' || c == '\t' ||
231  c == '\v';
232 }
233 
234 /**
235  * Locale-independent conversion of ASCII characters to uppercase.
236  */
237 static inline av_const int av_toupper(int c)
238 {
239  if (c >= 'a' && c <= 'z')
240  c ^= 0x20;
241  return c;
242 }
243 
244 /**
245  * Locale-independent conversion of ASCII characters to lowercase.
246  */
247 static inline av_const int av_tolower(int c)
248 {
249  if (c >= 'A' && c <= 'Z')
250  c ^= 0x20;
251  return c;
252 }
253 
254 /**
255  * Locale-independent conversion of ASCII isxdigit.
256  */
257 static inline av_const int av_isxdigit(int c)
258 {
259  c = av_tolower(c);
260  return av_isdigit(c) || (c >= 'a' && c <= 'f');
261 }
262 
263 /**
264  * Locale-independent case-insensitive compare.
265  * @note This means only ASCII-range characters are case-insensitive
266  */
267 int av_strcasecmp(const char *a, const char *b);
268 
269 /**
270  * Locale-independent case-insensitive compare.
271  * @note This means only ASCII-range characters are case-insensitive
272  */
273 int av_strncasecmp(const char *a, const char *b, size_t n);
274 
275 /**
276  * Locale-independent strings replace.
277  * @note This means only ASCII-range characters are replace
278  */
279 char *av_strireplace(const char *str, const char *from, const char *to);
280 
281 /**
282  * Thread safe basename.
283  * @param path the string to parse, on DOS both \ and / are considered separators.
284  * @return pointer to the basename substring.
285  * If path does not contain a slash, the function returns a copy of path.
286  * If path is a NULL pointer or points to an empty string, a pointer
287  * to a string "." is returned.
288  */
289 const char *av_basename(const char *path);
290 
291 /**
292  * Thread safe dirname.
293  * @param path the string to parse, on DOS both \ and / are considered separators.
294  * @return A pointer to a string that's the parent directory of path.
295  * If path is a NULL pointer or points to an empty string, a pointer
296  * to a string "." is returned.
297  * @note the function may modify the contents of the path, so copies should be passed.
298  */
299 const char *av_dirname(char *path);
300 
301 /**
302  * Match instances of a name in a comma-separated list of names.
303  * List entries are checked from the start to the end of the names list,
304  * the first match ends further processing. If an entry prefixed with '-'
305  * matches, then 0 is returned. The "ALL" list entry is considered to
306  * match all names.
307  *
308  * @param name Name to look for.
309  * @param names List of names.
310  * @return 1 on match, 0 otherwise.
311  */
312 int av_match_name(const char *name, const char *names);
313 
314 /**
315  * Append path component to the existing path.
316  * Path separator '/' is placed between when needed.
317  * Resulting string have to be freed with av_free().
318  * @param path base path
319  * @param component component to be appended
320  * @return new path or NULL on error.
321  */
322 char *av_append_path_component(const char *path, const char *component);
323 
325  AV_ESCAPE_MODE_AUTO, ///< Use auto-selected escaping mode.
326  AV_ESCAPE_MODE_BACKSLASH, ///< Use backslash escaping.
327  AV_ESCAPE_MODE_QUOTE, ///< Use single-quote escaping.
328  AV_ESCAPE_MODE_XML, ///< Use XML non-markup character data escaping.
329 };
330 
331 /**
332  * Consider spaces special and escape them even in the middle of the
333  * string.
334  *
335  * This is equivalent to adding the whitespace characters to the special
336  * characters lists, except it is guaranteed to use the exact same list
337  * of whitespace characters as the rest of libavutil.
338  */
339 #define AV_ESCAPE_FLAG_WHITESPACE (1 << 0)
340 
341 /**
342  * Escape only specified special characters.
343  * Without this flag, escape also any characters that may be considered
344  * special by av_get_token(), such as the single quote.
345  */
346 #define AV_ESCAPE_FLAG_STRICT (1 << 1)
347 
348 /**
349  * Within AV_ESCAPE_MODE_XML, additionally escape single quotes for single
350  * quoted attributes.
351  */
352 #define AV_ESCAPE_FLAG_XML_SINGLE_QUOTES (1 << 2)
353 
354 /**
355  * Within AV_ESCAPE_MODE_XML, additionally escape double quotes for double
356  * quoted attributes.
357  */
358 #define AV_ESCAPE_FLAG_XML_DOUBLE_QUOTES (1 << 3)
359 
360 
361 /**
362  * Escape string in src, and put the escaped string in an allocated
363  * string in *dst, which must be freed with av_free().
364  *
365  * @param dst pointer where an allocated string is put
366  * @param src string to escape, must be non-NULL
367  * @param special_chars string containing the special characters which
368  * need to be escaped, can be NULL
369  * @param mode escape mode to employ, see AV_ESCAPE_MODE_* macros.
370  * Any unknown value for mode will be considered equivalent to
371  * AV_ESCAPE_MODE_BACKSLASH, but this behaviour can change without
372  * notice.
373  * @param flags flags which control how to escape, see AV_ESCAPE_FLAG_ macros
374  * @return the length of the allocated string, or a negative error code in case of error
375  * @see av_bprint_escape()
376  */
378 int av_escape(char **dst, const char *src, const char *special_chars,
379  enum AVEscapeMode mode, int flags);
380 
381 #define AV_UTF8_FLAG_ACCEPT_INVALID_BIG_CODES 1 ///< accept codepoints over 0x10FFFF
382 #define AV_UTF8_FLAG_ACCEPT_NON_CHARACTERS 2 ///< accept non-characters - 0xFFFE and 0xFFFF
383 #define AV_UTF8_FLAG_ACCEPT_SURROGATES 4 ///< accept UTF-16 surrogates codes
384 #define AV_UTF8_FLAG_EXCLUDE_XML_INVALID_CONTROL_CODES 8 ///< exclude control codes not accepted by XML
385 
386 #define AV_UTF8_FLAG_ACCEPT_ALL \
387  AV_UTF8_FLAG_ACCEPT_INVALID_BIG_CODES|AV_UTF8_FLAG_ACCEPT_NON_CHARACTERS|AV_UTF8_FLAG_ACCEPT_SURROGATES
388 
389 /**
390  * Read and decode a single UTF-8 code point (character) from the
391  * buffer in *buf, and update *buf to point to the next byte to
392  * decode.
393  *
394  * In case of an invalid byte sequence, the pointer will be updated to
395  * the next byte after the invalid sequence and the function will
396  * return an error code.
397  *
398  * Depending on the specified flags, the function will also fail in
399  * case the decoded code point does not belong to a valid range.
400  *
401  * @note For speed-relevant code a carefully implemented use of
402  * GET_UTF8() may be preferred.
403  *
404  * @param codep pointer used to return the parsed code in case of success.
405  * The value in *codep is set even in case the range check fails.
406  * @param bufp pointer to the address the first byte of the sequence
407  * to decode, updated by the function to point to the
408  * byte next after the decoded sequence
409  * @param buf_end pointer to the end of the buffer, points to the next
410  * byte past the last in the buffer. This is used to
411  * avoid buffer overreads (in case of an unfinished
412  * UTF-8 sequence towards the end of the buffer).
413  * @param flags a collection of AV_UTF8_FLAG_* flags
414  * @return >= 0 in case a sequence was successfully read, a negative
415  * value in case of invalid sequence
416  */
418 int av_utf8_decode(int32_t *codep, const uint8_t **bufp, const uint8_t *buf_end,
419  unsigned int flags);
420 
421 /**
422  * Check if a name is in a list.
423  * @returns 0 if not found, or the 1 based index where it has been found in the
424  * list.
425  */
426 int av_match_list(const char *name, const char *list, char separator);
427 
428 /**
429  * See libc sscanf manual for more information.
430  * Locale-independent sscanf implementation.
431  */
432 int av_sscanf(const char *string, const char *format, ...);
433 
434 /**
435  * @}
436  */
437 
438 #endif /* AVUTIL_AVSTRING_H */
av_utf8_decode
av_warn_unused_result int av_utf8_decode(int32_t *codep, const uint8_t **bufp, const uint8_t *buf_end, unsigned int flags)
Read and decode a single UTF-8 code point (character) from the buffer in *buf, and update *buf to poi...
Definition: avstring.c:379
av_isxdigit
static av_const int av_isxdigit(int c)
Locale-independent conversion of ASCII isxdigit.
Definition: avstring.h:257
name
it s the only field you need to keep assuming you have a context There is some magic you don t need to care about around this just let it vf default minimum maximum flags name is the option name
Definition: writing_filters.txt:88
av_get_token
char * av_get_token(const char **buf, const char *term)
Unescape the given string until a non escaped terminating char, and return the token corresponding to...
Definition: avstring.c:154
av_stristr
char * av_stristr(const char *haystack, const char *needle)
Locate the first case-independent occurrence in the string haystack of the string needle.
Definition: avstring.c:59
av_strcasecmp
int av_strcasecmp(const char *a, const char *b)
Locale-independent case-insensitive compare.
Definition: avstring.c:218
av_isspace
static av_const int av_isspace(int c)
Locale-independent conversion of ASCII isspace.
Definition: avstring.h:228
av_const
#define av_const
Definition: attributes.h:84
b
#define b
Definition: input.c:41
av_d2str
char attribute_deprecated char * av_d2str(double d)
Convert a number to an av_malloced string.
Definition: avstring.c:143
av_basename
const char * av_basename(const char *path)
Thread safe basename.
Definition: avstring.c:263
av_append_path_component
char * av_append_path_component(const char *path, const char *component)
Append path component to the existing path.
Definition: avstring.c:307
av_escape
av_warn_unused_result int av_escape(char **dst, const char *src, const char *special_chars, enum AVEscapeMode mode, int flags)
Escape string in src, and put the escaped string in an allocated string in *dst, which must be freed ...
Definition: avstring.c:338
av_dirname
const char * av_dirname(char *path)
Thread safe dirname.
Definition: avstring.c:286
s
#define s(width, name)
Definition: cbs_vp9.c:256
format
Filter the word “frame” indicates either a video frame or a group of audio as stored in an AVFrame structure Format for each input and each output the list of supported formats For video that means pixel format For audio that means channel sample format(the sample packing is implied by the sample format) and sample rate. The lists are not just lists
av_strtok
char * av_strtok(char *s, const char *delim, char **saveptr)
Split the string into several tokens which can be accessed by successive calls to av_strtok().
Definition: avstring.c:189
from
const char * from
Definition: jacosubdec.c:66
to
const char * to
Definition: webvttdec.c:35
av_stristart
int av_stristart(const char *str, const char *pfx, const char **ptr)
Return non-zero if pfx is a prefix of str independent of case.
Definition: avstring.c:48
av_sscanf
int av_sscanf(const char *string, const char *format,...)
See libc sscanf manual for more information.
Definition: avsscanf.c:962
AV_ESCAPE_MODE_QUOTE
@ AV_ESCAPE_MODE_QUOTE
Use single-quote escaping.
Definition: avstring.h:327
av_match_list
int av_match_list(const char *name, const char *list, char separator)
Check if a name is in a list.
Definition: avstring.c:455
av_strireplace
char * av_strireplace(const char *str, const char *from, const char *to)
Locale-independent strings replace.
Definition: avstring.c:240
av_strnlen
size_t static size_t av_strnlen(const char *s, size_t len)
Get the count of continuous non zero chars starting from the beginning.
Definition: avstring.h:142
av_printf_format
#define av_printf_format(fmtpos, attrpos)
Definition: attributes.h:161
list
Filter the word “frame” indicates either a video frame or a group of audio as stored in an AVFrame structure Format for each input and each output the list of supported formats For video that means pixel format For audio that means channel sample they are references to shared objects When the negotiation mechanism computes the intersection of the formats supported at each end of a all references to both lists are replaced with a reference to the intersection And when a single format is eventually chosen for a link amongst the remaining list
Definition: filter_design.txt:25
AV_ESCAPE_MODE_AUTO
@ AV_ESCAPE_MODE_AUTO
Use auto-selected escaping mode.
Definition: avstring.h:325
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
FFFILE::buf
unsigned char * buf
Definition: avsscanf.c:39
av_strncasecmp
int av_strncasecmp(const char *a, const char *b, size_t n)
Locale-independent case-insensitive compare.
Definition: avstring.c:228
size
int size
Definition: twinvq_data.h:10344
AV_ESCAPE_MODE_XML
@ AV_ESCAPE_MODE_XML
Use XML non-markup character data escaping.
Definition: avstring.h:328
attribute_deprecated
#define attribute_deprecated
Definition: attributes.h:104
av_isgraph
static av_const int av_isgraph(int c)
Locale-independent conversion of ASCII isgraph.
Definition: avstring.h:220
av_isdigit
static av_const int av_isdigit(int c)
Locale-independent conversion of ASCII isdigit.
Definition: avstring.h:212
a
The reader does not expect b to be semantically here and if the code is changed by maybe adding a a division or other the signedness will almost certainly be mistaken To avoid this confusion a new type was SUINT is the C unsigned type but it holds a signed int to use the same example SUINT a
Definition: undefined.txt:41
attributes.h
av_strstart
int av_strstart(const char *str, const char *pfx, const char **ptr)
Return non-zero if pfx is a prefix of str.
Definition: avstring.c:37
av_warn_unused_result
#define av_warn_unused_result
Definition: attributes.h:64
i
#define i(width, name, range_min, range_max)
Definition: cbs_h2645.c:269
av_strlcatf
size_t av_strlcatf(char *dst, size_t size, const char *fmt,...) av_printf_format(3
Append output to a string, according to a format.
av_toupper
static av_const int av_toupper(int c)
Locale-independent conversion of ASCII characters to uppercase.
Definition: avstring.h:237
len
int len
Definition: vorbis_enc_data.h:426
version.h
av_strlcat
size_t av_strlcat(char *dst, const char *src, size_t size)
Append the string src to the string dst, but to a total length of no more than size - 1 bytes,...
Definition: avstring.c:96
av_strnstr
char * av_strnstr(const char *haystack, const char *needle, size_t hay_length)
Locate the first occurrence of the string needle in the string haystack where not more than hay_lengt...
Definition: avstring.c:72
av_asprintf
char * av_asprintf(const char *fmt,...) av_printf_format(1
Print arguments following specified format into a large enough auto allocated buffer.
mode
mode
Definition: ebur128.h:83
av_match_name
int av_match_name(const char *name, const char *names)
Match instances of a name in a comma-separated list of names.
Definition: avstring.c:356
src
INIT_CLIP pixel * src
Definition: h264pred_template.c:418
AV_ESCAPE_MODE_BACKSLASH
@ AV_ESCAPE_MODE_BACKSLASH
Use backslash escaping.
Definition: avstring.h:326
d
d
Definition: ffmpeg_filter.c:156
int32_t
int32_t
Definition: audioconvert.c:56
convert_header.str
string str
Definition: convert_header.py:20
flags
#define flags(name, subs,...)
Definition: cbs_av1.c:561
av_strlcpy
size_t av_strlcpy(char *dst, const char *src, size_t size)
Copy the string src to dst, but no more than size - 1 bytes, and null-terminate dst.
Definition: avstring.c:86
AVEscapeMode
AVEscapeMode
Definition: avstring.h:324
av_tolower
static av_const int av_tolower(int c)
Locale-independent conversion of ASCII characters to lowercase.
Definition: avstring.h:247