/**
* @addtogroup Eina_String_Group String
*
- * @brief These functions provide useful C string management.
+ * @brief Provide useful functions for C string manipulation.
+ *
+ * This group of functions allow you to more easily manipulate strings, they
+ * provide functionality not available through string.h.
+ *
+ * @warning Since these functions modify the strings they can't be used with
+ * shared strings(eina_stringshare).
*
* @{
*/
* (unless @p siz is equal to 0). The returned value is the length of
* @p src. If the returned value is greater than @p siz, truncation
* occurred.
+ *
+ * @note The main difference between eina_strlcpy and strncpy is that this
+ * ensures @p dst is NULL terminated even if no NULL byte is found in the first
+ * @p siz bytes of src.
*/
EAPI size_t eina_strlcpy(char *dst, const char *src, size_t siz) EINA_ARG_NONNULL(1, 2);
* @param ext The extension to check for.
* @return #EINA_TRUE if the string has the given extension, #EINA_FALSE otherwise.
*
- * This function does the same like eina_str_has_suffix(), but with a
- * case insensitive compare.
+ * This function does the same as eina_str_has_suffix(), except it's case
+ * insensitive.
*/
EAPI Eina_Bool eina_str_has_extension(const char *str, const char *ext) EINA_PURE EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT;
* newly allocated NULL-terminated array of strings or NULL if it fails to
* allocate the array. To free it, free the first element of the array and the
* array itself.
+ *
+ * @note If you need the number of elements in the returned array see
+ * eina_str_split_full().
*/
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;
/**
- * @brief Put a \ before and Space( ), \ or ' in a string.
+ * @brief Escape slashes, spaces and apostrophes in strings.
*
* @param str The string to escape.
* @return The escaped string.
*
- * This function returns a newly allocated escaped string on success,
- * @c NULL on failure. When not used anymore, the returned value must
- * be freed.
+ * Escaping is done by adding a slash "\" before any occurrence of slashes "\",
+ * spaces " " or apostrophes "'". This function returns a newly allocated
+ * escaped string on success, @c NULL on failure. When not used anymore, the
+ * returned value must be freed.
*/
EAPI char *eina_str_escape(const char *str) EINA_WARN_UNUSED_RESULT EINA_MALLOC EINA_ARG_NONNULL(1);