Skip to content

Commit

Permalink
Squashed commit of the following:
Browse files Browse the repository at this point in the history
commit 1e81fcb
Author: JacksonAllan <[email protected]>
Date:   Mon Mar 18 01:37:14 2024 +0300

    Update README.md

commit 7fa5bc7
Author: JacksonAllan <[email protected]>
Date:   Mon Mar 18 01:35:48 2024 +0300

    Update pre-release to full release

commit cd6de7c
Author: JacksonAllan <[email protected]>
Date:   Tue Feb 20 16:25:30 2024 +0300

    Update cc.h

commit 2ba9ad2
Author: JacksonAllan <[email protected]>
Date:   Tue Feb 20 04:21:10 2024 +0300

    v1.1.0 beta release

commit 726da2f
Author: JacksonAllan <[email protected]>
Date:   Sun Feb 18 16:17:41 2024 +0300

    Added explicit BETA tag.

commit 79b4e17
Author: JacksonAllan <[email protected]>
Date:   Sun Feb 18 04:34:35 2024 +0300

    Revised code comments and documentation, add CC_LIKELY/UNLIKELY.

commit b6df376
Author: JacksonAllan <[email protected]>
Date:   Mon Feb 12 03:06:53 2024 +0300

    Updated readme, unit tests.

commit 31d6ba4
Author: JacksonAllan <[email protected]>
Date:   Fri Feb 9 20:57:35 2024 +0300

    Update unit_tests.c

commit 2d07ae6
Author: JacksonAllan <[email protected]>
Date:   Fri Feb 9 20:39:56 2024 +0300

    Update cc.h

commit 5bfa266
Author: JacksonAllan <[email protected]>
Date:   Wed Feb 7 19:43:05 2024 +0300

    Integrated Verstable

    Integrated Verstable (first fully working draft).
  • Loading branch information
JacksonAllan committed Mar 18, 2024
1 parent 505e9a2 commit ccc38a9
Show file tree
Hide file tree
Showing 5 changed files with 1,032 additions and 570 deletions.
41 changes: 16 additions & 25 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,17 +1,15 @@
<picture><img src="./header.svg" alt="CC: Convenient Containers"></picture>

*Note: [Version 1.1.0 Pre-Release](https://github.com/JacksonAllan/CC/releases/tag/v1.1.0_Pre-Release) is now available via a [dedicated branch](https://github.com/JacksonAllan/CC/tree/v1.1.0-Pre-Release).*

**Convenient Containers** (**CC**) is a small, usability-oriented generic container library for C that provides **vectors**, **doubly linked lists**, **unordered maps**, and **unordered sets**.
Convenient Containers (**CC**) is a small, usability-oriented generic container library for C that provides **vectors**, **doubly linked lists**, **unordered maps**, and **unordered sets**.

Its features include:

- Fully generic API.
- Type safety.
- User-defined destructor, comparison, and hash functions associated with element and key types.
- No assumption of successful memory allocation.
- Single header.
- Compiles in C and C++.
* Fully generic API.
* Type safety.
* User-defined destructor, comparison, and hash functions associated with element and key types.
* No assumption of successful memory allocation.
* Single header.
* Compiles in C and C++.

It requires C23, or C11 and compiler support for `typeof`, or C++11.

Expand All @@ -29,7 +27,7 @@ In contrast, **CC** requires no type definitions and provides an API agnostic to
<tr>
</tr>
<tr>
<td>
<td valign="top">

```c
// CC
Expand All @@ -50,14 +48,10 @@ int main( void )
printf( "%f\n", *get( &our_map, 5 ) );
cleanup( &our_map );
}




```
</td>
<td>
<td valign="top">
```c
// Template-instantiation paradigm
Expand Down Expand Up @@ -87,7 +81,7 @@ int main( void )
<tr>
</tr>
<tr>
<td>
<td valign="top">

```c
// Typed-pointer/hidden-metadata paradigm
Expand Down Expand Up @@ -115,7 +109,7 @@ int main( void )
```
</td>
<td>
<td valign="top">
```c
// void-pointers paradigm
Expand All @@ -136,11 +130,6 @@ int main( void )
printf( "%f\n", *(float *)map_get( &our_map, &(int){ 5 } ) );
map_cleanup( &our_map );
}
```

</td>
Expand Down Expand Up @@ -249,7 +238,7 @@ int main( void )

### Map

A `map` is an unordered container associating elements with keys, implemented as a [Robin Hood](https://www.sebastiansylvan.com/post/robin-hood-hashing-should-be-your-default-hash-table-implementation) hash table.
A `map` is an unordered associative container mapping elements to keys, implemented as a hybird open-addressing, chained hash table that is also available as a [standalone library](https://github.com/JacksonAllan/Verstable).

```c
#include <stdio.h>
Expand Down Expand Up @@ -301,7 +290,7 @@ int main( void )
### Set
A `set` is a [Robin Hood](https://www.sebastiansylvan.com/post/robin-hood-hashing-should-be-your-default-hash-table-implementation) hash table for elements without a separate key.
A `set` is an unordered associative container for elements without a separate key, implemented as a hybird open-addressing, chained hash table also available as a [standalone library](https://github.com/JacksonAllan/Verstable).
```c
#include <stdio.h>
Expand Down Expand Up @@ -503,4 +492,6 @@ Destructor, comparison, and hash functions are also deduced via a novel techniqu
Future versions should include `NULL`-terminated dynamic strings, ordered maps, and ordered sets, as well as performance benchmarks.
## [API Reference](api_reference.md)
## API Reference
Full API documentation is available [here](api_reference.md).
39 changes: 21 additions & 18 deletions api_reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -96,7 +96,7 @@ Returns the current capacity.
bool reserve( vec( el_ty ) *cntr, size_t n )
```
Ensures that the the capacity is large enough to support `n` elements.
Ensures that the the capacity is large enough to accommodate `n` elements.
Returns `true`, or `false` if unsuccessful due to memory allocation failure.
```c
Expand Down Expand Up @@ -287,9 +287,9 @@ It is equivalent to `for( el_ty *i_name = last( cntr ); i_name != r_end( cntr );
> **Note**
> List pointer-iterators (including `r_end` and `end`) are not invalidated by any API calls besides `init` and `cleanup`, unless they point to erased elements.
### Map
## Map

A `map` is an unordered container associating elements with keys, implemented as a Robin Hood hash table.
A `map` is an unordered associative container mapping elements to keys, implemented as a hybird open-addressing, chained hash table.

```c
map( key_ty, el_ty ) cntr
Expand All @@ -305,13 +305,13 @@ size_t cap( map( key_ty, el_ty ) *cntr )
```

Returns the current capacity, i.e. bucket count.
Note that the number of elements a map can support without rehashing is not its capacity but its capacity multiplied by the max load factor associated with its key type.
Note that the number of elements a map can accommodate without rehashing is not its capacity but its capacity multiplied by the max load factor associated with its key type.

```c
bool reserve( map( key_ty, el_ty ) *cntr, size_t n )
```
Ensures that the capacity is large enough to support `n` elements without rehashing.
Ensures that the capacity is large enough to accommodate `n` elements without rehashing.
Returns `true`, or `false` if unsuccessful due to memory allocation failure.
```c
Expand All @@ -327,8 +327,7 @@ el_ty *insert( map( key_ty, el_ty ) *cntr, key_ty key, el_ty el )
Inserts element `el` with the specified key.
If an element with the same key already exists, the existing element is replaced.
Returns a pointer-iterator to the new element, or `NULL` in the case of memory allocation failure.
If adding one element would violate the map's max load factor, failure can occur even if it already contains the key.
Returns a pointer-iterator to the new element, or `NULL` in the case of memory allocation failure.
```c
el_ty *get( map( key_ty, el_ty ) *cntr, key_ty key )
Expand All @@ -341,9 +340,7 @@ el_ty *get_or_insert( map( key_ty, el_ty ) *cntr, key_ty key, el_ty el )
```
Inserts element `el` if no element with the specified key already exist.
Returns a pointer-iterator to the new element if it was inserted, or a pointer-iterator to the existing element with the same key, or `NULL` in the case of memory allocation failure.
If adding one element would violate the map's max load factor, failure can occur even if it already contains the key.
Determine whether an element was inserted by comparing the map's size before and after the call.
Returns a pointer-iterator to the new element if it was inserted, or a pointer-iterator to the existing element with the same key, or `NULL` in the case of memory allocation failure.
```c
const key_ty *key_for( map( key_ty, el_ty ) *cntr, el_ty *i )
Expand All @@ -359,10 +356,11 @@ Erases the element with the specified key, if it exists.
Returns `true` if an element was erased, or `false` if no such element exists.
```c
void erase_itr( map( key_ty, el_ty ) *cntr, el_ty *i )
el_ty * erase_itr( map( key_ty, el_ty ) *cntr, el_ty *i )
```

Erases the element pointed to by pointer-iterator `i`.
Erases the element pointed to by pointer-iterator `i`.
Returns an iterator to the next element in the map, or an end pointer-iterator if the erased element was the last one.

```c
el_ty *first( map( key_ty, el_ty ) *cntr )
Expand Down Expand Up @@ -433,7 +431,7 @@ It should be followed by the body of the loop.
## Set
A `set` is a Robin Hood hash table for elements without a separate key.
A `set` is an unordered associative container for elements without a separate key, implemented as a hybird open-addressing, chained hash table
```c
set( el_ty ) cntr
Expand All @@ -449,13 +447,13 @@ size_t cap( set( el_ty ) *cntr )
```
Returns the current capacity, i.e. bucket count.
Note that the number of elements a set can support without rehashing is not its capacity but its capacity multiplied by the max load factor associated with its key type.
Note that the number of elements a set can accommodate without rehashing is not its capacity but its capacity multiplied by the max load factor associated with its key type.
```c
bool reserve( set( el_ty ) *cntr, size_t n )
```

Ensures that the capacity is large enough to support `n` elements without rehashing.
Ensures that the capacity is large enough to accommodate `n` elements without rehashing.
Returns `true`, or `false` if unsuccessful due to memory allocation failure.

```c
Expand All @@ -471,8 +469,7 @@ el_ty *insert( set( el_ty ) *cntr, el_ty el )

Inserts element `el`.
If the element already exists, the existing element is replaced.
Returns a pointer-iterator to the new element, or `NULL` in the case of memory allocation failure.
Note that if adding one element would violate the set's max load factor, failure can occur even if it already contains `el`.
Returns a pointer-iterator to the new element, or `NULL` in the case of memory allocation failure.

```c
el_ty *get( set( el_ty ) *cntr, el_ty el )
Expand All @@ -486,7 +483,6 @@ el_ty *get_or_insert( set( el_ty ) *cntr, el_ty el )

Inserts element `el` if it does not already exist.
Returns a pointer-iterator to the new element if it was inserted, or a pointer-iterator to the existing element, or `NULL` in the case of memory allocation failure.
If adding one element would violate the set's max load factor, failure can occur even if it already contains the element.
Determine whether an element was inserted by comparing the set's size before and after the call.

```c
Expand All @@ -496,6 +492,13 @@ bool erase( set( el_ty ) *cntr, el_ty el )
Erases the element `el`, if it exists.
Returns `true` if an element was erased, or `false` if no such element exists.
```c
el_ty * erase_itr( set( el_ty ) *cntr, el_ty *i )
```

Erases the element pointed to by pointer-iterator `i`.
Returns an iterator to the next element in the set, or an end pointer-iterator if the erased element was the last one.

```c
el_ty *first( set( el_ty ) *cntr )
```
Expand Down
Loading

0 comments on commit ccc38a9

Please sign in to comment.