aboutsummaryrefslogtreecommitdiffstatshomepage
path: root/libraries/eina/src/include/eina_str.h
diff options
context:
space:
mode:
Diffstat (limited to 'libraries/eina/src/include/eina_str.h')
-rw-r--r--libraries/eina/src/include/eina_str.h325
1 files changed, 0 insertions, 325 deletions
diff --git a/libraries/eina/src/include/eina_str.h b/libraries/eina/src/include/eina_str.h
deleted file mode 100644
index 2913fbf..0000000
--- a/libraries/eina/src/include/eina_str.h
+++ /dev/null
@@ -1,325 +0,0 @@
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 frequentely 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 * NUL-terminated string @p src to @p dst, NUL-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 NULL byte is found in the first
101 * @p siz bytes of src.
102 */
103EAPI 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 NUL 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 */
120EAPI 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 */
134EAPI 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 */
147EAPI 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 */
159EAPI 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.
167 * @return A newly-allocated NULL-terminated array of strings or NULL if it
168 * fails to allocate the array.
169 *
170 * This functin splits @p string into a maximum of @p max_tokens pieces,
171 * using the given delimiter @p delimiter. @p delimiter is not included in any
172 * of the resulting strings, unless @p max_tokens is reached. If
173 * @p max_tokens is less than @c 1, the string is splitted completely. If
174 * @p max_tokens is reached, the last string in the returned string
175 * array contains the remainder of string. The returned value is a
176 * newly allocated NULL-terminated array of strings or NULL if it fails to
177 * allocate the array. To free it, free the first element of the array and the
178 * array itself.
179 *
180 * @note If you need the number of elements in the returned array see
181 * eina_str_split_full().
182 */
183EAPI char **eina_str_split(const char *string, const char *delimiter, int max_tokens) EINA_ARG_NONNULL(1, 2) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
184
185/**
186 * @brief Split a string using a delimiter and returns number of elements.
187 *
188 * @param string The string to split.
189 * @param delimiter The string which specifies the places at which to split the string.
190 * @param max_tokens The maximum number of strings to split string into.
191 * @param elements Where to return the number of elements in returned
192 * array (not counting the terminating @c NULL). May be @c NULL.
193 * @return A newly-allocated NULL-terminated array of strings or NULL if it
194 * fails to allocate the array.
195 *
196 * This function splits @p string into a maximum of @p max_tokens pieces,
197 * using the given delimiter @p delimiter. @p delimiter is not included in any
198 * of the resulting strings, unless @p max_tokens is reached. If
199 * @p max_tokens is less than @c 1, the string is splitted completely. If
200 * @p max_tokens is reached, the last string in the returned string
201 * array contains the remainder of string. The returned value is a
202 * newly allocated NULL-terminated array of strings or NULL if it fails to
203 * allocate the array. To free it, free the first element of the array and the
204 * array itself.
205 *
206 * @see eina_str_split()
207 */
208EAPI 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;
209
210
211/**
212 * @brief Join two strings of known length.
213 *
214 * @param dst The buffer to store the result.
215 * @param size Size (in byte) of the buffer.
216 * @param sep The separator character to use.
217 * @param a First string to use, before @p sep.
218 * @param a_len length of @p a.
219 * @param b Second string to use, after @p sep.
220 * @param b_len length of @p b.
221 * @return The number of characters printed.
222 *
223 * This function joins the strings @p a and @p b (in that order) and
224 * separate them with @p sep. The result is stored in the buffer
225 * @p dst and at most @p size - 1 characters will be written and the
226 * string is NULL-terminated. @p a_len is the length of @p a (not
227 * including '\\0') and @p b_len is the length of @p b (not including
228 * '\\0'). This function returns the number of characters printed (not
229 * including the trailing '\\0' used to end output to strings). Just
230 * like snprintf(), it will not write more than @p size bytes, thus a
231 * returned value of @p size or more means that the output was
232 * truncated.
233 *
234 * @see eina_str_join()
235 * @see eina_str_join_static()
236 */
237EAPI 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);
238
239
240/**
241 * @brief Use Iconv to convert a text string from one encoding to another.
242 *
243 * @param enc_from Encoding to convert from.
244 * @param enc_to Encoding to convert to.
245 * @param text The text to convert.
246 * @return The converted text.
247 *
248 * This function converts @p text, encoded in @p enc_from. On success,
249 * the converted text is returned and is encoded in @p enc_to. On
250 * failure, @c NULL is returned. Iconv is used to convert @p text. If
251 * Iconv is not available, @c NULL is returned. When not used anymore,
252 * the returned value must be freed.
253 */
254EAPI 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);
255
256
257/**
258 * @brief Escape slashes, spaces and apostrophes in strings.
259 *
260 * @param str The string to escape.
261 * @return The escaped string.
262 *
263 * Escaping is done by adding a slash "\" before any occurrence of slashes "\",
264 * spaces " " or apostrophes "'". This function returns a newly allocated
265 * escaped string on success, @c NULL on failure. When not used anymore, the
266 * returned value must be freed.
267 */
268EAPI char *eina_str_escape(const char *str) EINA_WARN_UNUSED_RESULT EINA_MALLOC EINA_ARG_NONNULL(1);
269
270
271/**
272 * @brief Lowercase all the characters in range [A-Z] in the given string.
273 *
274 * @param str The string to lowercase.
275 *
276 * This function modifies the original string, changing all characters
277 * in [A-Z] to lowercase. If @p str is @c NULL or is an empty string,
278 * this function does nothing.
279 */
280EAPI void eina_str_tolower(char **str);
281
282/**
283 * @brief Uppercase all the characters in range [a-z] in the given string.
284 *
285 * @param str The string to uppercase.
286 *
287 * This function modifies the original string, changing all characters
288 * in [a-z] to uppercase. If @p str is @c NULL or is an empty string,
289 * this function does nothing.
290 */
291EAPI void eina_str_toupper(char **str);
292
293static 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);
294
295/**
296 * @def eina_str_join_static(dst, sep, a, b)
297 * @brief Join two static strings and store the result in a static buffer.
298 *
299 * @param dst The buffer to store the result.
300 * @param sep The separator character to use.
301 * @param a First string to use, before @p sep.
302 * @param b Second string to use, after @p sep.
303 * @return The number of characters printed.
304 *
305 * This function is similar to eina_str_join_len(), but will assume
306 * string sizes are know using sizeof(X).
307 *
308 * @see eina_str_join()
309 * @see eina_str_join_static()
310 */
311#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)
312
313static inline size_t eina_strlen_bounded(const char *str, size_t maxlen) EINA_PURE EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1);
314
315#include "eina_inline_str.x"
316
317/**
318 * @}
319 */
320
321/**
322 * @}
323 */
324
325#endif /* EINA_STR_H */