ucx: comparison ucx/string.h

-:965fd17ed9cf
+:234920008754
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 */
+/**
+* Bounded string implementation.
+*
+* The UCX strings (<code>sstr_t</code>) provide an alternative to C strings.
+* The main difference to C strings is, that <code>sstr_t</code> does <b>not
+* need to be <code>NULL</code>-terminated</b>. Instead the length is stored
+* within the structure.
+*
+* When using <code>sstr_t</code>, developers must be full aware of what type
+* of string (<code>NULL</code>-terminated) or not) they are using, when
+* accessing the <code>char* ptr</code> directly.
+*
+* The UCX string module provides some common string functions, known from
+* standard libc, working with <code>sstr_t</code>.
+*
+* @file   string.h
+* @author Mike Becker
+* @author Olaf Wintermann
+*/
-#ifndef _SSTRING_H
+#ifndef UCX_STRING_H
-#define	_SSTRING_H
+#define	UCX_STRING_H
 #include "ucx.h"
 #include "allocator.h"
 #include <stddef.h>
-/* use macros for literals only */
+/** Shortcut for a <code>sstr_t struct</code> literal. */
-#define S(s) { (char*)s, sizeof(s)-1 }
+#define ST(s) { (char*)s, sizeof(s)-1 }
-#define ST(s) sstrn((char*)s, sizeof(s)-1)
+/** Shortcut for the conversion of a C string to a <code>sstr_t</code>. */
+#define S(s) sstrn((char*)s, sizeof(s)-1)
 #ifdef	__cplusplus
 extern "C" {
 #endif
-typedef struct sstring {
+/**
+* The UCX string structure.
+*/
+typedef struct {
+/** A reference to the string (<b>not necessarily  <code>NULL</code>
+* -terminated</b>) */
 char   *ptr;
+/** The length of the string */
 size_t length;
 } sstr_t;
-/*
+/**
-* creates a new sstr_t from a null terminated string
+* Creates a new sstr_t based on a C string.
+*
+* The length is implicitly inferred by using a call to <code>strlen()</code>.
 *
-* s  null terminated string
+* <b>Note:</b> the sstr_t will hold a <i>reference</i> to the C string. If you
+* do want a copy, use sstrdup() on the return value of this function.
+*
+* @param cstring the C string to wrap
+* @return a new sstr_t containing the C string
+*
+* @see sstrn()
 */
-sstr_t sstr(char *s);
+sstr_t sstr(char *cstring);
-/*
+/**
-* creates a new sstr_t from a string and length
+* Creates a new sstr_t of the specified length based on a C string.
 *
-* s  string
+* <b>Note:</b> the sstr_t will hold a <i>reference</i> to the C string. If you
-* n  length of string
+* do want a copy, use sstrdup() on the return value of this function.
+*
+* @param cstring  the C string to wrap
+* @param length   the length of the string
+* @return a new sstr_t containing the C string
+*
+* @see sstr()
+* @see S()
 */
-sstr_t sstrn(char *s, size_t n);
+sstr_t sstrn(char *cstring, size_t length);
-/*
+/**
-* gets the length of n sstr_t strings
+* Returns the cumulated length of all specified strings.
 *
-* n    number of strings
+* At least one string must be specified.
-* s    string
+*
-* ...  strings
+* <b>Attention:</b> if the count argument does not match the count of the
+* specified strings, the behavior is undefined.
+*
+* @param count    the total number of specified strings (so at least 1)
+* @param string   the first string
+* @param ...      all other strings
+* @return the cumulated length of all strings
 */
-size_t sstrnlen(size_t n, sstr_t s, ...);
+size_t sstrnlen(size_t count, sstr_t string, ...);
 /*
 * concatenates n strings
 *
 *
 * Returns NULL on error
 */
 sstr_t* sstrsplit(sstr_t s, sstr_t d, size_t *n);
+/**
+* Compares two UCX strings with standard <code>memcmp()</code>.
+*
+* At first it compares the sstr_t.length attribute of the two strings. The
+* <code>memcmp()</code> function is called, if and only if the lengths match.
+*
+* @param s1 the first string
+* @param s2 the second string
+* @return -1, if the length of s1 is less than the length of s2 or 1, if the
+* length of s1 is greater than the length of s2 or the result of
+* <code>memcmp()</code> otherwise (i.e. 0 if the strings match)
+*/
 int sstrcmp(sstr_t s1, sstr_t s2);
-sstr_t sstrdup(sstr_t s);
+/**
-sstr_t sstrdup_alloc(UcxAllocator *allocator, sstr_t s);
+* Creates a duplicate of the specified string.
+*
+* The new sstr_t will contain a copy allocated by standard
+* <code>malloc()</code>. So developers <b>MUST</b> pass the sstr_t.ptr to
+* <code>free()</code>.
+*
+* @param string the string to duplicate
+* @return a duplicate of the argument
+*/
+sstr_t sstrdup(sstr_t string);
+sstr_t sstrdupa(UcxAllocator *allocator, sstr_t s);
 sstr_t sstrtrim(sstr_t string);
 #ifdef	__cplusplus
 }
 #endif
-#endif	/* _SSTRING_H */
+#endif	/* UCX_STRING_H */

Mercurial > hg > ucx / file comparison

comparison: ucx/string.h

ucx/string.h