From 65ad066312ed549472814e1576cec2f0dc0f51ea Mon Sep 17 00:00:00 2001 From: Tyge Løvset <60263450+tylov@users.noreply.github.com> Date: Wed, 25 Nov 2020 11:12:38 +0100 Subject: Update cstr_api.md --- docs/cstr_api.md | 35 ++++++++++++++++++----------------- 1 file changed, 18 insertions(+), 17 deletions(-) diff --git a/docs/cstr_api.md b/docs/cstr_api.md index 613071f8..547a2bea 100644 --- a/docs/cstr_api.md +++ b/docs/cstr_api.md @@ -23,8 +23,9 @@ All cstr definitions and prototypes may be included in your C source file by inc ```c #include "stc/cstr.h" ``` +## Methods -## Construction +### Construction The interfaces to create a cstr_t object: ```c @@ -36,16 +37,15 @@ cstr_t cstr_from_n( const char* str, size_t len ); (5) cstr_t cstr_from_fmt( const char* fmt, ... ); (6) cstr_t cstr_clone( cstr_t s ); (7) ``` -(1) Create an empty cstr_t, (2) with capacity `cap`. (3) Create a cstr_t containing the `fill` character `len` times. (4) Construct a cstr_t from a const char* str, and (5) limit the length by `len` or `strlen(str)`. (6) Construct a string from a formatted const char* `fmt` and arguments, as defined by `printf()`. (7) Construct a new string by cloning another cstr_t `s`. +(1) Create an empty cstr_t, (2) with capacity `cap`. (3) Create a cstr_t by repeating the `fill` character `len` times. (4) Construct a cstr_t from a const char* str, and (5) limit the length by `len` and `strlen(str)`. (6) Construct a string from a formatted const char* `fmt` and arguments, using `printf()` formatting. (7) Construct a new string by cloning another cstr_t `s`. -## Destruction +### Destruction ```c void cstr_del( cstr_t *self ); ``` +Free the allocated memory used by string. -## cstr_t Interface - -### Get attributes +### Get string properties ```c size_t cstr_size( cstr_t s ); size_t cstr_length( cstr_t s ); @@ -67,7 +67,7 @@ cstr_t* cstr_assign_n( cstr_t* self, const char* str, size_t len ); (2) cstr_t* cstr_take( cstr_t* self, cstr_t s ); (3) cstr_t cstr_move( cstr_t* self ); (4) ``` -(1) Assign `str` to `*self`, (2) assign substring `str` limited by `len` or `strlen(str)`. (3) Take the constructed or moved string `s`, i.e., no allocation takes place. (4) Explicitly move `*self` to the caller of the method; `*self` becomes an empty string after move. +(1) Assign `str` to `*self`, (2) assign substring `str` limited by `len` and `strlen(str)`. (3) Take the constructed or moved string `s`, i.e., no allocation takes place. (4) Explicitly move `*self` to the caller of the method; `*self` becomes an empty string after move. ### Append characters ```c @@ -79,10 +79,10 @@ cstr_t* cstr_push_back( cstr_t* self, char ch ); (3) ### Insert characters ```c -void cstr_insert( cstr_t* self, size_t pos, const char* str ); -void cstr_insert_n( cstr_t* self, size_t pos, const char* str, size_t n ); +void cstr_insert( cstr_t* self, size_t pos, const char* str ); (1) +void cstr_insert_n( cstr_t* self, size_t pos, const char* str, size_t n ); (2) ``` - +Insert a string at the specified position (1), or insert string limited with ### Erase characters ```c void cstr_erase( cstr_t* self, size_t pos, size_t n ); @@ -119,20 +119,21 @@ char* cstr_front( cstr_t* self ); char* cstr_back( cstr_t* self ); ``` -### Iterator functions +### Iterator methods ```c -cstr_iter_t cstr_begin( cstr_t* self ); -cstr_iter_t cstr_end( cstr_t* self ); -void cstr_next( cstr_iter_t* it ); -char* cstr_itval( cstr_iter_t it ); +cstr_iter_t cstr_begin( cstr_t* self ); (1) +cstr_iter_t cstr_end( cstr_t* self ); (2) +void cstr_next( cstr_iter_t* it ); (3) +char* cstr_itval( cstr_iter_t it ); (4) ``` +To iterate though a string, one can use the generic `c_foreach` macro. E.g. `c_foreach (i, cstr, mystr) printf("%c", *i.val);`. This is equivalent to `for (size_t i=0; i