From 3b02e2386a0921ca2c4c084bf95151191739f08c Mon Sep 17 00:00:00 2001 From: Maxim Date: Sun, 12 Apr 2020 19:52:27 +0100 Subject: [PATCH] README.md updated. --- README.md | 41 +++++++++++++++++++++++++++++++---------- 1 file changed, 31 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 5d84d84..417d8b9 100644 --- a/README.md +++ b/README.md @@ -31,6 +31,8 @@ there is no corrupt or leaked memory resulting from using this library._ A string is represented by the type `str` that maintains a pointer to some memory containing the actual string. Objects of type `str` are small enough (a struct of a `const char*` and a `size_t`) to be cheap to pass by value. The strings are assumed to be immutable, like those in Java or Go. +This library focusses on handling the strings, not gradually composing them like +[StringBuffer](https://docs.oracle.com/javase/7/docs/api/java/lang/StringBuffer.html) class in Java. All string objects must be initialised. Uninitialised objects are likely to cause undefined behaviour. Use `str_null` for empty strings. @@ -113,6 +115,8 @@ The string object. `str_null`
Empty string constant. +#### String Properties + `size_t str_len(const str s)`
Returns the number of bytes in the string associated with the object. @@ -134,20 +138,24 @@ Returns "true" if the string object is the owner of the memory it references. `bool str_is_ref(const str s)`
Returns "true" if the string object does not own the memory it references. -`void str_free(const str s)`
-Release the memory referenced by the owning object; no-op for references. +#### String Modification `void str_assign(str* const ps, const str s)`
-Assigns the object "s" to the object pointed to by "ps". Any memory owned by the target +Assigns the object `s` to the object pointed to by `ps`. Any memory owned by the target object is freed before the assignment. `str str_move(str* const ps)`
Saves the given object to a temporary, resets the source object to `str_null`, and then returns the saved object. +`void str_dup(str* const dest, const str src)`
+Creates a copy of the string `src` and assigns it to `dest`, with `str_assign` semantics. + `void str_clear(str* const ps)`
Sets the target object to `str_null` after freeing any memory associated with the object. +#### String Comparison + `int str_cmp(const str s1, const str s2)`
Lexicographically compares the two string objects, with usual semantics. @@ -160,6 +168,8 @@ Case-insensitive comparison of two strings, implemented using `strncasecmp(3)`. `bool str_eq_ci(const str s1, const str s2`
Returns "true" is the two strings match case-insensitively. +#### String Composition + `void str_cat_range(str* const dest, const str* const src, const size_t n)`
Concatenates `n` strings from the array starting at address `src`, and assigns the newly allocated string to `dest`, with `str_assign` semantics. @@ -183,6 +193,8 @@ Same as `str_join_range`, but ignores empty strings. `str_join_ignore_empty(dest, sep, ...)`
Same as `str_join`, but ignores empty arguments. Implemented as a macro. +#### String Construction + `str_lit(s)`
Constructs `str` reference object from a string literal. Implemented as a macro. @@ -201,29 +213,38 @@ Creates an owning object for the specified range of bytes. The range should be s Creates an owning object from the given C string. The string should be safe to pass to `free(3)` function. Destination is assigned using `str_assign` semantics. -#### sorting and searching +#### Sorting and Searching `void str_sort(const str_cmp_func cmp, str* const array, const size_t count)`
-Sorts the given array of `str` objects. A number of typically used sorting functions is -provided (see `str.h` file). +Sorts the given array of `str` objects. A set of typically used comparison functions is +also provided: +* `str_order_asc` (ascending sort) +* `str_order_desc` (descending sort) +* `str_order_asc_ci` (ascending case-insensitive sort) +* `str_order_desc_ci` (descending case-insensitive sort) `const str* str_search(const str key, const str* const array, const size_t count)`
Binary search for the given key. The input array must be sorted using `str_order_asc`. Returns a pointer to the string matching the key, or NULL. `size_t str_uniq(str* const array, const size_t count)`
-Retain only the unique strings in the given array. Returns the number of strings. -After the call, the strings in the array are sorted, so the array is suitable for +Retain only the unique strings in the given array, in-place, also releasing any memory +owned by unused strings. Input array does _not_ have to be sorted. Returns the number of +strings retained. After the call, the strings are sorted, so the array is suitable for binary search using `str_search()` function. -#### Memory allocation +#### Memory Management + +`void str_free(const str s)`
+Release the memory referenced by the owning object; no-op for references. + By default the library uses `malloc(3)` for memory allocations, and calls `abort(3)` if the allocation fails. This behaviour can be changed by hash-defining `STR_EXT_ALLOC` symbol and providing the following functions: `void* str_mem_alloc(size_t)`
Allocates memory like `malloc(3)` does, also handling out-of-memory situations. The library -does not check the returned value for NULL. +does _not_ check the returned value for NULL. `void str_mem_free(void*)`
Releases the allocated memory like `free(3)` does.