toolkit: comparison ucx/string.h

-:55adc92e7c09
+:80609f9675f1
 /*
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
 *
-* Copyright 2013 Olaf Wintermann. All rights reserved.
+* Copyright 2015 Olaf Wintermann. All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 *   1. Redistributions of source code must retain the above copyright
 * @param ...      all other strings
 * @return the cumulated length of all strings
 */
 size_t sstrnlen(size_t count, sstr_t string, ...);
+/**
-/**
+* Concatenates two or more strings.
-* Concatenates strings.
+*
-*
+* The resulting string will be allocated by standard <code>malloc()</code>.
-* At least one string must be specified and there must be enough memory
+* So developers <b>MUST</b> pass the sstr_t.ptr to <code>free()</code>.
-* available referenced by the destination sstr_t.ptr for this function to
+*
-* successfully concatenate all specified strings.
+* The sstr_t.ptr of the return value will <i>always</i> be <code>NULL</code>-
-*
+* terminated.
-* The sstr_t.length of the destination string specifies the capacity and
+*
-* should match the total memory available referenced by the destination
-* sstr_t.ptr. This function <i>never</i> copies data beyond the capacity and
-* does not modify any of the source strings.
-*
-* <b>Attention:</b>
-* <ul>
-*   <li>Any content in the destination string will be overwritten</li>
-*   <li>The destination sstr_t.ptr is <b>NOT</b>
-*       <code>NULL</code>-terminated</li>
-*   <li>The destination sstr_t.length is set to the total length of the
-*       concatenated strings</li>
-*   <li><i>Hint:</i> get a <code>NULL</code>-terminated string by performing
-*       <code>mystring.ptr[mystring.length]='\0'</code> after calling this
-*       function</li>
-* </ul>
-*
-* @param dest    new sstr_t with capacity information and allocated memory
 * @param count   the total number of strings to concatenate
-* @param src     the first string
+* @param s1      first string
-* @param ...     all other strings
+* @param s2      second string
-* @return the argument for <code>dest</code> is returned
+* @param ...     all remaining strings
-*/
+* @return the concatenated string
-sstr_t sstrncat(sstr_t dest, size_t count, sstr_t src, ...);
+*/
+sstr_t sstrcat(size_t count, sstr_t s1, sstr_t s2, ...);
+/**
+* Concatenates two or more strings using an UcxAllocator.
+*
+* See sstrcat() for details.
+*
+* @param a       the allocator to use
+* @param count   the total number of strings to concatenate
+* @param s1      first string
+* @param s2      second string
+* @param ...     all remaining strings
+* @return the concatenated string
+*/
+sstr_t sstrcat_a(UcxAllocator *a, size_t count, sstr_t s1, sstr_t s2, ...);
 /**
 * Returns a substring starting at the specified location.
 *
 *   <li>the string equals the delimeter</li>
 *   <li>memory allocation fails</li>
 * </ul>
 *
 * The integer referenced by <code>count</code> is used as input and determines
-* the maximum size of the resulting list, i.e. the maximum count of splits to
+* the maximum size of the resulting array, i.e. the maximum count of splits to
 * perform + 1.
 *
 * The integer referenced by <code>count</code> is also used as output and is
 * set to
 * <ul>
 *   <li>-2, on memory allocation errors</li>
 *   <li>-1, if either the string or the delimiter is an empty string</li>
 *   <li>0, if the string equals the delimiter</li>
 *   <li>1, if the string does not contain the delimiter</li>
-*   <li>the count of list items, otherwise</li>
+*   <li>the count of array items, otherwise</li>
 * </ul>
 *
 * If the string starts with the delimiter, the first item of the resulting
-* list will be an empty string.
+* array will be an empty string.
 *
 * If the string ends with the delimiter and the maximum list size is not
-* exceeded, the last list item will be an empty string.
+* exceeded, the last array item will be an empty string.
 *
-* <b>Attention:</b> All list items <b>AND</b> all sstr_t.ptr of the list
+* <b>Attention:</b> The array pointer <b>AND</b> all sstr_t.ptr of the array
 * items must be manually passed to <code>free()</code>. Use sstrsplit_a() with
 * an allocator to managed memory, to avoid this.
 *
 * @param string the string to split
 * @param delim  the delimiter string
-* @param count  IN: the maximum size of the resulting list (0 for an
+* @param count  IN: the maximum size of the resulting array (0 = no limit),
-*               unbounded list), OUT: the actual size of the list
+*               OUT: the actual size of the array
-* @return a list of the split strings as sstr_t array or
+* @return a sstr_t array containing the split strings or
 *         <code>NULL</code> on error
 *
 * @see sstrsplit_a()
 */
-sstr_t* sstrsplit(sstr_t string, sstr_t delim, size_t *count);
+sstr_t* sstrsplit(sstr_t string, sstr_t delim, ssize_t *count);
 /**
 * Performing sstrsplit() using an UcxAllocator.
 *
 * <i>Read the description of sstrsplit() for details.</i>
 *
-* The memory for the sstr_t.ptr pointers of the list items and the memory for
+* The memory for the sstr_t.ptr pointers of the array items and the memory for
 * the sstr_t array itself are allocated by using the UcxAllocator.malloc()
 * function.
 *
 * <b>Note:</b> the allocator is not used for memory that is freed within the
 * same call of this function (locally scoped variables).
 *
 * @param allocator the UcxAllocator used for allocating memory
 * @param string the string to split
 * @param delim  the delimiter string
-* @param count  IN: the maximum size of the resulting list (0 for an
+* @param count  IN: the maximum size of the resulting array (0 = no limit),
-*               unbounded list), OUT: the actual size of the list
+*               OUT: the actual size of the array
-* @return a list of the split strings as sstr_t array or
+* @return a sstr_t array containing the split strings or
 *         <code>NULL</code> on error
 *
 * @see sstrsplit()
 */
 sstr_t* sstrsplit_a(UcxAllocator *allocator, sstr_t string, sstr_t delim,
-size_t *count);
+ssize_t *count);
 /**
 * Compares two UCX strings with standard <code>memcmp()</code>.
 *
 * At first it compares the sstr_t.length attribute of the two strings. The
 * @param suffix the suffix the string should have
 * @return 1, if and only if the string has the specified suffix, 0 otherwise
 */
 int sstrsuffix(sstr_t string, sstr_t suffix);
+/**
+* Returns a lower case version of a string.
+*
+* This function creates a duplicate of the input string, first. See the
+* documentation of sstrdup() for the implications.
+*
+* @param string the input string
+* @return the resulting lower case string
+* @see sstrdup()
+*/
+sstr_t sstrlower(sstr_t string);
+/**
+* Returns a lower case version of a string.
+*
+* This function creates a duplicate of the input string, first. See the
+* documentation of sstrdup_a() for the implications.
+*
+* @param allocator the allocator used for duplicating the string
+* @param string the input string
+* @return the resulting lower case string
+* @see sstrdup_a()
+*/
+sstr_t sstrlower_a(UcxAllocator *allocator, sstr_t string);
+/**
+* Returns a upper case version of a string.
+*
+* This function creates a duplicate of the input string, first. See the
+* documentation of sstrdup() for the implications.
+*
+* @param string the input string
+* @return the resulting upper case string
+* @see sstrdup()
+*/
+sstr_t sstrupper(sstr_t string);
+/**
+* Returns a upper case version of a string.
+*
+* This function creates a duplicate of the input string, first. See the
+* documentation of sstrdup_a() for the implications.
+*
+* @param allocator the allocator used for duplicating the string
+* @param string the input string
+* @return the resulting upper case string
+* @see sstrdup_a()
+*/
+sstr_t sstrupper_a(UcxAllocator *allocator, sstr_t string);
 #ifdef	__cplusplus
 }
 #endif
 #endif	/* UCX_STRING_H */

Mercurial > hg > toolkit / file comparison

comparison: ucx/string.h

ucx/string.h