From 012ec9f8c2df5006c87e96735643216259b64d2f Mon Sep 17 00:00:00 2001 From: Tyge Løvset Date: Mon, 30 Nov 2020 21:11:07 +0100 Subject: Added docs/cset_api.md, and some small additions. --- README.md | 3 +- docs/cmap_api.md | 8 +++-- docs/cset_api.md | 107 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/cstr_api.md | 2 +- 4 files changed, 116 insertions(+), 4 deletions(-) create mode 100644 docs/cset_api.md diff --git a/README.md b/README.md index 9cb49a58..714da7da 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,8 @@ An elegant, fully typesafe, generic, customizable, user-friendly, consistent, an - [***carray*** - Dynamic generic **multi-dimensional array**](docs/cbitset_api.md), implemented as a single contiguous block of memory. - [***cbitset*** - A **bitset** - *std::bitset*- or *boost::dynamic_bitset*-like](docs/cbitset_api.md) - [***clist*** - Generic circular **singly linked List** type](docs/clist_api.md). Can be used as a *queue* as it supports *push_back(), push_front(), and pop_front()*. Supports various *splice* functions and *merge sort*. -- [***cmap*** - Generic fast **unordered map/set** types](docs/cstr_api.md) Implemented as open hashing without tombstones. Highly customizable and fast. +- [***cmap*** - Generic fast **unordered map** type](docs/cmap_api.md) Implemented as open hashing without tombstones. Highly customizable and fast. +- [***cset*** - Generic fast **unordered set** type](docs/cset_api.md) Same as cmap, but contains and uses keys only. - [***cstr*** - Powerful and compact **string** type](docs/cstr_api.md) - [***cvec*** - Dynamic generic **vector** type](docs/cvec_api.md) - [***cstack*** - A **stack** adapter type](docs/cstack_api.md) diff --git a/docs/cmap_api.md b/docs/cmap_api.md index 3b598d88..ff8f6f19 100644 --- a/docs/cmap_api.md +++ b/docs/cmap_api.md @@ -52,6 +52,10 @@ be replaced by `my` in all of the following documentation. | | `}` | | | `cmap_T_input_t` | `cmap_T_value_t` | cmap input type | | `cmap_T_rawvalue_t` | `RawMapped` | cmap raw value type | +| `cmap_T_result_t` | `struct {` | Result of insert/put/emplace | +| | ` cmap_T_value_t* first;` | | +| | ` bool second;` /* inserted */ | | +| | `}` | | | `cmap_T_iter_t` | `struct {` | cmap iterator | | | ` cmap_T_value_t* val;` | | | | ` ...;` | | @@ -78,7 +82,7 @@ All cmap definitions and prototypes may be included in your C source file by inc ### Construction -The interfaces to create a cmap_T object: +The interface for cmap_T: ```c cmap_T cmap_T_init(void); cmap_T cmap_T_with_capacity(size_t cap); @@ -97,7 +101,7 @@ size_t cmap_T_capacity(cmap_T m); void cmap_T_push_n(cmap_T* self, const cmap_T_input_t in[], size_t size); -cmap_T_result_t cmap_T_emplace(cmap_T* self, RawKey rawKey RawMapped rawVal); +cmap_T_result_t cmap_T_emplace(cmap_T* self, RawKey rawKey, RawMapped rawVal); cmap_T_result_t cmap_T_insert(cmap_T* self, cmap_T_input_t in); cmap_T_result_t cmap_T_insert_or_assign(cmap_T* self, RawKey rawKey, RawMapped rawVal); cmap_T_result_t cmap_T_put(cmap_T* self, RawKey rawKey, RawMapped rawVal); diff --git a/docs/cset_api.md b/docs/cset_api.md new file mode 100644 index 00000000..23ae6cf2 --- /dev/null +++ b/docs/cset_api.md @@ -0,0 +1,107 @@ +# Introduction + +UNDER CONSTRUCTION! + +This describes the API of circular singly linked list type **cset**. + +## Declaration + +```c +#define using_cset_str() + +#define using_cset(T, Key, keyEqualsRaw=c_default_equals, + keyHashRaw=c_default_hash16, + keyDestroy=c_default_del, + RawKey=Key, + keyToRaw=c_default_to_raw, + keyFromRaw=c_default_from_raw) +``` +The macro `using_cset()` can be instantiated with 2, 4, 5, or 8 arguments in the global scope. +Default values are given above for args not specified. `T` is a type tag name and +will affect the names of all cset types and methods. E.g. declaring `using_cset(my, int);`, `T` should +be replaced by `my` in all of the following documentation. + +`using_cset_str()` is a predefined macro for `using_cset(str, cstr_t, ...)`. + +## Types + +| Type name | Type definition | Used to represent... | +|:---------------------|:--------------------------------------|:-----------------------------------| +| `cset_T` | `struct {` | The cset type | +| | ` cset_T_value_t* table; | | +| | ` uint8_t* _hashx;` | | +| | ` ...;` | | +| | `}` | | +| `cset_T_key_t` | `Key` | The cset key type | +| `cset_T_mapped_t` | `Mapped` | cset mapped type | +| `cset_T_value_t` | `Key` | The cset value type | +| `cset_T_result_t` | `struct {` | Result of insert/emplace | +| | ` cset_T_value_t* first;` | | +| | ` bool second;` /* inserted */ | | +| | `}` | | +| `cset_T_input_t` | `cset_T_value_t` | cset input type | +| `cset_T_iter_t` | `struct {` | cset iterator | +| | ` cset_T_value_t* val;` | | +| | ` ...;` | | +| | `}` | | + +## Constants and macros + +| Name | Value | +|:---------------------------|:-----------------| +| `cset_inits` | `{...}` | +| `cset_empty(map)` | `true` if empty | +| `cset_size(map)` | | +| `cset_capacity(map)` | | + + +## Header file + +All cset definitions and prototypes may be included in your C source file by including a single header file. + +```c +#include "stc/cset.h" +``` +## Methods + +### Construction + +The interface for cset_T: +```c +cset_T cset_T_init(void); +cset_T cset_T_with_capacity(size_t cap); +void cset_T_set_load_factors(cset_T* self, float max, float shrink); + +void cset_T_clear(cset_T* self); +void cset_T_reserve(cset_T* self, size_t size); +void cset_T_swap(cset_T* a, cset_T* b); + +void cset_T_del(cset_T* self); + +bool cset_T_empty(cset_T m); +size_t cset_T_size(cset_T m); +size_t cset_T_bucket_count(cset_T m); +size_t cset_T_capacity(cset_T m); + +void cset_T_push_n(cset_T* self, const cset_T_input_t in[], size_t size); + +cset_T_result_t cset_T_emplace(cset_T* self, cset_T_rawkey_t rawKey); +cset_T_result_t cset_T_insert(cset_T* self, cset_T_rawkey_t rawKey); + +size_t cset_T_erase(cset_T* self, cset_T_rawkey_t rawKey); +void cset_T_erase_entry(cset_T* self, cset_T_key_t* key); +cset_T_iter_t cset_T_erase_at(cset_T* self, cset_T_iter_t pos); + +cset_T_value_t* cset_T_find(const cset_T* self, cset_T_rawkey_t rawKey); +bool cset_T_contains(const cset_T* self, cset_T_rawkey_t rawKey); + +cset_T_iter_t cset_T_begin(cset_T* self); +cset_T_iter_t cset_T_end(cset_T* self); +void cset_T_next(cset_T_iter_t* it); +cset_T_mapped_t* cset_T_itval(cset_T_iter_t it); + +cset_bucket_t cset_T_bucket(const cset_T* self, const cset_T_rawkey_t* rawKeyPtr); + +uint32_t c_default_hash16(const void *data, size_t len); +uint32_t c_default_hash32(const void* data, size_t len); +``` diff --git a/docs/cstr_api.md b/docs/cstr_api.md index 80d8543a..6fbd1253 100644 --- a/docs/cstr_api.md +++ b/docs/cstr_api.md @@ -27,7 +27,7 @@ All cstr definitions and prototypes may be included in your C source file by inc ### Construction -The interfaces to create a cstr_t object: +The interface for cstr_t: ```c cstr_t cstr_init(void); (1) cstr_t cstr_with_capacity(size_t cap); (2) -- cgit v1.2.3