Wed, 17 Jul 2013 20:03:01 +0200
documented allocator + some further documentation for sstr_t
1 /*
2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
3 *
4 * Copyright 2013 Olaf Wintermann. All rights reserved.
5 *
6 * Redistribution and use in source and binary forms, with or without
7 * modification, are permitted provided that the following conditions are met:
8 *
9 * 1. Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 *
12 * 2. Redistributions in binary form must reproduce the above copyright
13 * notice, this list of conditions and the following disclaimer in the
14 * documentation and/or other materials provided with the distribution.
15 *
16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
17 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
20 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
23 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
26 * POSSIBILITY OF SUCH DAMAGE.
27 */
28 /**
29 * Bounded string implementation.
30 *
31 * The UCX strings (<code>sstr_t</code>) provide an alternative to C strings.
32 * The main difference to C strings is, that <code>sstr_t</code> does <b>not
33 * need to be <code>NULL</code>-terminated</b>. Instead the length is stored
34 * within the structure.
35 *
36 * When using <code>sstr_t</code>, developers must be full aware of what type
37 * of string (<code>NULL</code>-terminated) or not) they are using, when
38 * accessing the <code>char* ptr</code> directly.
39 *
40 * The UCX string module provides some common string functions, known from
41 * standard libc, working with <code>sstr_t</code>.
42 *
43 * @file string.h
44 * @author Mike Becker
45 * @author Olaf Wintermann
46 */
48 #ifndef UCX_STRING_H
49 #define UCX_STRING_H
51 #include "ucx.h"
52 #include "allocator.h"
53 #include <stddef.h>
55 /** Shortcut for a <code>sstr_t struct</code> literal. */
56 #define ST(s) { (char*)s, sizeof(s)-1 }
57 /** Shortcut for the conversion of a C string to a <code>sstr_t</code>. */
58 #define S(s) sstrn((char*)s, sizeof(s)-1)
60 #ifdef __cplusplus
61 extern "C" {
62 #endif
64 /**
65 * The UCX string structure.
66 */
67 typedef struct {
68 /** A reference to the string (<b>not necessarily <code>NULL</code>
69 * -terminated</b>) */
70 char *ptr;
71 /** The length of the string */
72 size_t length;
73 } sstr_t;
75 /**
76 * Creates a new sstr_t based on a C string.
77 *
78 * The length is implicitly inferred by using a call to <code>strlen()</code>.
79 *
80 * <b>Note:</b> the sstr_t will hold a <i>reference</i> to the C string. If you
81 * do want a copy, use sstrdup() on the return value of this function.
82 *
83 * @param cstring the C string to wrap
84 * @return a new sstr_t containing the C string
85 *
86 * @see sstrn()
87 */
88 sstr_t sstr(char *cstring);
90 /**
91 * Creates a new sstr_t of the specified length based on a C string.
92 *
93 * <b>Note:</b> the sstr_t will hold a <i>reference</i> to the C string. If you
94 * do want a copy, use sstrdup() on the return value of this function.
95 *
96 * @param cstring the C string to wrap
97 * @param length the length of the string
98 * @return a new sstr_t containing the C string
99 *
100 * @see sstr()
101 * @see S()
102 */
103 sstr_t sstrn(char *cstring, size_t length);
106 /**
107 * Returns the cumulated length of all specified strings.
108 *
109 * At least one string must be specified.
110 *
111 * <b>Attention:</b> if the count argument does not match the count of the
112 * specified strings, the behavior is undefined.
113 *
114 * @param count the total number of specified strings (so at least 1)
115 * @param string the first string
116 * @param ... all other strings
117 * @return the cumulated length of all strings
118 */
119 size_t sstrnlen(size_t count, sstr_t string, ...);
122 /*
123 * concatenates n strings
124 *
125 * n number of strings
126 * s new string with enough memory allocated
127 * ... strings
128 */
129 sstr_t sstrncat(size_t n, sstr_t s, sstr_t c1, ...);
132 /*
133 *
134 */
135 sstr_t sstrsubs(sstr_t s, size_t start);
137 /*
138 *
139 */
140 sstr_t sstrsubsl(sstr_t s, size_t start, size_t length);
142 /*
143 *
144 */
145 sstr_t sstrchr(sstr_t s, int c);
147 /*
148 * splits s into n parts
149 *
150 * s the string to split
151 * d the delimiter string
152 * n the maximum size of the resulting list
153 * a size of 0 indicates an unbounded list size
154 * the actual size of the list will be stored here
155 *
156 * Hint: use this value to avoid dynamic reallocation of the result list
157 *
158 * Returns a list of the split strings
159 * NOTE: this list needs to be freed manually after usage
160 *
161 * Returns NULL on error
162 */
163 sstr_t* sstrsplit(sstr_t s, sstr_t d, size_t *n);
165 /**
166 * Compares two UCX strings with standard <code>memcmp()</code>.
167 *
168 * At first it compares the sstr_t.length attribute of the two strings. The
169 * <code>memcmp()</code> function is called, if and only if the lengths match.
170 *
171 * @param s1 the first string
172 * @param s2 the second string
173 * @return -1, if the length of s1 is less than the length of s2 or 1, if the
174 * length of s1 is greater than the length of s2 or the result of
175 * <code>memcmp()</code> otherwise (i.e. 0 if the strings match)
176 */
177 int sstrcmp(sstr_t s1, sstr_t s2);
179 /**
180 * Creates a duplicate of the specified string.
181 *
182 * The new sstr_t will contain a copy allocated by standard
183 * <code>malloc()</code>. So developers <b>MUST</b> pass the sstr_t.ptr to
184 * <code>free()</code>.
185 *
186 * The sstr_t.ptr of the return value will <i>always</i> be <code>NULL</code>-
187 * terminated.
188 *
189 * @param string the string to duplicate
190 * @return a duplicate of the string
191 */
192 sstr_t sstrdup(sstr_t string);
194 /**
195 * Creates a duplicate of the specified string using an UcxAllocator.
196 *
197 * The new sstr_t will contain a copy allocated by the allocators
198 * ucx_allocator_malloc function. So it is implementation depended, whether the
199 * returned sstr_t.ptr pointer must be passed to the allocators
200 * ucx_allocator_free function manually.
201 *
202 * The sstr_t.ptr of the return value will <i>always</i> be <code>NULL</code>-
203 * terminated.
204 *
205 * @param allocator a valid instance of an UcxAllocator
206 * @param string the string to duplicate
207 * @return a duplicate of the string
208 */
209 sstr_t sstrdupa(UcxAllocator *allocator, sstr_t string);
211 /**
212 * Omits leading and trailing spaces.
213 *
214 * This function returns a new sstr_t containing a trimmed version of the
215 * specified string.
216 *
217 * <b>Note:</b> the new sstr_t references the same memory, thus you
218 * <b>MUST NOT</b> pass the sstr_t.ptr of the return value to
219 * <code>free()</code>. It is also highly recommended to avoid assignments like
220 * <code>mystr = sstrtrim(mystr);</code> as you lose the reference to the
221 * source string. Assignments of this type are only permitted, if the
222 * sstr_t.ptr of the source string does not need to be freed or if another
223 * reference to the source string exists.
224 *
225 * @param string the string that shall be trimmed
226 * @return a new sstr_t containing the trimmed string
227 */
228 sstr_t sstrtrim(sstr_t string);
230 #ifdef __cplusplus
231 }
232 #endif
234 #endif /* UCX_STRING_H */