Updated README file.

This commit is contained in:
LoRd_MuldeR 2022-11-23 20:36:04 +01:00
parent 66b274e7f3
commit 5bdaa3d648

169
README.md
View File

@ -69,6 +69,175 @@ int main(int argc, char* argv[])
```
API Reference
=============
Types
-----
### hash_set_t
A `struct` that represents a hash set instance. Instances can be allocated and de-allocated via the [hash_set_create()](#hashsetcreate) and [hash_set_destroy()](#hashsetdestroy) functions, respectively.
***Note:*** Application code shall treat this `struct` as opaque!
```C
typedef struct _hash_set hash_set_t;
```
Functions
---------
### hash_set_create()
Allocates a new hash set instance. The new hash set instance is empty initially.
```C
hash_set_t *hash_set_create(
const size_t initial_capacity,
const double load_factor,
const uint16_t options
);
```
#### Parameters
* `initial_capacity`
The initial capacity of the hash set (number of items). The given value will be rounded to the next power of two. If set to *zero*, the default initial capacity is used.
* `load_factor`
The load factor to be used for the hash set. The given value will be clipped to the **0.1** to **1.0** range. If less than or equal to *zero*, the recommended default load factor is used.
* `options`
Bit mask that can contain zero or more of the following values OR'ed together:
- `HASHSET_OPT_FAILFAST`
If an operation attempts to grow the hash set, but the hash set fails to grow (e.g. because of a low-memory situation), causes the operation to fail immediately.
By default, if the set can *not* be grown as desired, the operation may complete successfully anyways. As a result, the performance of the hash set may degrade!
#### Return value
On success, this function returns a pointer to a new hash set instance. On error, a `NULL` pointer is returned.
***Note:*** To avoid a memory leak, the returned pointer must be de-allocated using the [hash_set_destroy()](#hashsetdestroy) function, as soon as the instance is *not* needed anymore!
### hash_set_destroy()
De-allocates an existing hash set instance. All items in the hash set are discarded, and all memory occupied by the hash set is released.
```C
void hash_set_destroy(
hash_set_t *instance
);
```
#### Parameters
* `instance`
A pointer to the existing hash set instance that is to be destroyed, as returned by the [hash_set_create()](#hashsetcreate) function.
***Note:*** The given pointer is *invalidated* by this function, and it **must not** be used afterwards!
### hash_set_insert()
Tries to insert the given value into the hash set. The operation fails, if the set already contains the given value.
***Note:*** If the value is actually inserted, then is *may* cause the hash set to grow.
```C
errno_t hash_set_insert(
hash_set_t *const instance,
const uint64_t value
);
```
#### Parameters
* `instance`
A pointer to the hash set instance to be used by this operation, as returned by the [hash_set_create()](#hashsetcreate) function.
* `value`
The value (key) to be inserted into the hash set. It can be *any* value in the `0U` to `UINT64_MAX` range.
#### Return value
On success, this function returns *zero*. On error, the appropriate error code is returned. Possible error codes include:
* `EINVAL`
An invalid argument was given, e.g. `instance` was set to `NULL`.
* `EEXIST`
The given value (key) was *not* inserted into the hash set, because the hash set already contained that value.
* `ENOMEM`
The value could *not* be inserted, because the required amount of memory could *not* be allocated.
* `EFAULT`
Something else went wrong. This usually indicates an internal error (inconsistency) and is *not* supposed to happen.
### hash_set_remove()
```C
errno_t hash_set_remove(
hash_set_t *const instance,
const uint64_t value
);
```
### hash_set_clear()
```C
errno_t hash_set_clear(
hash_set_t *const instance
);
```
### hash_set_shrink()
```C
errno_t hash_set_shrink(
hash_set_t *const instance
);
```
### hash_set_contains()
```C
errno_t hash_set_contains(
const hash_set_t *const instance,
const uint64_t value
);
```
### hash_set_iterate()
```C
errno_t hash_set_iterate(
const hash_set_t *const instance,
size_t *const offset,
uint64_t *const value
);
```
### hash_set_size()
```C
size_t hash_set_size(
const hash_set_t *const instance
);
```
### hash_set_info()
```C
errno_t hash_set_info(
const hash_set_t *const instance,
size_t *const capacity,
size_t *const valid,
size_t *const deleted,
size_t *const limit
);
```
License
=======