From 625ac703986f21adf54274ed179c07ac98c8da61 Mon Sep 17 00:00:00 2001 From: Tyge Løvset <60263450+tylov@users.noreply.github.com> Date: Wed, 25 Nov 2020 07:29:06 +0100 Subject: Update cstr_api.md More text added --- docs/cstr_api.md | 45 ++++++++++++++++++++++++--------------------- 1 file changed, 24 insertions(+), 21 deletions(-) diff --git a/docs/cstr_api.md b/docs/cstr_api.md index 4abf8a33..9ca51be1 100644 --- a/docs/cstr_api.md +++ b/docs/cstr_api.md @@ -1,6 +1,6 @@ # Introduction -This describes the API of **cstr_t**. +This describes the API of string type **cstr_t**. ## Types @@ -18,7 +18,7 @@ This describes the API of **cstr_t**. ## Header file -All cstr definitions and prototypes may be included in your C source file by including a single header file: +All cstr definitions and prototypes may be included in your C source file by including a single header file. ```c #include "stc/cstr.h" @@ -28,22 +28,24 @@ All cstr definitions and prototypes may be included in your C source file by inc The interfaces to create a cstr_t object: ```c -cstr_t cstr_init( void ); -cstr_t cstr_with_capacity( size_t cap ); -cstr_t cstr_with_size( size_t len, char fill ); -cstr_t cstr_from( const char* str ); -cstr_t cstr_from_n( const char* str, size_t len ); -cstr_t cstr_from_fmt( const char* fmt, ... ); +cstr_t cstr_init( void ); (1) +cstr_t cstr_with_capacity( size_t cap ); (2) +cstr_t cstr_with_size( size_t len, char fill ); (3) +cstr_t cstr_from( const char* str ); (4) +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) creates an empty string, and (2) with capacity `cap`. (3) creates a cstr_t of length `len`, containing `fill` characters. (4) constructs a cstr_t from a const char* string, and (5) limits the length by `len` or strlen(str). (6) constructs a string from a formatted string `fmt` and arguments, as defined by printf(). (7) constructs a new string by cloning cstr_t `s`. ## Destruction ```c void cstr_del( cstr_t *self ); ``` -## Interface +## cstr_t Interface -### Get properties +### Get attributes ```c size_t cstr_size( cstr_t s ); size_t cstr_length( cstr_t s ); @@ -51,28 +53,29 @@ size_t cstr_capacity( cstr_t s ); bool cstr_empty( cstr_t s ); ``` -### Reserve, reserve, and clear string. +### Reserve, resize and clear string ```c size_t cstr_reserve( cstr_t* self, size_t cap ); void cstr_resize( cstr_t* self, size_t len, char fill ); void cstr_clear( cstr_t* self ); ``` -### Assignment and transfer of ownership. +### Assignment and transfer of ownership ```c -cstr_t* cstr_assign( cstr_t* self, const char* str ); -cstr_t* cstr_assign_n( cstr_t* self, const char* str, size_t len ); -cstr_t* cstr_take( cstr_t* self, cstr_t s ); -cstr_t cstr_clone( cstr_t s ); -cstr_t cstr_move( cstr_t* self ); +cstr_t* cstr_assign( cstr_t* self, const char* str ); (1) +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) assigns `str` to `*self`, (2) assigns substring `str` limited by `len` or `strlen(str)`. (3) takes the constructed or moved string `s`, i.e., no allocation takes place. (4) explicitely moves `*self` to the caller of the method; `*self` becomes an empty string after move. -### Append characters. +### Append characters ```c -cstr_t* cstr_append( cstr_t* self, const char* str ); -cstr_t* cstr_append_n( cstr_t* self, const char* str, size_t len ); -cstr_t* cstr_push_back( cstr_t* self, char value ); +cstr_t* cstr_append( cstr_t* self, const char* str ); (1) +cstr_t* cstr_append_n( cstr_t* self, const char* str, size_t len ); (2) +cstr_t* cstr_push_back( cstr_t* self, char ch ); (3) ``` +Appends `str` (1), substring `str` limited by `len` (2), or character `ch` to `*self` (3). ### Insert characters ```c -- cgit v1.2.3