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 
38 struct c_strlist_s; typedef struct c_strlist_s c_strlist_t;
39 
40 /**
41  * @brief Structure for a stringlist
42  *
43  * Using a for loop you can access the strings saved in the vector.
44  *
45  * c_strlist_t strlist;
46  * int i;
47  * for (i = 0; i < strlist->count; i++) {
48  * printf("value: %s", strlist->vector[i];
49  * }
50  */
51 struct c_strlist_s {
52  /** The string vector */
53  char **vector;
54  /** The count of the strings saved in the vector */
55  size_t count;
56  /** Size of strings allocated */
57  size_t size;
58 };
59 
60 /**
61  * @brief Compare to strings if they are equal.
62  *
63  * @param a First string to compare.
64  * @param b Second string to compare.
65  *
66  * @return 1 if they are equal, 0 if not.
67  */
68 int c_streq(const char *a, const char *b);
69 
70 /**
71  * @brief Create a new stringlist.
72  *
73  * @param size Size to allocate.
74  *
75  * @return Pointer to the newly allocated stringlist. NULL if an error occured.
76  */
78 
79 /**
80  * @brief Expand the stringlist
81  *
82  * @param strlist Stringlist to expand
83  * @param size New size of the strlinglist to expand
84  *
85  * @return Pointer to the expanded stringlist. NULL if an error occured.
86  */
87 c_strlist_t *c_strlist_expand(c_strlist_t *strlist, size_t size);
88 
89 /**
90  * @brief Add a string to the stringlist.
91  *
92  * Duplicates the string and stores it in the stringlist.
93  *
94  * @param strlist Stringlist to add the string.
95  * @param string String to add.
96  *
97  * @return 0 on success, less than 0 and errno set if an error occured.
98  * ENOBUFS if the list is full.
99  */
100 int c_strlist_add(c_strlist_t *strlist, const char *string);
101 
102 /**
103  * @brief Destroy the memory of the stringlist.
104  *
105  * Frees the strings and the stringlist.
106  *
107  * @param strlist Stringlist to destroy
108  */
109 void c_strlist_destroy(c_strlist_t *strlist);
110 
111 /**
112  * @breif Replace a string with another string in a source string.
113  *
114  * @param src String to search for pattern.
115  *
116  * @param pattern Pattern to search for in the source string.
117  *
118  * @param repl The string which which should replace pattern if found.
119  *
120  * @return Return a pointer to the source string.
121  */
122 char *c_strreplace(char *src, const char *pattern, const char *repl);
123 
124 /**
125  * @brief Uppercase a string.
126  *
127  * @param str The String to uppercase.
128  *
129  * @return The malloced uppered string or NULL on error.
130  */
131 char *c_uppercase(const char* str);
132 
133 /**
134  * @brief Lowercase a string.
135  *
136  * @param str The String to lowercase.
137  *
138  * @return The malloced lowered string or NULL on error.
139  */
140 char *c_lowercase(const char* str);
141 
142 /**
143  * @brief Convert a multibyte string to utf8 (Win32).
144  *
145  * @param str The multibyte encoded string to convert
146  *
147  * @return The malloced converted string or NULL on error.
148  */
149 const char* c_utf8(const _TCHAR *str);
150 
151 /**
152  * @brief Convert a utf8 encoded string to multibyte (Win32).
153  *
154  * @param str The utf8 string to convert.
155  *
156  * @return The malloced converted multibyte string or NULL on error.
157  */
158 const _TCHAR* c_multibyte(const char *wstr);
159 
160 /**
161  * @brief Free buffer malloced by c_utf8.
162  *
163  * @param buf The buffer to free.
164  *
165  */
166 void c_free_utf8(char* buf);
167 
168 /**
169  * @brief Free buffer malloced by c_multibyte.
170  *
171  * @param buf The buffer to free.
172  */
173 void c_free_multibyte(const _TCHAR* buf);
174 
175 /**
176  * }@
177  */
178 #endif /* _C_STR_H */
179