1.1 --- a/ucx/string.h Wed Jul 17 12:32:03 2013 +0200
1.2 +++ b/ucx/string.h Wed Jul 17 15:56:01 2013 +0200
1.3 @@ -25,51 +25,98 @@
1.4 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
1.5 * POSSIBILITY OF SUCH DAMAGE.
1.6 */
1.7 +/**
1.8 + * Bounded string implementation.
1.9 + *
1.10 + * The UCX strings (<code>sstr_t</code>) provide an alternative to C strings.
1.11 + * The main difference to C strings is, that <code>sstr_t</code> does <b>not
1.12 + * need to be <code>NULL</code>-terminated</b>. Instead the length is stored
1.13 + * within the structure.
1.14 + *
1.15 + * When using <code>sstr_t</code>, developers must be full aware of what type
1.16 + * of string (<code>NULL</code>-terminated) or not) they are using, when
1.17 + * accessing the <code>char* ptr</code> directly.
1.18 + *
1.19 + * The UCX string module provides some common string functions, known from
1.20 + * standard libc, working with <code>sstr_t</code>.
1.21 + *
1.22 + * @file string.h
1.23 + * @author Mike Becker
1.24 + * @author Olaf Wintermann
1.25 + */
1.26
1.27 -#ifndef _SSTRING_H
1.28 -#define _SSTRING_H
1.29 +#ifndef UCX_STRING_H
1.30 +#define UCX_STRING_H
1.31
1.32 #include "ucx.h"
1.33 #include "allocator.h"
1.34 #include <stddef.h>
1.35
1.36 -/* use macros for literals only */
1.37 -#define S(s) { (char*)s, sizeof(s)-1 }
1.38 -#define ST(s) sstrn((char*)s, sizeof(s)-1)
1.39 +/** Shortcut for a <code>sstr_t struct</code> literal. */
1.40 +#define ST(s) { (char*)s, sizeof(s)-1 }
1.41 +/** Shortcut for the conversion of a C string to a <code>sstr_t</code>. */
1.42 +#define S(s) sstrn((char*)s, sizeof(s)-1)
1.43
1.44 #ifdef __cplusplus
1.45 extern "C" {
1.46 #endif
1.47
1.48 -typedef struct sstring {
1.49 +/**
1.50 + * The UCX string structure.
1.51 + */
1.52 +typedef struct {
1.53 + /** A reference to the string (<b>not necessarily <code>NULL</code>
1.54 + * -terminated</b>) */
1.55 char *ptr;
1.56 + /** The length of the string */
1.57 size_t length;
1.58 } sstr_t;
1.59
1.60 -/*
1.61 - * creates a new sstr_t from a null terminated string
1.62 +/**
1.63 + * Creates a new sstr_t based on a C string.
1.64 + *
1.65 + * The length is implicitly inferred by using a call to <code>strlen()</code>.
1.66 *
1.67 - * s null terminated string
1.68 + * <b>Note:</b> the sstr_t will hold a <i>reference</i> to the C string. If you
1.69 + * do want a copy, use sstrdup() on the return value of this function.
1.70 + *
1.71 + * @param cstring the C string to wrap
1.72 + * @return a new sstr_t containing the C string
1.73 + *
1.74 + * @see sstrn()
1.75 */
1.76 -sstr_t sstr(char *s);
1.77 +sstr_t sstr(char *cstring);
1.78
1.79 -/*
1.80 - * creates a new sstr_t from a string and length
1.81 +/**
1.82 + * Creates a new sstr_t of the specified length based on a C string.
1.83 *
1.84 - * s string
1.85 - * n length of string
1.86 + * <b>Note:</b> the sstr_t will hold a <i>reference</i> to the C string. If you
1.87 + * do want a copy, use sstrdup() on the return value of this function.
1.88 + *
1.89 + * @param cstring the C string to wrap
1.90 + * @param length the length of the string
1.91 + * @return a new sstr_t containing the C string
1.92 + *
1.93 + * @see sstr()
1.94 + * @see S()
1.95 */
1.96 -sstr_t sstrn(char *s, size_t n);
1.97 +sstr_t sstrn(char *cstring, size_t length);
1.98
1.99
1.100 -/*
1.101 - * gets the length of n sstr_t strings
1.102 +/**
1.103 + * Returns the cumulated length of all specified strings.
1.104 *
1.105 - * n number of strings
1.106 - * s string
1.107 - * ... strings
1.108 + * At least one string must be specified.
1.109 + *
1.110 + * <b>Attention:</b> if the count argument does not match the count of the
1.111 + * specified strings, the behavior is undefined.
1.112 + *
1.113 + * @param count the total number of specified strings (so at least 1)
1.114 + * @param string the first string
1.115 + * @param ... all other strings
1.116 + * @return the cumulated length of all strings
1.117 */
1.118 -size_t sstrnlen(size_t n, sstr_t s, ...);
1.119 +size_t sstrnlen(size_t count, sstr_t string, ...);
1.120
1.121
1.122 /*
1.123 @@ -115,10 +162,32 @@
1.124 */
1.125 sstr_t* sstrsplit(sstr_t s, sstr_t d, size_t *n);
1.126
1.127 +/**
1.128 + * Compares two UCX strings with standard <code>memcmp()</code>.
1.129 + *
1.130 + * At first it compares the sstr_t.length attribute of the two strings. The
1.131 + * <code>memcmp()</code> function is called, if and only if the lengths match.
1.132 + *
1.133 + * @param s1 the first string
1.134 + * @param s2 the second string
1.135 + * @return -1, if the length of s1 is less than the length of s2 or 1, if the
1.136 + * length of s1 is greater than the length of s2 or the result of
1.137 + * <code>memcmp()</code> otherwise (i.e. 0 if the strings match)
1.138 + */
1.139 int sstrcmp(sstr_t s1, sstr_t s2);
1.140
1.141 -sstr_t sstrdup(sstr_t s);
1.142 -sstr_t sstrdup_alloc(UcxAllocator *allocator, sstr_t s);
1.143 +/**
1.144 + * Creates a duplicate of the specified string.
1.145 + *
1.146 + * The new sstr_t will contain a copy allocated by standard
1.147 + * <code>malloc()</code>. So developers <b>MUST</b> pass the sstr_t.ptr to
1.148 + * <code>free()</code>.
1.149 + *
1.150 + * @param string the string to duplicate
1.151 + * @return a duplicate of the argument
1.152 + */
1.153 +sstr_t sstrdup(sstr_t string);
1.154 +sstr_t sstrdupa(UcxAllocator *allocator, sstr_t s);
1.155
1.156 sstr_t sstrtrim(sstr_t string);
1.157
1.158 @@ -126,4 +195,4 @@
1.159 }
1.160 #endif
1.161
1.162 -#endif /* _SSTRING_H */
1.163 +#endif /* UCX_STRING_H */
