doc
c_string.h
Go to the documentation of this file.
1 /*
2  * cynapses libc functions
3  *
4  * Copyright (c) 2008-2013 by Andreas Schneider <asn@cryptomilk.org>
5  * Copyright (c) 2012-2013 by Klaas Freitag <freitag@owncloud.com>
6  *
7  * This library is free software; you can redistribute it and/or
8  * modify it under the terms of the GNU Lesser General Public
9  * License as published by the Free Software Foundation; either
10  * version 2.1 of the License, or (at your option) any later version.
11  *
12  * This library is distributed in the hope that it will be useful,
13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15  * Lesser General Public License for more details.
16  *
17  * You should have received a copy of the GNU Lesser General Public
18  * License along with this library; if not, write to the Free Software
19  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
20  */
21 
22 /**
23  * @file c_string.h
24  *
25  * @brief Interface of the cynapses string implementations
26  *
27  * @defgroup cynStringInternals cynapses libc string functions
28  * @ingroup cynLibraryAPI
29  *
30  * @{
31  */
32 #ifndef _C_STR_H
33 #define _C_STR_H
34 
35 #include "c_private.h"
36 #include "c_macro.h"
37 
38 #include <stdlib.h>
39 
40 struct c_strlist_s; typedef struct c_strlist_s c_strlist_t;
41 
42 /**
43  * @brief Structure for a stringlist
44  *
45  * Using a for loop you can access the strings saved in the vector.
46  *
47  * c_strlist_t strlist;
48  * int i;
49  * for (i = 0; i < strlist->count; i++) {
50  * printf("value: %s", strlist->vector[i];
51  * }
52  */
53 struct c_strlist_s {
54  /** The string vector */
55  char **vector;
56  /** The count of the strings saved in the vector */
57  size_t count;
58  /** Size of strings allocated */
59  size_t size;
60 };
61 
62 /**
63  * @brief Compare to strings if they are equal.
64  *
65  * @param a First string to compare.
66  * @param b Second string to compare.
67  *
68  * @return 1 if they are equal, 0 if not.
69  */
70 int c_streq(const char *a, const char *b);
71 
72 /**
73  * @brief Create a new stringlist.
74  *
75  * @param size Size to allocate.
76  *
77  * @return Pointer to the newly allocated stringlist. NULL if an error occured.
78  */
80 
81 /**
82  * @brief Expand the stringlist
83  *
84  * @param strlist Stringlist to expand
85  * @param size New size of the strlinglist to expand
86  *
87  * @return Pointer to the expanded stringlist. NULL if an error occured.
88  */
89 c_strlist_t *c_strlist_expand(c_strlist_t *strlist, size_t size);
90 
91 /**
92  * @brief Add a string to the stringlist.
93  *
94  * Duplicates the string and stores it in the stringlist.
95  *
96  * @param strlist Stringlist to add the string.
97  * @param string String to add.
98  *
99  * @return 0 on success, less than 0 and errno set if an error occured.
100  * ENOBUFS if the list is full.
101  */
102 int c_strlist_add(c_strlist_t *strlist, const char *string);
103 
104 /**
105  * @brief Destroy the memory of the stringlist.
106  *
107  * Frees the strings and the stringlist.
108  *
109  * @param strlist Stringlist to destroy
110  */
111 void c_strlist_destroy(c_strlist_t *strlist);
112 
113 /**
114  * @breif Replace a string with another string in a source string.
115  *
116  * @param src String to search for pattern.
117  *
118  * @param pattern Pattern to search for in the source string.
119  *
120  * @param repl The string which which should replace pattern if found.
121  *
122  * @return Return a pointer to the source string.
123  */
124 char *c_strreplace(char *src, const char *pattern, const char *repl);
125 
126 /**
127  * @brief Uppercase a string.
128  *
129  * @param str The String to uppercase.
130  *
131  * @return The malloced uppered string or NULL on error.
132  */
133 char *c_uppercase(const char* str);
134 
135 /**
136  * @brief Lowercase a string.
137  *
138  * @param str The String to lowercase.
139  *
140  * @return The malloced lowered string or NULL on error.
141  */
142 char *c_lowercase(const char* str);
143 
144 /**
145  * @brief Convert a platform locale string to utf8.
146  *
147  * This function is part of the multi platform abstraction of basic file
148  * operations to handle various platform encoding correctly.
149  *
150  * Instead of using the standard file operations the multi platform aliases
151  * defined in c_private.h have to be used instead.
152  *
153  * To convert path names returned by these functions to the internally used
154  * utf8 format this function has to be used. The returned string has to
155  * be freed by c_free_locale_string(). On some platforms this method allocates
156  * memory and on others not but it has never to be cared about.
157  *
158  * @param str The multibyte encoded string to convert
159  *
160  * @return The malloced converted string or NULL on error.
161  *
162  * @see c_free_locale_string()
163  * @see c_utf8_to_locale()
164  *
165  */
166  char* c_utf8_from_locale(const mbchar_t *str);
167 
168 /**
169  * @brief Convert a utf8 encoded string to platform specific locale.
170  *
171  * This function is part of the multi platform abstraction of basic file
172  * operations to handle various platform encoding correctly.
173  *
174  * Instead of using the standard file operations the multi platform aliases
175  * defined in c_private.h have to be used instead.
176  *
177  * To convert path names as input for the cross platform functions from the
178  * internally used utf8 format, this function has to be used.
179  * The returned string has to be freed by c_free_locale_string(). On some
180  * platforms this method allocates memory and on others not but it has never
181  * sto be cared about.
182  *
183  * @param str The utf8 string to convert.
184  *
185  * @return The malloced converted multibyte string or NULL on error.
186  *
187  * @see c_free_locale_string()
188  * @see c_utf8_from_locale()
189  *
190  */
191 mbchar_t* c_utf8_to_locale(const char *wstr);
192 
193 #if defined(_WIN32) || defined(WITH_ICONV)
194 
195 /**
196  * @brief Free buffer malloced by c_utf8_from_locale or c_utf8_to_locale().
197  *
198  * This function is part of the multi platform abstraction of basic file
199  * operations to handle various platform encoding correctly.
200  *
201  * Instead of using the standard file operations the multi platform aliases
202  * defined in c_private.h have to be used instead.
203  *
204  * This function frees the memory that was allocated by a previous call to
205  * c_utf8_to_locale() or c_utf8_from_locale().
206  *
207  * @param buf The buffer to free.
208  *
209  * @see c_utf8_from_locale(), c_utf8_to_locale()
210  *
211  */
212 #define c_free_locale_string(x) SAFE_FREE(x)
213 #else
214 #define c_free_locale_string(x) (void)x
215 #endif
216 
217 /**
218  * }@
219  */
220 #endif /* _C_STR_H */
221 
char * c_utf8_from_locale(const mbchar_t *str)
Convert a platform locale string to utf8.
int c_strlist_add(c_strlist_t *strlist, const char *string)
Add a string to the stringlist.
int c_streq(const char *a, const char *b)
Compare to strings if they are equal.
char * c_uppercase(const char *str)
Uppercase a string.
char * c_strreplace(char *src, const char *pattern, const char *repl)
Replace a string with another string in a source string.
char mbchar_t
Definition: c_private.h:112
cynapses libc macro definitions
c_strlist_t * c_strlist_new(size_t size)
Create a new stringlist.
char * c_lowercase(const char *str)
Lowercase a string.
void c_strlist_destroy(c_strlist_t *strlist)
Destroy the memory of the stringlist.
Structure for a stringlist.
Definition: c_string.h:53
off_t size
Definition: csync_private.h:35
size_t size
Size of strings allocated.
Definition: c_string.h:59
char ** vector
The string vector.
Definition: c_string.h:55
c_strlist_t * c_strlist_expand(c_strlist_t *strlist, size_t size)
Expand the stringlist.
mbchar_t * c_utf8_to_locale(const char *wstr)
Convert a utf8 encoded string to platform specific locale.
size_t count
The count of the strings saved in the vector.
Definition: c_string.h:57