diff options
Diffstat (limited to '')
-rw-r--r-- | libraries/eina/src/include/eina_str.h | 325 |
1 files changed, 325 insertions, 0 deletions
diff --git a/libraries/eina/src/include/eina_str.h b/libraries/eina/src/include/eina_str.h new file mode 100644 index 0000000..8b52ab2 --- /dev/null +++ b/libraries/eina/src/include/eina_str.h | |||
@@ -0,0 +1,325 @@ | |||
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 | */ | ||
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 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 | */ | ||
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 str The string to split. | ||
165 | * @param delim 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 str into a maximum of @p max_tokens pieces, | ||
171 | * using the given delimiter @p delim. @p delim 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 | */ | ||
183 | 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; | ||
184 | |||
185 | /** | ||
186 | * @brief Split a string using a delimiter and returns number of elements. | ||
187 | * | ||
188 | * @param str The string to split. | ||
189 | * @param delim 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 functin splits @p str into a maximum of @p max_tokens pieces, | ||
197 | * using the given delimiter @p delim. @p delim 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 | */ | ||
208 | 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; | ||
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 | */ | ||
237 | 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); | ||
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 | */ | ||
254 | 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); | ||
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 | */ | ||
268 | EAPI 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 | */ | ||
280 | EAPI 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 | */ | ||
291 | EAPI void eina_str_toupper(char **str); | ||
292 | |||
293 | 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); | ||
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 | |||
313 | static 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 */ | ||