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