From 09b696eab6ae640f6c1e07178d49fcd8646e1737 Mon Sep 17 00:00:00 2001 From: Tyge Løvset Date: Sun, 19 Dec 2021 20:46:02 +0100 Subject: More docs, small example updates. --- README.md | 18 ++++++++++-------- docs/csmap_api.md | 2 +- examples/multimap.c | 31 +++++++++++++++---------------- examples/vikings.c | 6 +++--- 4 files changed, 29 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index 9d1587a8..fb822b48 100644 --- a/README.md +++ b/README.md @@ -5,15 +5,15 @@ STC - Smart Template Containers for C News ---- -### Version 3.0 released. Migration guide for breaking changes from version 2.X: -There are new general `i_key_bind` / `i_val_bind` template parameters which auto-binds a set of functions to the type specified, and can be used in place of `i_key` / `i_val`. Use the `_bind` variant for elements of Type which have following functions defined: *Type_cmp*, *Type_clone*, *Type_drop*, *Type_equalto*, and *Type_hash*. Only the functions required by the particular container needs to be defined, e.g. only **cmap** and **cset** require *Type_equalto* and *Type_hash* to be defined. -You may still define template parameters with `i_val` / `i_key` as before, which is easier for simple element types. +### Version 3.0 released +There are new general `i_key_bind` / `i_val_bind` template parameters which auto-binds a set of functions to the type specified, and can be used in place of `i_key` / `i_val`. Use the `_bind` variant for elements of Type which have following functions defined: *Type_cmp*, *Type_clone*, *Type_drop*, *Type_equalto*, and *Type_hash*. Only the functions required by the particular container needs to be defined, e.g. only **cmap** and **cset** require *Type_equalto* and *Type_hash* to be defined. You can override these by defining `i_cmp`, `i_drop`, etc. +It's still possible define template parameters with `i_val` / `i_key` as before, which is easier for simple element types, as defaults will be assigned to missing functions. -Regex replace in VS Code: +Migration guide from version 2 to 3. Replace (regular expresion) in VS Code: - `_del\b` → `_drop` - `_compare\b` → `_cmp` -Whole word + Match case: +Replace (whole word + match case): - `i_keydel` → `i_keydrop` - `i_valdel` → `i_valdrop` - `i_cnt` → `i_type` @@ -29,7 +29,7 @@ Whole word + Match case: - Added [**c_forpair**](docs/ccommon_api.md) macro: for-loop with "structured binding". - Deprecated *csptr_X_make()*. Renamed to *csptr_X_new()*. Corresponding **cbox** method is *cbox_X_new()*. - Deprecated *c_default_fromraw(raw)*. Renamed to *c_default_clone(raw)*. -- Deprecated `i_key_csptr` / `i_val_csptr`. Use `i_key_bind` / `i_val_bind` +- Deprecated `i_key_csptr` / `i_val_csptr`. Use `i_key_bind` / `i_val_bind` for types that has required functions defined. - Deprecated `i_cnt`. Use `i_type` instead to define the complete container type name. - Added `i_opt` template parameter: compile-time options: `c_no_cmp`, `c_no_clone`, `c_no_atomic`, `c_is_fwd`; may be combined with `|` @@ -39,9 +39,11 @@ Whole word + Match case: Introduction ------------ STC is a modern, templated, user-friendly, fast, fully type-safe, and customizable container library for C99, -with a uniform API across the containers, and is similar to the c++ standard library containers API. +with a uniform API across the containers, and is similar to the c++ standard library containers API. It takes some +inspirations from Rust and Python too. + It is a compact, header-only library which includes the all the major "standard" data containers except for the -multimap/set variants. There are examples on how to create multimaps in the examples folder. +multimap/set variants. However, there are examples on how to create multimaps in the examples folder. For an introduction to templated containers, please read the blog by Ian Fisher on [type-safe generic data structures in C](https://iafisher.com/blog/2020/06/type-safe-generics-in-c). diff --git a/docs/csmap_api.md b/docs/csmap_api.md index 88d58cd4..c4f0ff16 100644 --- a/docs/csmap_api.md +++ b/docs/csmap_api.md @@ -183,7 +183,7 @@ static int Vec3i_cmp(const Vec3i* a, const Vec3i* b) { #define i_key Vec3i #define i_val int -#define i_cmp Vec3i_cmp // uses c_default_hash +#define i_cmp Vec3i_cmp #define i_tag vi #include #include diff --git a/examples/multimap.c b/examples/multimap.c index 424ae606..472af8aa 100644 --- a/examples/multimap.c +++ b/examples/multimap.c @@ -35,6 +35,21 @@ struct OlympicsData { int year; const char *city, *country, *date; } ol_data[] = typedef struct { int year; cstr city, date; } OlympicLocation; +int OlympicLocation_cmp(OlympicLocation* a, OlympicLocation* b); +OlympicLocation OlympicLocation_clone(OlympicLocation loc); +void OlympicLocation_drop(OlympicLocation* self); + +// Create a clist, can be sorted by year. +#define i_val_bind OlympicLocation // binds _cmp, _clone and _drop. +#define i_tag OL +#include + +// Create a csmap where key is country name +#define i_key_str // binds cstr_equ, cstr_hash, cstr_clone, ++ +#define i_val_bind clist_OL // binds clist_OL_clone, clist_OL_drop +#define i_tag OL +#include + int OlympicLocation_cmp(OlympicLocation* a, OlympicLocation* b) { return a->year - b->year; } @@ -48,22 +63,6 @@ void OlympicLocation_drop(OlympicLocation* self) { c_drop(cstr, &self->city, &self->date); } -// Create a clist, can be sorted by year. -#define i_val OlympicLocation -#define i_cmp OlympicLocation_cmp -#define i_drop OlympicLocation_drop -#define i_from OlympicLocation_clone -#define i_tag OL -#include - -// Create a csmap where key is country name -#define i_key_str -#define i_val clist_OL -#define i_valdrop clist_OL_drop -#define i_valfrom clist_OL_clone -#define i_tag OL -#include - int main() { // Define the multimap with destructor defered to when block is completed. diff --git a/examples/vikings.c b/examples/vikings.c index 87977538..838598b5 100644 --- a/examples/vikings.c +++ b/examples/vikings.c @@ -36,12 +36,12 @@ static inline RViking Viking_toraw(const Viking* vk) { // With this in place, we define the Viking => int hash map type: #define i_type Vikings #define i_key_bind Viking -#define i_val int #define i_keyraw RViking -// i_key_bind auto-maps these functions: +#define i_val int +// i_key_bind auto-binds these functions: // #define i_hash Viking_hash // #define i_equ Viking_equalto -// #define i_keyfrom Viking_from // uses _from because i_keyraw is defined +// #define i_keyfrom Viking_from // uses _from (not _clone) because i_keyraw is defined // #define i_keyto Viking_toraw // #define i_keydrop Viking_drop #include -- cgit v1.2.3