blankhex/bhlib
Archived
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Fix function documentation, add missing function

Browse Source
This commit is contained in:
Mikhail Romanko
2025-02-03 15:18:57 +03:00
parent c34a24c2a4
commit 7a7134a2f5
5 changed files with 179 additions and 172 deletions
Download Patch File Download Diff File Expand all files Collapse all files

71
include/BH/Algo.h
View File

@@ -6,10 +6,10 @@
/**
* Exchanges the values of two elements.
* Exchanges values between \a src and \a dest elements of sizze \a size.
*
* \param dest Pointer to the element
* \param src Pointer to the element
* \param dest Destination element pointer
* \param src Source element pointer
* \param size Element size in bytes
*/
void BH_Swap(void *dest,
@@ -18,14 +18,15 @@ void BH_Swap(void *dest,
/**
* Partitions the array relative to the specified pivot element.
* Partitions the \a array (with specified \a size and \a element size)
* relative to specified \a pivot element.
*
* The pivot element can be part of the partitioned array.
* The \a pivot element can be part of the partitioned \a array.
*
* \param pivot Pointer to the pivot element
* \param array Pointer to the array
* \param pivot Pivot element pointer
* \param array Array pointer
* \param size Array size
* \param element Element size in bytes
* \param element Array element size
* \param equal Comparision function
*
* \return Pointer to the first element of the second partition.
@@ -38,11 +39,14 @@ void *BH_Partition(void *pivot,
/**
* Sorts the array.
* Sorts the \a array (with specified \a size and \a element size).
*
* \param array Pointer to the array
* The sorting algorithm is implementation defined and may change between
* revisions.
*
* \param array Array pointer
* \param size Array size
* \param element Element size in bytes
* \param element Array element size
* \param equal Comparision function
*/
void BH_Sort(void *array,
@@ -52,11 +56,11 @@ void BH_Sort(void *array,
/**
* Makes heap in an array from the array.
* Heapifies an \a array (with specified \a size and \a element size).
*
* \param array Pointer to the array
* \param array Array pointer
* \param size Array size
* \param element Element size in bytes
* \param element Array element size
* \param equal Comparision function
*/
void BH_HeapMake(void *array,
@@ -66,11 +70,12 @@ void BH_HeapMake(void *array,
/**
* Removes top/first element from a heap in an array.
* Removes top value from the heapified \a array (with specified \a size
* and \a element size).
*
* \param array Pointer to the array
* \param array Array pointer
* \param size Array size
* \param element Element size in bytes
* \param element Array element size
* \param equal Comparasion function
*/
void BH_HeapRemove(void *array,
@@ -80,15 +85,16 @@ void BH_HeapRemove(void *array,
/**
* Inserts new element into heap in an array.
* Inserts new \a value into heapified \a array in an array (with specified
* \a size and \a element size)
*
* If the pointer to value is NULL, this function assumes that the new value
* is at the end of the array.
* If \a value pointer is NULL, it is assumed that new value is placed at the
* end of the array.
*
* \param value Pointer to the value
* \param array Pointer to the array
* \param value Value pointer
* \param array Array pointer
* \param size Array size
* \param element Element size in bytes
* \param element Array element size
* \param equal Comparasion function
*/
void BH_HeapInsert(void *value,
@@ -99,21 +105,16 @@ void BH_HeapInsert(void *value,
/**
* Removes top/first element and inserts new element into heap in an array.
* Removes top value from heapified \a array (with specified \a size and
* \a element size) and inserts new \a value.
*
* If the pointer to value is NULL, this function assumes that the new value
* is at the end of the array.
* If value pointer is NULL, it is assumed that new value is placed at the
* end of the array.
*
* This function is roughly equivalent to the following code:
* \code
* BH_HeapRemove(array, size, element, equal);
* BH_HeapInsert(value, array, size - 1, element, equal);
* \endcode
*
* \param value Pointer to the value
* \param array Pointer to the array
* \param value Value pointer
* \param array Array pointer
* \param size Array size
* \param element Element size in bytes
* \param element Array element size
* \param equal Comparasion function
*/
void BH_HeapReplace(void *value,

75
include/BH/Hashmap.h
View File

@@ -9,12 +9,12 @@ typedef struct BH_Hashmap BH_Hashmap;
/**
* Creates the new hashmap handle.
* Creates the new hashmap with specified \a equal and \a hash callbacks.
*
* \param equal Comparision function
* \param hash Key hash function
*
* \return On success, returns hashmap handle.
* \return On success, returns hashmap pointer.
* \return On failure, returns a null pointer.
*/
BH_Hashmap *BH_HashmapNew(BH_EqualCallback equal,
@@ -22,34 +22,34 @@ BH_Hashmap *BH_HashmapNew(BH_EqualCallback equal,
/**
* Destroys the hashmap.
* Destroys the \a hashmap.
*
* \param hashmap Hashmap handle
* \param hashmap Hashmap pointer
*/
void BH_HashmapFree(BH_Hashmap *hashmap);
/**
* Clears the hashmap.
* Clears the \a hashmap.
*
* \param hashmap Hashmap handle
* \param hashmap Hashmap pointer
*/
void BH_HashmapClear(BH_Hashmap *hashmap);
/**
* Reserves space in the hashmap.
* Reserves space for \a size amount of elements in the \a hashmap.
*
* This function can both expand and shrink the available space in hashmap.
* This function takes into account current hashmap load factor.
*
* \param hashmap Hahsmap handle
* \param hashmap Hahsmap pointer
* \param size Capacity
*
* \note Calling this function will invalidate iterators.
* \note Actual hashmap capacity can be bigger then requested.
*
* \return On success, returns zero value.
* \return On success, returns zero.
* \return On failure, returns error code.
*/
int BH_HashmapReserve(BH_Hashmap *hashmap,
@@ -57,16 +57,16 @@ int BH_HashmapReserve(BH_Hashmap *hashmap,
/**
* Inserts the pair of key-value into the hashmap.
* Inserts the pair \a key \a value pair into the \a hashmap.
*
* \param hashmap Hashmap handle
* \param hashmap Hashmap pointer
* \param key Key
* \param value Value
*
* \note This function allows duplicates to be inserted.
* \note Calling this function will invalidate iterators.
*
* \return On success, returns zero value.
* \return On success, returns zero.
* \return On failure, returns error code.
*/
int BH_HashmapInsert(BH_Hashmap *hashmap,
@@ -75,9 +75,9 @@ int BH_HashmapInsert(BH_Hashmap *hashmap,
/**
* Removes value from the hashmap.
* Removes value from the \a hashmap by \a key.
*
* \param hashmap Hashmap handle
* \param hashmap Hashmap pointer
* \param key Key
*
* \note Calling this function will invalidate iterators.
@@ -89,13 +89,13 @@ void BH_HashmapRemove(BH_Hashmap *hashmap,
/**
* Returns value from the hashmap by key.
* Returns \a value from the \a hashmap by \a key.
*
* \param hashmap Hashmap handle
* \param hashmap Hashmap pointer
* \param key Key
* \param value Value (optional)
*
* \return On success, returns zero value.
* \return On success, returns zero.
* \return On failure, returns error code.
*/
int BH_HashmapAt(BH_Hashmap *hashmap,
@@ -104,20 +104,20 @@ int BH_HashmapAt(BH_Hashmap *hashmap,
/**
* Checks if the hashmap is empty.
* Checks if the \a hashmap is empty.
*
* \param hashmap Hashmap handle
* \param hashmap Hashmap pointer
*
* \return If hashmap is empty, returns non-zero value
* \return If hashmap is not empty, returns zero value
* \return If hashmap is not empty, returns zero
*/
int BH_HashmapEmpty(BH_Hashmap *hashmap);
/**
* Returns the size of the hashmap.
* Returns the size of the \a hashmap.
*
* \param hashmap Hashmap handle
* \param hashmap Hashmap pointer
*
* \return Returns the size of the hashmap.
*/
@@ -125,9 +125,9 @@ size_t BH_HashmapSize(BH_Hashmap *hashmap);
/**
* Returns the capacity of the hashmap.
* Returns the capacity of the \a hashmap.
*
* \param hashmap Hashmap handle
* \param hashmap Hashmap pointer
*
* \return Returns the capacity of the hashmap.
*/
@@ -135,9 +135,9 @@ size_t BH_HashmapCapacity(BH_Hashmap *hashmap);
/**
* Returns the load factor of the hashmap.
* Returns the load factor of the \a hashmap.
*
* \param hashmap Hashmap handle
* \param hashmap Hashmap pointer
*
* \return Returns the load factor of the hashmap.
*/
@@ -145,9 +145,9 @@ float BH_HashmapFactor(BH_Hashmap *hashmap);
/**
* Sets the load factor of the hashmap.
* Sets the load \a factor of the \a hashmap.
*
* \param hashmap Hashmap handle
* \param hashmap Hashmap pointer
* \param factor Load factor
*
* \note New load factor will be applied on the next reserve/insert operation.
@@ -157,9 +157,9 @@ void BH_HashmapSetFactor(BH_Hashmap *hashmap,
/**
* Returns the iterator to the element in the hashmap with specified key.
* Returns the iterator to the element in the \a hashmap by \a key.
*
* \param hashmap Hashmap handle
* \param hashmap Hashmap pointer
* \param iter Iterator
*
* \return On success, returns iterator value.
@@ -173,12 +173,12 @@ void *BH_HashmapIterAt(BH_Hashmap *hashmap,
/**
* Returns the iterator to the next element in the hashmap.
* Returns next element \a iter in the \a hashmap.
*
* If the iterator is NULL pointer, this function will return iterator to the
* If \a iter is NULL pointer, then this function will return iter to the
* first element of the hashmap.
*
* \param hashmap Hashmap handle
* \param hashmap Hashmap pointer
* \param iter Iterator
*
* \return On success, returns new iterator value for the next element.
@@ -189,9 +189,9 @@ void *BH_HashmapIterNext(BH_Hashmap *hashmap,
/**
* Removes value from the hashmap pointed by by iterator.
* Removes key-value from the \a hashmap pointed by \a iter.
*
* \param hashmap Hashmap handle
* \param hashmap Hashmap pointer
* \param iter Iterator
*
* \note Calling this function will invalidate iterators.
@@ -201,7 +201,7 @@ void BH_HashmapIterRemove(BH_Hashmap *hashmap,
/**
* Returns key, pointed by the iterator.
* Returns key, pointed by the \a iter.
*
* \param iter Iterator
*
@@ -211,7 +211,7 @@ void *BH_HashmapIterKey(void *iter);
/**
* Returns value, pointed by the iterator.
* Returns value, pointed by the \a iter.
*
* \param iter Iterator
*
@@ -221,3 +221,4 @@ void *BH_HashmapIterValue(void *iter);
#endif /* BH_HASHMAP_H */

112
include/BH/IO.h
View File

@@ -48,34 +48,34 @@ typedef int (*BH_IOCallback)(void *, int ,void *, void *);
/**
* Creates the IO handle that represents file.
* Creates the IO that represents file with the given \a path.
*
* \param path Path to the file
* \param path File path
*
* \return On success, returns IO handle.
* \return On success, returns IO pointer.
* \return On failure, returns NULL pointer.
*/
BH_IO *BH_FileNew(const char *path);
/**
* Creates the IO handle that represents buffered IO.
* Creates the IO that buffers access to other \a io.
*
* \param io IO handle
* \param io IO pointer
*
* \return On success, returns IO handle.
* \return On success, returns IO pointer.
* \return On failure, returns NULL pointer.
*/
BH_IO *BH_BufferNew(BH_IO *io);
/**
* Creates the IO handle with specified handler and context.
* Creates the IO with specified callback \a cb and \a data.
*
* \param func IO actions handler
* \param cb Callback
* \param data Initialization data
*
* \return On success, returns IO handle.
* \return On success, returns IO pointer.
* \return On failure, returns NULL pointer.
*/
BH_IO *BH_IONew(BH_IOCallback cb,
@@ -83,17 +83,17 @@ BH_IO *BH_IONew(BH_IOCallback cb,
/**
* Destroys the IO.
* Destroys the \a io.
*
* \param io IO handle
* \param io IO pointer
*/
void BH_IOFree(BH_IO *io);
/**
* Returns the IO instance classname.
* Returns the \a io classname.
*
* \param io IO handle
* \param io IO pointer
*
* \return On success, returns pointer to constant string.
* \return On failure, returns NULL pointer
@@ -102,12 +102,12 @@ const char *BH_IOClassname(BH_IO* io);
/**
* Opens the IO in specified mode of operation.
* Opens the \a io in specified \a mode of operation.
*
* \param io IO handle
* \param io IO pointer
* \param mode Mode of operation
*
* \return On success, returns zero value.
* \return On success, returns zero.
* \return On failure, returns error code.
*/
int BH_IOOpen(BH_IO *io,
@@ -115,25 +115,25 @@ int BH_IOOpen(BH_IO *io,
/**
* Closes the IO.
* Closes the \a io.
*
* \param io IO handle
* \param io IO pointer
*
* \return On success, returns zero value.
* \return On success, returns zero.
* \return On failure, returns error code.
*/
int BH_IOClose(BH_IO *io);
/**
* Reads up to specified amount of bytes from the IO into memory buffer.
* Reads up to \a size bytes from the \a io into \a buffer.
*
* \param io IO handle
* \param buffer Pointer to the buffer
* \param size Bytes to read
* \param actual Bytes read
* \param io IO pointer
* \param buffer Buffer pointer
* \param size Buffer size
* \param actual Bytes read (optional)
*
* \return On success, returns zero value.
* \return On success, returns zero.
* \return On failure, returns error code.
*/
int BH_IORead(BH_IO *io,
@@ -143,14 +143,14 @@ int BH_IORead(BH_IO *io,
/**
* Writes up to specified amount of bytes into the IO from the memory buffer.
* Writes up to \a size bytes to the \a io from \a buffer.
*
* \param io IO handle
* \param buffer Pointer to the buffer
* \param size Bytes to write
* \param actual Bytes written
* \param io IO pointer
* \param buffer Buffer pointer
* \param size Buffer size
* \param actual Bytes written (optional)
*
* \return On success, returns zero value.
* \return On success, returns zero.
* \return On failure, returns error code.
*/
int BH_IOWrite(BH_IO *io,
@@ -160,14 +160,14 @@ int BH_IOWrite(BH_IO *io,
/**
* Peeks up to specified amount of bytes from the IO handle.
* Peeks up to \a size bytes from \a io into \a buffer.
*
* \param io IO handle
* \param buffer Pointer to the buffer
* \param size Bytes to peek
* \param actial Bytes peeked
* \param io IO pointer
* \param buffer Buffer pointer
* \param size Buffer size
* \param actial Bytes peeked (optional)
*
* \return On success, returns zero value.
* \return On success, returns zero.
* \return On failure, returns error code.
*/
int BH_IOPeek(BH_IO *io,
@@ -177,12 +177,12 @@ int BH_IOPeek(BH_IO *io,
/**
* Tells current offset in the IO.
* Tells current \a position in the \a io.
*
* \param io IO handle
* \param position Offset
* \param io IO pointer
* \param position Position
*
* \return On success, returns zero value.
* \return On success, returns zero.
* \return On failure, returns error code.
*/
int BH_IOTell(BH_IO *io,
@@ -190,13 +190,13 @@ int BH_IOTell(BH_IO *io,
/**
* Seeks to specified offset in the IO.
* Seeks to specified \a position and \a direction in the \a io.
*
* \param io IO handle
* \param position Offset
* \param io IO pointer
* \param position Position
* \param direction Direction
*
* \return On success, returns zero value.
* \return On success, returns zero.
* \return On failure, returns error code.
*/
int BH_IOSeek(BH_IO *io,
@@ -205,23 +205,23 @@ int BH_IOSeek(BH_IO *io,
/**
* Flushes the internal buffers of the IO.
* Flushes the internal buffers of the \a io.
*
* \param io IO handle
* \param io IO pointer
*
* \return On success, returns zero value.
* \return On success, returns zero.
* \return On failure, returns error code.
*/
int BH_IOFlush(BH_IO *io);
/**
* Returns the size of the IO (either total or available size).
* Returns total or available size of the \a io.
*
* \param io IO handle
* \param io IO pointer
* \param size Available/total size
*
* \return On success, returns zero value.
* \return On success, returns zero.
* \return On failure, returns error code.
*/
int BH_IOSize(BH_IO *io,
@@ -229,9 +229,9 @@ int BH_IOSize(BH_IO *io,
/**
* Returns flags of the IO.
* Returns flags of the \a io.
*
* \param io IO handle
* \param io IO pointer
*
* \return Flags of the IO
*/
@@ -239,11 +239,11 @@ int BH_IOFlags(BH_IO *io);
/**
* Clears errors of the IO.
* Clears errors of the \a io.
*
* \param io IO handle
* \param io IO pointer
*
* \return On success, returns zero value.
* \return On success, returns zero.
* \return On failure, returns error code.
*/
int BH_IOClear(BH_IO *io);

65
include/BH/Queue.h
View File

@@ -9,42 +9,42 @@ typedef struct BH_Queue BH_Queue;
/**
* Creates the new queue object.
* Creates the new queue.
*
* \return On success, returns the pointer to the new queue object.
* \return On success, returns the queue pointer.
* \return On failure, returns a null pointer.
*/
BH_Queue *BH_QueueNew(void);
/**
* Frees the \a queue object.
* Frees the \a queue.
*
* \param queue Pointer to the queue object to be freed
* \param queue Queue pointer
*/
void BH_QueueFree(BH_Queue *queue);
/**
* Clears the \a queue object.
* Clears the \a queue.
*
* \param queue Pointer to the queue object to be cleared
* \param queue Queue pointer
*/
void BH_QueueClear(BH_Queue *queue);
/**
* Reserves the space for \a size elements in the \a queue.
* Reserves the space for \a size amount of value in the \a queue.
*
* This function can both expand and shrink the available space in \a queue.
* This function can both expand and shrink the available space in queue.
*
* \param queue Pointer to the queue object to be resized in terms of capacity
* \param size New capacity of the queue
* \param queue Queue pointer
* \param size Capacity
*
* \note Calling this function will invalidate iterators.
* \note Actual hashmap capacity can be bigger then requested.
* \note Actual queue capacity can be bigger then requested.
*
* \return On success, returns zero value.
* \return On success, returns zero.
* \return On failure, returns error code.
*/
int BH_QueueReserve(BH_Queue *queue,
@@ -54,12 +54,12 @@ int BH_QueueReserve(BH_Queue *queue,
/**
* Inserts the \a value into the \a queue.
*
* \param queue Pointer to the queue object
* \param value Value to be inserted
* \param queue Queue pointer
* \param value Value
*
* \note Calling this function will invalidate iterators.
*
* \return On success, returns zero value.
* \return On success, returns zero.
* \return On failure, returns error code.
*/
int BH_QueueInsert(BH_Queue *queue,
@@ -69,7 +69,7 @@ int BH_QueueInsert(BH_Queue *queue,
/**
* Removes front value from the \a queue.
*
* \param queue Pointer to the queue object
* \param queue Queue pointer
*
* \note Calling this function will invalidate iterators.
*/
@@ -77,12 +77,13 @@ void BH_QueueRemove(BH_Queue *queue);
/**
* Returns front value from the \a queue.
* Returns front \a value from the \a queue.
*
* \param queue Pointer to the queue object
* \param queue Queue pointer
* \param value Value
*
* \return On success, returns front value from the queue.
* \return On failure, returns null pointer.
* \return On success, returns zero.
* \return On failure, returns error code.
*/
int BH_QueueFront(BH_Queue *queue,
void **value);
@@ -91,10 +92,10 @@ int BH_QueueFront(BH_Queue *queue,
/**
* Checks if the \a queue is empty.
*
* \param queue Pointer to the queue object
* \param queue Queue pointer
*
* \return If queue is empty, returns non-zero value
* \return If queue is not empty, returns zero value
* \return If queue is not empty, returns zero
*/
int BH_QueueEmpty(BH_Queue *queue);
@@ -102,7 +103,7 @@ int BH_QueueEmpty(BH_Queue *queue);
/**
* Returns the size of the \a queue.
*
* \param queue Pointer to the queue object
* \param queue Queue pointer
*
* \return Returns the size of the queue.
*/
@@ -112,7 +113,7 @@ size_t BH_QueueSize(BH_Queue *queue);
/**
* Returns the capacity of the \a queue.
*
* \param queue Pointer to the queue object
* \param queue Queue pointer
*
* \return Returns the capacity of the queue.
*/
@@ -122,24 +123,20 @@ size_t BH_QueueCapacity(BH_Queue *queue);
/**
* Returns the iterator to the next element in the \a queue.
*
* \param queue Pointer to the queue object
* \param iter Opaque iterator value
* \param queue Queue pointer
* \param iter Iterator
*
* \return If the \a iter doesn't point to the last element of the queue,
* returns next iterator value.
* \return If the \a iter point to the last element of the queue, returns
* null pointer.
* \return If the \a iter is the null pointer, returns iterator to the
* first element of the queue.
* \return On success, returns new iterator value for the next element.
* \return On failure, returns NULL pointer.
*/
void *BH_QueueIterNext(BH_Queue *queue,
void *iter);
/**
* Returns the value, pointed by the queue iterator \a iter.
* Returns the value, pointed by the \a iter.
*
* \param iter Opaque iterator value
* \param iter Iterator
*
* \return Returns value, pointed by iterator.
*/

8
src/IO.c
View File

@@ -224,3 +224,11 @@ int BH_IOClear(BH_IO *io)
/* Call the IO device clear error handler */
return io->cb(io + 1, BH_IO_CLEAR_CB, NULL, NULL);
}
BH_IO *BH_BufferNew(BH_IO *io)
{
(void)io;
return NULL;
}