avstring.h 10 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317
  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. #ifndef AVUTIL_AVSTRING_H
  21. #define AVUTIL_AVSTRING_H
  22. #include <stddef.h>
  23. #include "attributes.h"
  24. /**
  25. * @addtogroup lavu_string
  26. * @{
  27. */
  28. /**
  29. * Return non-zero if pfx is a prefix of str. If it is, *ptr is set to
  30. * the address of the first character in str after the prefix.
  31. *
  32. * @param str input string
  33. * @param pfx prefix to test
  34. * @param ptr updated if the prefix is matched inside str
  35. * @return non-zero if the prefix matches, zero otherwise
  36. */
  37. int av_strstart(const char *str, const char *pfx, const char **ptr);
  38. /**
  39. * Return non-zero if pfx is a prefix of str independent of case. If
  40. * it is, *ptr is set to the address of the first character in str
  41. * after the prefix.
  42. *
  43. * @param str input string
  44. * @param pfx prefix to test
  45. * @param ptr updated if the prefix is matched inside str
  46. * @return non-zero if the prefix matches, zero otherwise
  47. */
  48. int av_stristart(const char *str, const char *pfx, const char **ptr);
  49. /**
  50. * Locate the first case-independent occurrence in the string haystack
  51. * of the string needle. A zero-length string needle is considered to
  52. * match at the start of haystack.
  53. *
  54. * This function is a case-insensitive version of the standard strstr().
  55. *
  56. * @param haystack string to search in
  57. * @param needle string to search for
  58. * @return pointer to the located match within haystack
  59. * or a null pointer if no match
  60. */
  61. char *av_stristr(const char *haystack, const char *needle);
  62. /**
  63. * Locate the first occurrence of the string needle in the string haystack
  64. * where not more than hay_length characters are searched. A zero-length
  65. * string needle is considered to match at the start of haystack.
  66. *
  67. * This function is a length-limited version of the standard strstr().
  68. *
  69. * @param haystack string to search in
  70. * @param needle string to search for
  71. * @param hay_length length of string to search in
  72. * @return pointer to the located match within haystack
  73. * or a null pointer if no match
  74. */
  75. char *av_strnstr(const char *haystack, const char *needle, size_t hay_length);
  76. /**
  77. * Copy the string src to dst, but no more than size - 1 bytes, and
  78. * null-terminate dst.
  79. *
  80. * This function is the same as BSD strlcpy().
  81. *
  82. * @param dst destination buffer
  83. * @param src source string
  84. * @param size size of destination buffer
  85. * @return the length of src
  86. *
  87. * @warning since the return value is the length of src, src absolutely
  88. * _must_ be a properly 0-terminated string, otherwise this will read beyond
  89. * the end of the buffer and possibly crash.
  90. */
  91. size_t av_strlcpy(char *dst, const char *src, size_t size);
  92. /**
  93. * Append the string src to the string dst, but to a total length of
  94. * no more than size - 1 bytes, and null-terminate dst.
  95. *
  96. * This function is similar to BSD strlcat(), but differs when
  97. * size <= strlen(dst).
  98. *
  99. * @param dst destination buffer
  100. * @param src source string
  101. * @param size size of destination buffer
  102. * @return the total length of src and dst
  103. *
  104. * @warning since the return value use the length of src and dst, these
  105. * absolutely _must_ be a properly 0-terminated strings, otherwise this
  106. * will read beyond the end of the buffer and possibly crash.
  107. */
  108. size_t av_strlcat(char *dst, const char *src, size_t size);
  109. /**
  110. * Append output to a string, according to a format. Never write out of
  111. * the destination buffer, and always put a terminating 0 within
  112. * the buffer.
  113. * @param dst destination buffer (string to which the output is
  114. * appended)
  115. * @param size total size of the destination buffer
  116. * @param fmt printf-compatible format string, specifying how the
  117. * following parameters are used
  118. * @return the length of the string that would have been generated
  119. * if enough space had been available
  120. */
  121. size_t av_strlcatf(char *dst, size_t size, const char *fmt, ...) av_printf_format(3, 4);
  122. /**
  123. * Print arguments following specified format into a large enough auto
  124. * allocated buffer. It is similar to GNU asprintf().
  125. * @param fmt printf-compatible format string, specifying how the
  126. * following parameters are used.
  127. * @return the allocated string
  128. * @note You have to free the string yourself with av_free().
  129. */
  130. char *av_asprintf(const char *fmt, ...) av_printf_format(1, 2);
  131. /**
  132. * Convert a number to a av_malloced string.
  133. */
  134. char *av_d2str(double d);
  135. /**
  136. * Unescape the given string until a non escaped terminating char,
  137. * and return the token corresponding to the unescaped string.
  138. *
  139. * The normal \ and ' escaping is supported. Leading and trailing
  140. * whitespaces are removed, unless they are escaped with '\' or are
  141. * enclosed between ''.
  142. *
  143. * @param buf the buffer to parse, buf will be updated to point to the
  144. * terminating char
  145. * @param term a 0-terminated list of terminating chars
  146. * @return the malloced unescaped string, which must be av_freed by
  147. * the user, NULL in case of allocation failure
  148. */
  149. char *av_get_token(const char **buf, const char *term);
  150. /**
  151. * Split the string into several tokens which can be accessed by
  152. * successive calls to av_strtok().
  153. *
  154. * A token is defined as a sequence of characters not belonging to the
  155. * set specified in delim.
  156. *
  157. * On the first call to av_strtok(), s should point to the string to
  158. * parse, and the value of saveptr is ignored. In subsequent calls, s
  159. * should be NULL, and saveptr should be unchanged since the previous
  160. * call.
  161. *
  162. * This function is similar to strtok_r() defined in POSIX.1.
  163. *
  164. * @param s the string to parse, may be NULL
  165. * @param delim 0-terminated list of token delimiters, must be non-NULL
  166. * @param saveptr user-provided pointer which points to stored
  167. * information necessary for av_strtok() to continue scanning the same
  168. * string. saveptr is updated to point to the next character after the
  169. * first delimiter found, or to NULL if the string was terminated
  170. * @return the found token, or NULL when no token is found
  171. */
  172. char *av_strtok(char *s, const char *delim, char **saveptr);
  173. /**
  174. * Locale-independent conversion of ASCII isdigit.
  175. */
  176. static inline int av_isdigit(int c)
  177. {
  178. return c >= '0' && c <= '9';
  179. }
  180. /**
  181. * Locale-independent conversion of ASCII isgraph.
  182. */
  183. static inline int av_isgraph(int c)
  184. {
  185. return c > 32 && c < 127;
  186. }
  187. /**
  188. * Locale-independent conversion of ASCII isspace.
  189. */
  190. static inline int av_isspace(int c)
  191. {
  192. return c == ' ' || c == '\f' || c == '\n' || c == '\r' || c == '\t' || c == '\v';
  193. }
  194. /**
  195. * Locale-independent conversion of ASCII characters to uppercase.
  196. */
  197. static inline int av_toupper(int c)
  198. {
  199. if (c >= 'a' && c <= 'z') {
  200. c ^= 0x20;
  201. }
  202. return c;
  203. }
  204. /**
  205. * Locale-independent conversion of ASCII characters to lowercase.
  206. */
  207. static inline int av_tolower(int c)
  208. {
  209. if (c >= 'A' && c <= 'Z') {
  210. c ^= 0x20;
  211. }
  212. return c;
  213. }
  214. /**
  215. * Locale-independent conversion of ASCII isxdigit.
  216. */
  217. static inline int av_isxdigit(int c)
  218. {
  219. c = av_tolower(c);
  220. return av_isdigit(c) || (c >= 'a' && c <= 'z');
  221. }
  222. /**
  223. * Locale-independent case-insensitive compare.
  224. * @note This means only ASCII-range characters are case-insensitive
  225. */
  226. int av_strcasecmp(const char *a, const char *b);
  227. /**
  228. * Locale-independent case-insensitive compare.
  229. * @note This means only ASCII-range characters are case-insensitive
  230. */
  231. int av_strncasecmp(const char *a, const char *b, size_t n);
  232. /**
  233. * Thread safe basename.
  234. * @param path the path, on DOS both \ and / are considered separators.
  235. * @return pointer to the basename substring.
  236. */
  237. const char *av_basename(const char *path);
  238. /**
  239. * Thread safe dirname.
  240. * @param path the path, on DOS both \ and / are considered separators.
  241. * @return the path with the separator replaced by the string terminator or ".".
  242. * @note the function may change the input string.
  243. */
  244. const char *av_dirname(char *path);
  245. enum AVEscapeMode {
  246. AV_ESCAPE_MODE_AUTO, ///< Use auto-selected escaping mode.
  247. AV_ESCAPE_MODE_BACKSLASH, ///< Use backslash escaping.
  248. AV_ESCAPE_MODE_QUOTE, ///< Use single-quote escaping.
  249. };
  250. /**
  251. * Consider spaces special and escape them even in the middle of the
  252. * string.
  253. *
  254. * This is equivalent to adding the whitespace characters to the special
  255. * characters lists, except it is guaranteed to use the exact same list
  256. * of whitespace characters as the rest of libavutil.
  257. */
  258. #define AV_ESCAPE_FLAG_WHITESPACE 0x01
  259. /**
  260. * Escape only specified special characters.
  261. * Without this flag, escape also any characters that may be considered
  262. * special by av_get_token(), such as the single quote.
  263. */
  264. #define AV_ESCAPE_FLAG_STRICT 0x02
  265. /**
  266. * Escape string in src, and put the escaped string in an allocated
  267. * string in *dst, which must be freed with av_free().
  268. *
  269. * @param dst pointer where an allocated string is put
  270. * @param src string to escape, must be non-NULL
  271. * @param special_chars string containing the special characters which
  272. * need to be escaped, can be NULL
  273. * @param mode escape mode to employ, see AV_ESCAPE_MODE_* macros.
  274. * Any unknown value for mode will be considered equivalent to
  275. * AV_ESCAPE_MODE_BACKSLASH, but this behaviour can change without
  276. * notice.
  277. * @param flags flags which control how to escape, see AV_ESCAPE_FLAG_ macros
  278. * @return the length of the allocated string, or a negative error code in case of error
  279. * @see av_bprint_escape()
  280. */
  281. int av_escape(char **dst, const char *src, const char *special_chars,
  282. enum AVEscapeMode mode, int flags);
  283. /**
  284. * @}
  285. */
  286. #endif /* AVUTIL_AVSTRING_H */