From 5d1c6c81a544eb4ca86ad26cff16298de38510e8 Mon Sep 17 00:00:00 2001 From: Tyge Løvset Date: Wed, 3 Mar 2021 07:21:51 +0100 Subject: Toned down performance aspect in the docs. --- README.md | 29 ++++++++++++----------------- docs/csmap_api.md | 5 ++++- stc/cmap.h | 5 +++-- 3 files changed, 19 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index ad71f079..ae339d38 100644 --- a/README.md +++ b/README.md @@ -30,16 +30,22 @@ Others: - [***coption*** - POSIX **getopt_long()** alike method](docs/coption_api.md) - [***crandom*** - A novel extremely fast *PRNG* named **stc64**](docs/crandom_api.md) +Highlights +---------- +- **User friendly** - Just include the header and you are good to go. The API and functionality is very close to c++ STL, and is fully listed in the docs. The ***using***-declaration instantiates the container type to use. You may pass *optional* arguments to it for customization of value- *comparison*, *destruction*, *cloning*, *conversion types*, and more. +- **Unparalleled performance** - The containers are about equal and often much faster than the c++ STL containers. +- **Fully memory managed** - All containers will destruct keys/values via destructor passed as macro parameters to the ***using***-declaration. Also, smart-pointers are supported and can be stored in containers, see ***csptr***. +- **Fully type safe** - Avoids error-prone casting of container types and elements back and forth from the containers. +- **Uniform, easy-to-learn API** - Methods to ***construct***, ***initialize***, ***iterate*** and ***destruct*** have uniform and intuitive usage across the various containers. +- **Small footprint** - Small source code and generated executables. The executable from the example below using six different containers is *27 kb in size* compiled with TinyC. +- **Dual mode compilation** - By default it is a simple header-only library with inline and static methods only, but you can easily switch to create a traditional library with shared symbols, without changing existing source files. See the Installation section. +- **No callback functions** - All passed template argument functions/macros are directly called from the implementation, no slow callbacks which requires storage. + Performance ----------- ![Benchmark](benchmarks/pics/benchmark.png) -STC containers performs either about equal or better than the c++ std counterparts. **cmap** ***crushes*** *std::unordered_map* across the board. -**cdeq**, **cmap**, and **csmap** all have multiple times faster iteration of elements and destruction than the c++ equivalents. **csmap** also -has noticable faster lookup than *std::map*'s typical red-black tree implementation. It uses an AA-tree (Arne Andersson, 1993), which tends to -create a flatter structure (more balanced) than red-black trees. **cvec** is only slightly slower than *std::vector*. - -Notes: +Benchmark notes: - The barchart shows average test times over three platforms: Win-Clang++ v11, Mingw64 g++ 9.20, VC19. CPU: Ryzen 7 2700X CPU @4Ghz. - Containers uses value types `uint64_t` and pairs of `uint64_t`for the maps. - Black bars indicates performance variation between various platforms/compilers. @@ -48,17 +54,6 @@ Notes: - **deque**: *insert*: n/3 push_front(), n/3 push_back()+pop_front(), n/3 push_back(). - **map and unordered map**: *insert*: n/2 random numbers, n/2 sequential numbers. *erase*: n/2 keys in the map, n/2 random keys. -Highlights ----------- -- **User friendly** - Super easy usage, just include the header and you are good to go. The API and functionality is very close to c++ STL, and is fully listed in the docs. The ***using_***-declaration instantiates the container type to use. You may pass *optional* arguments to it for customization of value- *comparison*, *destruction*, *cloning*, *conversion types*, and more. -- **Unparalleled performance** - The containers are about equal and often much faster than the c++ STL containers. -- **Fully memory managed** - All containers will destruct keys/values via destructor passed as macro parameters to the ***using***-declaration. Also, smart-pointers are supported and can be stored in containers, see ***csptr***. -- **Fully type safe** - Avoids error-prone casting of container types and elements back and forth from the containers. -- **Uniform, easy-to-learn API** - Methods to ***construct***, ***initialize***, ***iterate*** and ***destruct*** have uniform and intuitive usage across the various containers. -- **Small footprint** - Small source code and generated executables. The executable from the example below using six different containers is *27 kb in size* compiled with TinyC. -- **Dual mode compilation** - By default it is a simple header-only library with inline and static methods only, but you can easily switch to create a traditional library with shared symbols, without changing existing source files. See the Installation section. -- **No callback functions** - All passed template argument functions/macros are directly called from the implementation, no slow callbacks which requires storage. - Usage ----- diff --git a/docs/csmap_api.md b/docs/csmap_api.md index 91562b9a..61362588 100644 --- a/docs/csmap_api.md +++ b/docs/csmap_api.md @@ -1,7 +1,10 @@ # STC [csmap](../stc/csmap.h): Sorted Map ![Map](pics/smap.jpg) -A **csmap** is a sorted associative container that contains key-value pairs with unique keys. Keys are sorted by using the comparison function *keyCompare*. Search, removal, and insertion operations have logarithmic complexity. **csmap** is implemented as an AA-tree. +A **csmap** is a sorted associative container that contains key-value pairs with unique keys. Keys are sorted by +using the comparison function *keyCompare*. Search, removal, and insertion operations have logarithmic complexity. +**csmap** is implemented as an AA-tree (Arne Andersson, 1993), which tends to create a flatter structure +(slightly more balanced) than red-black trees. See the c++ class [std::map](https://en.cppreference.com/w/cpp/container/map) for a functional description. diff --git a/stc/cmap.h b/stc/cmap.h index f2524110..ddba396a 100644 --- a/stc/cmap.h +++ b/stc/cmap.h @@ -284,8 +284,9 @@ typedef struct {size_t idx; uint_fast8_t hx;} chash_bucket_t; res.first->second = mapped; return res; \ } \ STC_INLINE C##_##X##_result_t \ - C##_##X##_put(C##_##X* self, Key k, Mapped m) \ - {return C##_##X##_insert_or_assign(self, k, m);} \ + C##_##X##_put(C##_##X* self, Key k, Mapped m) { /* shorter, like operator[] */ \ + return C##_##X##_insert_or_assign(self, k, m); \ + } \ STC_INLINE C##_##X##_result_t \ C##_##X##_emplace_or_assign(C##_##X* self, RawKey rkey, RawMapped rmapped) { \ C##_##X##_result_t res = C##_##X##_insert_entry_(self, rkey); \ -- cgit v1.2.3