git.sesse.net Git - ffmpeg/blob - libavutil/avstring.h

   1 /*
   2  * Copyright (c) 2007 Mans Rullgard
   3  *
   4  * This file is part of Libav.
   5  *
   6  * Libav 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  * Libav 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 Libav; 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 "attributes.h"
  26
  27 /**
  28  * @addtogroup lavu_string
  29  * @{
  30  */
  31
  32 /**
  33  * Return non-zero if pfx is a prefix of str. If it is, *ptr is set to
  34  * the address of the first character in str after the prefix.
  35  *
  36  * @param str input string
  37  * @param pfx prefix to test
  38  * @param ptr updated if the prefix is matched inside str
  39  * @return non-zero if the prefix matches, zero otherwise
  40  */
  41 int av_strstart(const char *str, const char *pfx, const char **ptr);
  42
  43 /**
  44  * Return non-zero if pfx is a prefix of str independent of case. If
  45  * it is, *ptr is set to the address of the first character in str
  46  * after the prefix.
  47  *
  48  * @param str input string
  49  * @param pfx prefix to test
  50  * @param ptr updated if the prefix is matched inside str
  51  * @return non-zero if the prefix matches, zero otherwise
  52  */
  53 int av_stristart(const char *str, const char *pfx, const char **ptr);
  54
  55 /**
  56  * Locate the first case-independent occurrence in the string haystack
  57  * of the string needle.  A zero-length string needle is considered to
  58  * match at the start of haystack.
  59  *
  60  * This function is a case-insensitive version of the standard strstr().
  61  *
  62  * @param haystack string to search in
  63  * @param needle   string to search for
  64  * @return         pointer to the located match within haystack
  65  *                 or a null pointer if no match
  66  */
  67 char *av_stristr(const char *haystack, const char *needle);
  68
  69 /**
  70  * Locate the first occurrence of the string needle in the string haystack
  71  * where not more than hay_length characters are searched. A zero-length
  72  * string needle is considered to match at the start of haystack.
  73  *
  74  * This function is a length-limited version of the standard strstr().
  75  *
  76  * @param haystack   string to search in
  77  * @param needle     string to search for
  78  * @param hay_length length of string to search in
  79  * @return           pointer to the located match within haystack
  80  *                   or a null pointer if no match
  81  */
  82 char *av_strnstr(const char *haystack, const char *needle, size_t hay_length);
  83
  84 /**
  85  * Copy the string src to dst, but no more than size - 1 bytes, and
  86  * null-terminate dst.
  87  *
  88  * This function is the same as BSD strlcpy().
  89  *
  90  * @param dst destination buffer
  91  * @param src source string
  92  * @param size size of destination buffer
  93  * @return the length of src
  94  *
  95  * @warning since the return value is the length of src, src absolutely
  96  * _must_ be a properly 0-terminated string, otherwise this will read beyond
  97  * the end of the buffer and possibly crash.
  98  */
  99 size_t av_strlcpy(char *dst, const char *src, size_t size);
 100
 101 /**
 102  * Append the string src to the string dst, but to a total length of
 103  * no more than size - 1 bytes, and null-terminate dst.
 104  *
 105  * This function is similar to BSD strlcat(), but differs when
 106  * size <= strlen(dst).
 107  *
 108  * @param dst destination buffer
 109  * @param src source string
 110  * @param size size of destination buffer
 111  * @return the total length of src and dst
 112  *
 113  * @warning since the return value use the length of src and dst, these
 114  * absolutely _must_ be a properly 0-terminated strings, otherwise this
 115  * will read beyond the end of the buffer and possibly crash.
 116  */
 117 size_t av_strlcat(char *dst, const char *src, size_t size);
 118
 119 /**
 120  * Append output to a string, according to a format. Never write out of
 121  * the destination buffer, and always put a terminating 0 within
 122  * the buffer.
 123  * @param dst destination buffer (string to which the output is
 124  *  appended)
 125  * @param size total size of the destination buffer
 126  * @param fmt printf-compatible format string, specifying how the
 127  *  following parameters are used
 128  * @return the length of the string that would have been generated
 129  *  if enough space had been available
 130  */
 131 size_t av_strlcatf(char *dst, size_t size, const char *fmt, ...) av_printf_format(3, 4);
 132
 133 /**
 134  * Convert a number to a av_malloced string.
 135  */
 136 char *av_d2str(double d);
 137
 138 /**
 139  * Unescape the given string until a non escaped terminating char,
 140  * and return the token corresponding to the unescaped string.
 141  *
 142  * The normal \ and ' escaping is supported. Leading and trailing
 143  * whitespaces are removed, unless they are escaped with '\' or are
 144  * enclosed between ''.
 145  *
 146  * @param buf the buffer to parse, buf will be updated to point to the
 147  * terminating char
 148  * @param term a 0-terminated list of terminating chars
 149  * @return the malloced unescaped string, which must be av_freed by
 150  * the user, NULL in case of allocation failure
 151  */
 152 char *av_get_token(const char **buf, const char *term);
 153
 154 /**
 155  * Locale-independent conversion of ASCII characters to uppercase.
 156  */
 157 static inline int av_toupper(int c)
 158 {
 159     if (c >= 'a' && c <= 'z')
 160         c ^= 0x20;
 161     return c;
 162 }
 163
 164 /**
 165  * Locale-independent conversion of ASCII characters to lowercase.
 166  */
 167 static inline int av_tolower(int c)
 168 {
 169     if (c >= 'A' && c <= 'Z')
 170         c ^= 0x20;
 171     return c;
 172 }
 173
 174 /*
 175  * Locale-independent case-insensitive compare.
 176  * @note This means only ASCII-range characters are case-insensitive
 177  */
 178 int av_strcasecmp(const char *a, const char *b);
 179
 180 /**
 181  * Locale-independent case-insensitive compare.
 182  * @note This means only ASCII-range characters are case-insensitive
 183  */
 184 int av_strncasecmp(const char *a, const char *b, size_t n);
 185
 186
 187 /**
 188  * Thread safe basename.
 189  * @param path the path, on DOS both \ and / are considered separators.
 190  * @return pointer to the basename substring.
 191  */
 192 const char *av_basename(const char *path);
 193
 194 /**
 195  * Thread safe dirname.
 196  * @param path the path, on DOS both \ and / are considered separators.
 197  * @return the path with the separator replaced by the string terminator or ".".
 198  * @note the function may change the input string.
 199  */
 200 const char *av_dirname(char *path);
 201
 202 /**
 203  * @}
 204  */
 205
 206 #endif /* AVUTIL_AVSTRING_H */