Updated README file.
This commit is contained in:
parent
66b274e7f3
commit
5bdaa3d648
169
README.md
169
README.md
@ -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
|
||||
=======
|
||||
|
||||
|
Loading…
Reference in New Issue
Block a user