diff -r 55adc92e7c09 -r 80609f9675f1 ucx/string.h --- a/ucx/string.h Tue Feb 16 17:39:33 2016 +0100 +++ b/ucx/string.h Mon May 23 12:28:32 2016 +0200 @@ -1,7 +1,7 @@ /* * 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: @@ -119,38 +119,36 @@ */ size_t sstrnlen(size_t count, sstr_t string, ...); +/** + * Concatenates two or more strings. + * + * The resulting string will be allocated by standard malloc(). + * So developers MUST pass the sstr_t.ptr to free(). + * + * The sstr_t.ptr of the return value will always be NULL- + * terminated. + * + * @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(size_t count, sstr_t s1, sstr_t s2, ...); /** - * Concatenates strings. - * - * At least one string must be specified and there must be enough memory - * available referenced by the destination sstr_t.ptr for this function to - * successfully concatenate all specified strings. - * - * 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 never copies data beyond the capacity and - * does not modify any of the source strings. + * Concatenates two or more strings using an UcxAllocator. * - * Attention: - * + * See sstrcat() for details. * - * @param dest new sstr_t with capacity information and allocated memory + * @param a the allocator to use * @param count the total number of strings to concatenate - * @param src the first string - * @param ... all other strings - * @return the argument for dest is returned + * @param s1 first string + * @param s2 second string + * @param ... all remaining strings + * @return the concatenated string */ -sstr_t sstrncat(sstr_t dest, size_t count, sstr_t src, ...); +sstr_t sstrcat_a(UcxAllocator *a, size_t count, sstr_t s1, sstr_t s2, ...); /** @@ -227,7 +225,7 @@ * * * The integer referenced by count 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 count is also used as output and is @@ -237,36 +235,36 @@ *
  • -1, if either the string or the delimiter is an empty string
    • *
  • 0, if the string equals the delimiter
    • *
  • 1, if the string does not contain the delimiter
    • - *
  • the count of list items, otherwise
    • + *
  • the count of array items, otherwise
    • * * * 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. * - * Attention: All list items AND all sstr_t.ptr of the list + * Attention: The array pointer AND all sstr_t.ptr of the array * items must be manually passed to free(). 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 - * unbounded list), OUT: the actual size of the list - * @return a list of the split strings as sstr_t array or + * @param count IN: the maximum size of the resulting array (0 = no limit), + * OUT: the actual size of the array + * @return a sstr_t array containing the split strings or * NULL 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. * * Read the description of sstrsplit() for details. * - * 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. * @@ -276,15 +274,15 @@ * @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 - * unbounded list), OUT: the actual size of the list - * @return a list of the split strings as sstr_t array or + * @param count IN: the maximum size of the resulting array (0 = no limit), + * OUT: the actual size of the array + * @return a sstr_t array containing the split strings or * NULL 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 memcmp(). @@ -385,6 +383,56 @@ */ 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