toolkit: comparison ucx/string.h

-:11f3bb408051
+:62921b370c60
 /*
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
 *
-* Copyright 2015 Olaf Wintermann. All rights reserved.
+* Copyright 2016 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
 * @return the concatenated string
 */
 sstr_t sstrcat(size_t count, sstr_t s1, sstr_t s2, ...);
 /**
-* Concatenates two or more strings using an UcxAllocator.
+* Concatenates two or more strings using a UcxAllocator.
 *
 * See sstrcat() for details.
 *
 * @param a       the allocator to use
 * @param count   the total number of strings to concatenate
 * @return       a substring starting at the last location of <code>chr</code>
 *
 * @see sstrsubs()
 */
 sstr_t sstrrchr(sstr_t string, int chr);
+/**
+* Returns a substring starting at the location of the first occurrence of the
+* specified string.
+*
+* If the string does not contain the other string, an empty string is returned.
+*
+* If <code>match</code> is an empty string, the complete <code>string</code> is
+* returned.
+*
+* @param string the string to be scanned
+* @param match  string containing the sequence of characters to match
+* @return       a substring starting at the first occurrence of
+*               <code>match</code>, or an empty string, if the sequence is not
+*               present in <code>string</code>
+*/
+sstr_t sstrstr(sstr_t string, sstr_t match);
 /**
 * Splits a string into parts by using a delimiter string.
 *
 * This function will return <code>NULL</code>, if one of the following happens:
 * If the string starts with the delimiter, the first item of the resulting
 * array will be an empty string.
 *
 * If the string ends with the delimiter and the maximum list size is not
 * exceeded, the last array item will be an empty string.
+* In case the list size would be exceeded, the last array item will be the
+* remaining string after the last split, <i>including</i> the terminating
+* delimiter.
 *
 * <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.
 *
 * @see sstrsplit_a()
 */
 sstr_t* sstrsplit(sstr_t string, sstr_t delim, ssize_t *count);
 /**
-* Performing sstrsplit() using an UcxAllocator.
+* Performing sstrsplit() using a UcxAllocator.
 *
 * <i>Read the description of sstrsplit() for details.</i>
 *
 * 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()
 * @see sstrdup_a()
 */
 sstr_t sstrdup(sstr_t string);
 /**
-* Creates a duplicate of the specified string using an UcxAllocator.
+* Creates a duplicate of the specified string using a UcxAllocator.
 *
 * The new sstr_t will contain a copy allocated by the allocators
 * ucx_allocator_malloc function. So it is implementation depended, whether the
 * returned sstr_t.ptr pointer must be passed to the allocators
 * ucx_allocator_free function manually.
 *
 * The sstr_t.ptr of the return value will <i>always</i> be <code>NULL</code>-
 * terminated.
 *
-* @param allocator a valid instance of an UcxAllocator
+* @param allocator a valid instance of a UcxAllocator
 * @param string the string to duplicate
 * @return a duplicate of the string
 * @see sstrdup()
 */
 sstr_t sstrdup_a(UcxAllocator *allocator, sstr_t string);

Mercurial > hg > toolkit / file comparison

comparison: ucx/string.h

ucx/string.h