From 4d0abdc7c308044f89008191e0036564bbd0f917 Mon Sep 17 00:00:00 2001 From: Tyge Løvset Date: Wed, 2 Dec 2020 18:53:43 +0100 Subject: Improved docs for using_*() macros. --- docs/clist_api.md | 10 ++++---- docs/cmap_api.md | 75 ++++++++++++++++++++++++++++++++++++++++++------------- docs/cvec_api.md | 11 +++++--- 3 files changed, 69 insertions(+), 27 deletions(-) (limited to 'docs') diff --git a/docs/clist_api.md b/docs/clist_api.md index 455a66fb..a6b88626 100644 --- a/docs/clist_api.md +++ b/docs/clist_api.md @@ -7,20 +7,20 @@ Also supports various *splice* functions and *merge sort*. ## Declaration ```c -#define using_clist_str() - #define using_clist(X, Value, valueDestroy=c_default_del, valueCompareRaw=c_default_compare, RawValue=Value, valueToRaw=c_default_to_raw, valueFromRaw=c_default_from_raw) +#define using_clist_str() ``` The macro `using_clist()` can be instantiated with 2, 3, 4, or 7 arguments in the global scope. Default values are given above for args not specified. `X` is a type tag name and will affect the names of all clist types and methods. E.g. declaring `using_clist(my, int);`, `X` should -be replaced by `my` in all of the following documentation. - -`using_clist_str()` is a predefined macro for `using_clist(str, cstr_t, ...)`. +be replaced by `my` in all of the following documentation. `using_clist_str()` is a shorthand for: +```c +using_clist(str, cstr_t, cstr_del, cstr_compare_raw, const char*, cstr_to_raw, cstr_from) +``` ## Types diff --git a/docs/cmap_api.md b/docs/cmap_api.md index 8bd079ae..2fe5a830 100644 --- a/docs/cmap_api.md +++ b/docs/cmap_api.md @@ -6,17 +6,6 @@ Implemented as open hashing without tombstones. Highly customizable and fast. ## Declaration ```c -#define using_cmap_str() - -#define using_cmap_strkey(X, Mapped, mappedDestroy=c_default_del) - -#define using_cmap_strval(X, Key, keyEquals=c_default_equals, - keyHash=c_default_hash16, - keyDestroy=c_default_del, - RawKey=Key, - keyToRaw=c_default_to_raw, - keyFromRaw=c_default_from_raw) - #define using_cmap(X, Key, Mapped, mappedDestroy=c_default_del, keyEqualsRaw=c_default_equals, keyHashRaw=c_default_hash16, @@ -26,14 +15,28 @@ Implemented as open hashing without tombstones. Highly customizable and fast. keyFromRaw=c_default_from_raw, RawMapped=Mapped, mappedFromRaw=c_default_from_raw) + +#define using_cmap_strkey(X, Mapped, mappedDestroy=c_default_del) + +#define using_cmap_strval(X, Key, keyEquals=c_default_equals, + keyHash=c_default_hash16, + keyDestroy=c_default_del, + RawKey=Key, + keyToRaw=c_default_to_raw, + keyFromRaw=c_default_from_raw) +#define using_cmap_str() ``` The macro `using_cmap()` can be instantiated with 3, 4, 6, 10, or 12 arguments in the global scope. Default values are given above for args not specified. `X` is a type tag name and will affect the names of all cmap types and methods. E.g. declaring `using_cmap(my, int);`, `X` should be replaced by `my` in all of the following documentation. -`using_cmap_str()` is a specific definition of `using_cmap(str, cstr_t, ...)`. `using_cmap_strkey(X, ...)` and `using_cmap_strval(X, ...)` -are special macros for `using_cmap()` with `cstr_t` as key and mapped value correspondingly. +`using_cmap_strkey(X, ...)` and `using_cmap_strval(X, ...)` are special macros defined with +`using_cmap()`. The `using_cmap_str()` macro expands to: +```c +using_cmap(str, cstr_t, cstr_t, cstr_del, cstr_equals_raw, cstr_hash_raw, + cstr_del, const char*, cstr_to_raw, cstr_from, const char*, cstr_from) +``` ## Types @@ -103,7 +106,7 @@ cmap_X_result_t cmap_X_emplace(cmap_X* self, RawKey rkey, RawMapped rmapped) cmap_X_result_t cmap_X_insert(cmap_X* self, cmap_X_input_t in); cmap_X_result_t cmap_X_insert_or_assign(cmap_X* self, RawKey rkey, RawMapped rmapped); cmap_X_result_t cmap_X_put(cmap_X* self, RawKey rkey, RawMapped rmapped); -cmap_X_result_t cmap_X_putv(cmap_X* self, RawKey rkey, Mapped mapped); +cmap_X_result_t cmap_X_put_mapped(cmap_X* self, RawKey rkey, Mapped mapped); cmap_X_mapped_t* cmap_X_at(const cmap_X* self, RawKey rkey); size_t cmap_X_erase(cmap_X* self, RawKey rkey); @@ -124,7 +127,7 @@ uint32_t c_default_hash16(const void *data, size_t len); uint32_t c_default_hash32(const void* data, size_t len); ``` -## Example +## Examples ```c #include #include "stc/cstr.h" @@ -137,9 +140,9 @@ int main() // Create an unordered_map of three strings (that map to strings) cmap_str u = cmap_inits; c_push_items(&u, cmap_str, { - {"RED","#FF0000"}, - {"GREEN","#00FF00"}, - {"BLUE","#0000FF"} + {"RED", "#FF0000"}, + {"GREEN", "#00FF00"}, + {"BLUE", "#0000FF"} }); // Iterate and print keys and values of unordered map @@ -155,6 +158,7 @@ int main() printf("The HEX of color RED is:[%s]\n", cmap_str_at(&u, "RED")->str); printf("The HEX of color BLACK is:[%s]\n", cmap_str_at(&u, "BLACK")->str); + cmap_str_del(&u); return 0; } ``` @@ -166,3 +170,38 @@ Key:[BLUE] Value:[#0000FF] The HEX of color RED is:[#FF0000] The HEX of color BLACK is:[#000000] ``` + +### Example 2 +For illustration, this example uses a cmap with cstr_t as mapped value, instead of `using_strval(id, int)` macro. +We must therefore pass new constructed cstr_t objects to the map when inserting, instead of `const char*` strings. +```c +#include +#include + +using_cmap(id, int, cstr_t, cstr_del); + +int main() +{ + uint32_t col = 0xcc7744ff; + cmap_id idnames = cmap_inits; + c_push_items(&idnames, cmap_id, { + {100, cstr_from("Red")}, + {110, cstr_from("Blue")}, + {120, cstr_from_fmt("#%08x", col)}, + }); + cmap_id_put(&idnames, 80, cstr_from("White")); + + c_foreach (i, cmap_id, idnames) + printf("%d: %s\n", i.val->first, i.val->second.str); + puts(""); + + cmap_id_del(&idnames); +} +``` +Output: +```c +80: White +100: Red +110: Blue +120: #cc7744ff +``` \ No newline at end of file diff --git a/docs/cvec_api.md b/docs/cvec_api.md index 3db9e7c8..442a13f8 100644 --- a/docs/cvec_api.md +++ b/docs/cvec_api.md @@ -5,20 +5,22 @@ This describes the API of vector type **cvec**. ## Declaration ```c -#define using_cvec_str() - #define using_cvec(X, Value, valueDestroy=c_default_del, valueCompareRaw=c_default_compare, RawValue=Value, valueToRaw=c_default_to_raw, valueFromRaw=c_default_from_raw) +#define using_cvec_str() ``` The macro `using_cvec()` can be instantiated with 2, 3, 4, or 7 arguments in the global scope. Defaults values are given above for args not specified. `X` is a type tag name and will affect the names of all cvec types and methods. E.g. declaring `using_cvec(my, int);`, `X` should be replaced by `my` in all of the following documentation. -`using_cvec_str()` is a predefined macro for `using_cvec(str, cstr_t, ...)`. +`using_cvec_str()` is a shorthand, expands to: +``` +using_cvec(str, cstr_t, cstr_del, cstr_compare_raw, const char*, cstr_to_raw, cstr_from) +``` ## Types @@ -155,8 +157,9 @@ int main() { cvec_str_emplace_back(&names, "Joe"); cstr_assign(&names.data[1], "Jake"); // replace "Joe". - // Use push_back() rather than emplace_back() when adding a cstr_t type: cstr_t tmp = cstr_from_fmt("%d elements so far", cvec_str_size(names)); + + // Emplace_back() will not compile when adding a new cstr_t type. Use push_back(): cvec_str_push_back(&names, tmp); // tmp is moved to names, do not del() it. printf("%s\n", names.data[1].str); // Access the second element -- cgit v1.2.3