diff options
| -rw-r--r-- | include/BH/Algo.h | 91 | ||||
| -rw-r--r-- | include/BH/Hashmap.h | 75 | ||||
| -rw-r--r-- | include/BH/IO.h | 112 | ||||
| -rw-r--r-- | include/BH/Queue.h | 65 | ||||
| -rw-r--r-- | src/IO.c | 8 |
5 files changed, 179 insertions, 172 deletions
diff --git a/include/BH/Algo.h b/include/BH/Algo.h index 2e5320e..4cb940c 100644 --- a/include/BH/Algo.h +++ b/include/BH/Algo.h @@ -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,15 +18,16 @@ 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 size Array size - * \param element Element size in bytes - * \param equal Comparision function + * \param pivot Pivot element pointer + * \param array Array pointer + * \param size Array size + * \param element Array element size + * \param equal Comparision function * * \return Pointer to the first element of the second partition. */ @@ -38,12 +39,15 @@ 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 - * \param size Array size - * \param element Element size in bytes - * \param equal Comparision function + * The sorting algorithm is implementation defined and may change between + * revisions. + * + * \param array Array pointer + * \param size Array size + * \param element Array element size + * \param equal Comparision function */ void BH_Sort(void *array, size_t size, @@ -52,12 +56,12 @@ 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 size Array size - * \param element Element size in bytes - * \param equal Comparision function + * \param array Array pointer + * \param size Array size + * \param element Array element size + * \param equal Comparision function */ void BH_HeapMake(void *array, size_t size, @@ -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,16 +85,17 @@ 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 size Array size - * \param element Element size in bytes - * \param equal Comparasion function + * \param value Value pointer + * \param array Array pointer + * \param size Array size + * \param element Array element size + * \param equal Comparasion function */ void BH_HeapInsert(void *value, void *array, @@ -99,22 +105,17 @@ void BH_HeapInsert(void *value, /** - * Removes top/first element and inserts new element into heap in an array. - * - * If the pointer to value is NULL, this function assumes that the new value - * is at the end of the array. + * Removes top value from heapified \a array (with specified \a size and + * \a element size) and inserts new \a value. * - * 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 + * If 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 size Array size - * \param element Element size in bytes - * \param equal Comparasion function + * \param value Value pointer + * \param array Array pointer + * \param size Array size + * \param element Array element size + * \param equal Comparasion function */ void BH_HeapReplace(void *value, void *array, diff --git a/include/BH/Hashmap.h b/include/BH/Hashmap.h index 615e747..57d04fc 100644 --- a/include/BH/Hashmap.h +++ b/include/BH/Hashmap.h @@ -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 */ + diff --git a/include/BH/IO.h b/include/BH/IO.h index e0a2fea..ab7bec1 100644 --- a/include/BH/IO.h +++ b/include/BH/IO.h @@ -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); diff --git a/include/BH/Queue.h b/include/BH/Queue.h index 5d6af58..48d2ce9 100644 --- a/include/BH/Queue.h +++ b/include/BH/Queue.h @@ -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. */ @@ -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; +} |