Mercurial > hg > toolkit / file diff

--- a/ucx/string.h	Wed Nov 22 12:59:13 2017 +0100
+++ b/ucx/string.h	Sun Jan 21 12:13:09 2018 +0100
@@ -1,7 +1,7 @@
 /*
  * 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:
@@ -137,7 +137,7 @@
 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.
  *
@@ -214,6 +214,23 @@
 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:
@@ -243,6 +260,9 @@
  * 
  * 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
@@ -260,7 +280,7 @@
 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>
  * 
@@ -331,7 +351,7 @@
 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
@@ -341,7 +361,7 @@
  * 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()