src/include/eina_str.h

   1 #ifndef _EINA_STR_H
   2 #define _EINA_STR_H
   3
   4 #include <stddef.h>
   5 #include <string.h>
   6
   7 #include "eina_types.h"
   8
   9 /**
  10  * @page tutorial_eina_string Eina String example
  11  * @dontinclude eina_str_01.c
  12  *
  13  * Whenever using eina we need to include it:
  14  * @skipline #include
  15  * @line #include
  16  *
  17  * In our main function we declare(and initialize) some variables and initialize
  18  * eina:
  19  * @until eina_init
  20  *
  21  * It's frequently necessary to split a string into its constituent parts,
  22  * eina_str_split() make's it easy to do so:
  23  * @until printf
  24  *
  25  * Another common need is to make a string uppercase or lowercase, so let's
  26  * create a string and make it uppercase and then make it lowercase again:
  27  * @until printf
  28  * @until printf
  29  *
  30  * Next we use eina to check if our @p names string starts or ends with some
  31  * values:
  32  * @until Has
  33  *
  34  * When strings will be used in a terminal(or a number of other places) it
  35  * necessary to escape certain characters that appear in them:
  36  * @until printf
  37  *
  38  * Much as we previously split a string we will now join two strings:
  39  * @until printf
  40  *
  41  * With strlcpy() we can copy what portion of the @p prologue fits in @p str and
  42  * be sure that it's still NULL terminated:
  43  * @until printf
  44  *
  45  * Since we are done with @p prologue and @p str we should free them:
  46  * @until free(str
  47  *
  48  * Finally we see strlcat in action:
  49  * @until printf("
  50  *
  51  * And then shut eina down and exit:
  52  * @until }
  53  * @example eina_str_01.c
  54  */
  55 /**
  56  * @addtogroup Eina_String_Group String
  57  *
  58  * @brief Provide useful functions for C string manipulation.
  59  *
  60  * This group of functions allow you to more easily manipulate strings, they
  61  * provide functionality not available through string.h.
  62  *
  63  * @warning Since these functions modify the strings they can't be used with
  64  * shared strings(eina_stringshare).
  65  *
  66  * See an example @ref tutorial_eina_string "here".
  67  */
  68
  69 /**
  70  * @addtogroup Eina_Tools_Group Tools
  71  *
  72  * For more information refer to the @ref tutorial_eina_string "string example".
  73  *
  74  * @{
  75  */
  76
  77 /**
  78  * @defgroup Eina_String_Group String
  79  *
  80  * @{
  81  */
  82
  83 /* strlcpy implementation for libc's lacking it */
  84
  85 /**
  86  * @brief Copy a c-string to another.
  87  *
  88  * @param dst The destination string.
  89  * @param src The source string.
  90  * @param siz The size of the destination string.
  91  * @return The length of the source string.
  92  *
  93  * This function copies up to @p siz - 1 characters from the
  94  * NULL-terminated string @p src to @p dst, NULL-terminating the result
  95  * (unless @p siz is equal to 0). The returned value is the length of
  96  * @p src. If the returned value is greater than @p siz, truncation
  97  * occurred.
  98  *
  99  * @note The main difference between eina_strlcpy and strncpy is that this
 100  * ensures @p dst is NULL-terminated even if no @c NULL byte is found in the first
 101  * @p siz bytes of src.
 102  */
 103 EAPI size_t          eina_strlcpy(char *dst, const char *src, size_t siz) EINA_ARG_NONNULL(1, 2);
 104
 105 /**
 106  * @brief Append a c-string.
 107  *
 108  * @param dst The destination string.
 109  * @param src The source string.
 110  * @param siz The size of the destination string.
 111  * @return The length of the source string plus MIN(siz, strlen(initial dst))
 112  *
 113  * This function appends @p src to @p dst of size @p siz (unlike
 114  * strncat, @p siz is the full size of @p dst, not space left).  At
 115  * most @p siz - 1 characters will be copied.  Always NULL-terminates
 116  * (unless @p siz <= strlen(dst)). This function returns strlen(src) +
 117  * MIN(siz, strlen(initial dst)). If the returned value is greater or
 118  * equal than @p siz, truncation occurred.
 119  */
 120 EAPI size_t          eina_strlcat(char *dst, const char *src, size_t siz) EINA_ARG_NONNULL(1, 2);
 121
 122
 123 /**
 124  * @brief Check if the given string has the given prefix.
 125  *
 126  * @param str The string to work with.
 127  * @param prefix The prefix to check for.
 128  * @return #EINA_TRUE if the string has the given prefix, #EINA_FALSE otherwise.
 129  *
 130  * This function returns #EINA_TRUE if @p str has the prefix
 131  * @p prefix, #EINA_FALSE otherwise. If the length of @p prefix is
 132  * greater than @p str, #EINA_FALSE is returned.
 133  */
 134 EAPI Eina_Bool       eina_str_has_prefix(const char *str, const char *prefix) EINA_PURE EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT;
 135
 136 /**
 137  * @brief Check if the given string has the given suffix.
 138  *
 139  * @param str The string to work with.
 140  * @param suffix The suffix to check for.
 141  * @return #EINA_TRUE if the string has the given suffix, #EINA_FALSE otherwise.
 142  *
 143  * This function returns #EINA_TRUE if @p str has the suffix
 144  * @p suffix, #EINA_FALSE otherwise. If the length of @p suffix is
 145  * greater than @p str, #EINA_FALSE is returned.
 146  */
 147 EAPI Eina_Bool       eina_str_has_suffix(const char *str, const char *suffix) EINA_PURE EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT;
 148
 149 /**
 150  * @brief Check if the given string has the given extension.
 151  *
 152  * @param str The string to work with.
 153  * @param ext The  extension to check for.
 154  * @return #EINA_TRUE if the string has the given extension, #EINA_FALSE otherwise.
 155  *
 156  * This function does the same as eina_str_has_suffix(), except it's case
 157  * insensitive.
 158  */
 159 EAPI Eina_Bool       eina_str_has_extension(const char *str, const char *ext) EINA_PURE EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT;
 160
 161 /**
 162  * @brief Split a string using a delimiter.
 163  *
 164  * @param string The string to split.
 165  * @param delimiter The string which specifies the places at which to split the string.
 166  * @param max_tokens The maximum number of strings to split string into, or a number less
 167  *                   than 1 to split as many times as possible. This parameter
 168  *                   IGNORES the added @c NULL terminator.
 169  * @return A newly-allocated NULL-terminated array of strings or @c NULL if it
 170  * fails to allocate the array.
 171  *
 172  * This function splits @p string into a maximum of @p max_tokens pieces,
 173  * using the given delimiter @p delimiter. @p delimiter is not included in any
 174  * of the resulting strings, unless @p max_tokens is reached. If
 175  * @p max_tokens is less than @c 1, the string is splitted as many times as possible. If
 176  * @p max_tokens is reached, the last string in the returned string
 177  * array contains the remainder of string. The returned value is a
 178  * newly allocated NULL-terminated array of strings or @c NULL if it fails to
 179  * allocate the array. To free it, free the first element of the array and the
 180  * array itself.
 181  *
 182  * @note If you need the number of elements in the returned array see
 183  * eina_str_split_full().
 184  */
 185 EAPI char          **eina_str_split(const char *string, const char *delimiter, int max_tokens) EINA_ARG_NONNULL(1, 2) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
 186
 187 /**
 188  * @brief Split a string using a delimiter and returns number of elements.
 189  *
 190  * @param string The string to split.
 191  * @param delimiter The string which specifies the places at which to split the string.
 192  * @param max_tokens The maximum number of strings to split string into, or a number less
 193  *                   than 1 to split as many times as possible. This parameter
 194  *                   IGNORES the added @c NULL terminator.
 195  * @param elements Where to return the number of elements in returned
 196  *        array. This array is guaranteed to be no greater than @p max_tokens, and
 197  *        it will NOT count the @c NULL terminator element.
 198  * @return A newly-allocated NULL-terminated array of strings or @c NULL if it
 199  * fails to allocate the array.
 200  *
 201  * This function splits @p string into a maximum of @p max_tokens pieces,
 202  * using the given delimiter @p delimiter. @p delimiter is not included in any
 203  * of the resulting strings, unless @p max_tokens is reached. If
 204  * @p max_tokens is less than @c 1, the string is splitted as many times as possible. If
 205  * @p max_tokens is reached, the last string in the returned string
 206  * array contains the remainder of string. The returned value is a
 207  * newly allocated NULL-terminated array of strings or @c NULL if it fails to
 208  * allocate the array. To free it, free the first element of the array and the
 209  * array itself.
 210  *
 211  * @note The actual size of the returned array, when @p elements returns greater than zero,
 212  *       will always be @p elements + 1. This is due to the @c NULL terminator element that
 213  *       is added to the array for safety. If it returns @c 6, the number of split strings returned
 214  *       will be 6, but the size of the array (including the @c NULL element) will actually be 7.
 215  *
 216  * @see eina_str_split()
 217  */
 218 EAPI char          **eina_str_split_full(const char *string, const char *delimiter, int max_tokens, unsigned int *elements) EINA_ARG_NONNULL(1, 2, 4) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
 219
 220
 221 /**
 222  * @brief Join two strings of known length.
 223  *
 224  * @param dst The buffer to store the result.
 225  * @param size Size (in byte) of the buffer.
 226  * @param sep The separator character to use.
 227  * @param a First string to use, before @p sep.
 228  * @param a_len length of @p a.
 229  * @param b Second string to use, after @p sep.
 230  * @param b_len length of @p b.
 231  * @return The number of characters printed.
 232  *
 233  * This function joins the strings @p a and @p b (in that order) and
 234  * separate them with @p sep. The result is stored in the buffer
 235  * @p dst and at most @p size - 1 characters will be written and the
 236  * string is NULL-terminated. @p a_len is the length of @p a (not
 237  * including '\\0') and @p b_len is the length of @p b (not including
 238  * '\\0'). This function returns the number of characters printed (not
 239  * including the trailing '\\0' used to end output to strings). Just
 240  * like snprintf(), it will not write more than @p size bytes, thus a
 241  * returned value of @p size or more means that the output was
 242  * truncated.
 243  *
 244  * @see eina_str_join()
 245  * @see eina_str_join_static()
 246  */
 247 EAPI size_t          eina_str_join_len(char *dst, size_t size, char sep, const char *a, size_t a_len, const char *b, size_t b_len) EINA_ARG_NONNULL(1, 4, 6);
 248
 249
 250 /**
 251  * @brief Use Iconv to convert a text string from one encoding to another.
 252  *
 253  * @param enc_from Encoding to convert from.
 254  * @param enc_to Encoding to convert to.
 255  * @param text The text to convert.
 256  * @return The converted text.
 257  *
 258  * This function converts @p text, encoded in @p enc_from. On success,
 259  * the converted text is returned and is encoded in @p enc_to. On
 260  * failure, @c NULL is returned. Iconv is used to convert @p text. If
 261  * Iconv is not available, @c NULL is returned. When not used anymore,
 262  * the returned value must be freed.
 263  */
 264 EAPI char           *eina_str_convert(const char *enc_from, const char *enc_to, const char *text) EINA_WARN_UNUSED_RESULT EINA_MALLOC EINA_ARG_NONNULL(1, 2, 3);
 265
 266
 267 /**
 268  * @brief Escape slashes, spaces and apostrophes in strings.
 269  *
 270  * @param str The string to escape.
 271  * @return The escaped string.
 272  *
 273  * Escaping is done by adding a slash "\" before any occurrence of slashes "\",
 274  * spaces " " or apostrophes "'". This function returns a newly allocated
 275  * escaped string on success, @c NULL on failure. When not used anymore, the
 276  * returned value must be freed.
 277  */
 278 EAPI char           *eina_str_escape(const char *str) EINA_WARN_UNUSED_RESULT EINA_MALLOC EINA_ARG_NONNULL(1);
 279
 280
 281 /**
 282  * @brief Lowercase all the characters in range [A-Z] in the given string.
 283  *
 284  * @param str The string to lowercase.
 285  *
 286  * This function modifies the original string, changing all characters
 287  * in [A-Z] to lowercase. If @p str is @c NULL or is an empty string,
 288  * this function does nothing.
 289  */
 290 EAPI void            eina_str_tolower(char **str);
 291
 292 /**
 293  * @brief Uppercase all the characters in range [a-z] in the given string.
 294  *
 295  * @param str The string to uppercase.
 296  *
 297  * This function modifies the original string, changing all characters
 298  * in [a-z] to uppercase. If @p str is @c NULL or is an empty string,
 299  * this function does nothing.
 300  */
 301 EAPI void            eina_str_toupper(char **str);
 302
 303 static inline size_t eina_str_join(char *dst, size_t size, char sep, const char *a, const char *b) EINA_ARG_NONNULL(1, 4, 5);
 304
 305 /**
 306  * @def eina_str_join_static(dst, sep, a, b)
 307  * @brief Join two static strings and store the result in a static buffer.
 308  *
 309  * @param dst The buffer to store the result.
 310  * @param sep The separator character to use.
 311  * @param a First string to use, before @p sep.
 312  * @param b Second string to use, after @p sep.
 313  * @return The number of characters printed.
 314  *
 315  * This function is similar to eina_str_join_len(), but will assume
 316  * string sizes are know using sizeof(X).
 317  *
 318  * @see eina_str_join()
 319  * @see eina_str_join_static()
 320  */
 321 #define eina_str_join_static(dst, sep, a, b) eina_str_join_len(dst, sizeof(dst), sep, a, (sizeof(a) > 0) ? sizeof(a) - 1 : 0, b, (sizeof(b) > 0) ? sizeof(b) - 1 : 0)
 322
 323 static inline size_t eina_strlen_bounded(const char *str, size_t maxlen) EINA_PURE EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
 324
 325 #include "eina_inline_str.x"
 326
 327 /**
 328  * @}
 329  */
 330
 331 /**
 332  * @}
 333  */
 334
 335 #endif /* EINA_STR_H */