Imagelibrary/Containers
1
0
Fork 0
mirror of https://github.com/bkthomps/Containers.git synced 2025-11-16 12:34:47 +00:00
Code Issues Packages Projects Releases Wiki Activity

Improve documentation (#48)

Browse Source
This commit is contained in:
Bailey Thompson
2019-05-30 18:46:33 -04:00
committed by GitHub
parent a180f8c42f
commit c9c22d49d7
16 changed files with 545 additions and 138 deletions
Download Patch File Download Diff File Expand all files Collapse all files

30
src/array.c
View File

@@ -37,7 +37,9 @@ struct internal_array {
* negative
* @param data_size the size of each element in the array; must be positive
*
* @return the newly-initialized array, or NULL if memory allocation error
* @return the newly-initialized array, or NULL if it was not successfully
* initialized due to either invalid input arguments or memory
* allocation error
*/
array array_init(const int element_count, const size_t data_size)
{
@@ -76,7 +78,10 @@ int array_size(array me)
}
/**
* Copies the array to a raw array.
* Copies the array to a raw array. Since it is a copy, the raw array may be
* modified without causing side effects to the array data structure. Memory
* is not allocated, thus the raw array being used for the copy must be
* allocated before this function is called.
*
* @param arr the initialized raw array to copy the array to
* @param me the array to copy to the raw array
@@ -90,10 +95,10 @@ void array_copy_to_array(void *const arr, array me)
}
/**
* Gets the storage element of the array which is contiguous in memory. If the
* data is modified, the data in the array is modified. Also, any array
* operation may invalidate this data pointer. The array owns the data pointer,
* thus it must not be freed.
* Gets the storage element of the array structure. This pointer is not a copy,
* thus any modification to the data will cause the array structure data to be
* modified. Operations using the array functions may invalidate this pointer.
* The array owns this memory, thus it should not be freed.
*
* @param me the array to get the storage element from
*
@@ -113,7 +118,11 @@ static int array_is_illegal_input(array me, const int index)
}
/**
* Sets the data for a specified element in the array.
* Sets the data for a specified element in the array. The pointer to the data
* being passed in should point to the data type which this array holds. For
* example, if this array holds integers, the data pointer should be a pointer
* to an integer. Since the data is being copied, the pointer only has to be
* valid when this function is called.
*
* @param me the array to set data for
* @param index the location to set data at in the array
@@ -133,7 +142,12 @@ int array_set(array me, const int index, void *const data)
}
/**
* Copies the element at index of the array to data.
* Copies the element at index of the array to data. The pointer to the data
* being obtained should point to the data type which this array holds. For
* example, if this array holds integers, the data pointer should be a pointer
* to an integer. Since this data is being copied from the array to the data
* pointer, the pointer only has to be valid when this function is called.
*
*
* @param data the data to copy to
* @param me the array to copy from

71
src/deque.c
View File

@@ -44,7 +44,9 @@ struct node {
*
* @param data_size the size of each element in the deque; must be positive
*
* @return the newly-initialized deque, or NULL if memory allocation error
* @return the newly-initialized deque, or NULL if it was not successfully
* initialized due to either invalid input arguments or memory
* allocation error
*/
deque deque_init(const size_t data_size)
{
@@ -145,7 +147,10 @@ int deque_trim(deque me)
}
/**
* Copies the deque to an array.
* Copies the deque to an array. Since it is a copy, the array may be modified
* without causing side effects to the deque data structure. Memory is not
* allocated, thus the array being used for the copy must be allocated before
* this function is called.
*
* @param arr the initialized array to copy the deque to
* @param me the deque to copy to the array
@@ -159,7 +164,11 @@ void deque_copy_to_array(void *const arr, deque me)
}
/**
* Adds an element to the front of the deque.
* Adds an element to the front of the deque. The pointer to the data being
* passed in should point to the data type which this deque holds. For example,
* if this deque holds integers, the data pointer should be a pointer to an
* integer. Since the data is being copied, the pointer only has to be valid
* when this function is called.
*
* @param me the deque to add an element to
* @param data the element to add
@@ -221,7 +230,11 @@ int deque_push_front(deque me, void *const data)
}
/**
* Adds an element to the back of the deque.
* Adds an element to the back of the deque. The pointer to the data being
* passed in should point to the data type which this deque holds. For example,
* if this deque holds integers, the data pointer should be a pointer to an
* integer. Since the data is being copied, the pointer only has to be valid
* when this function is called.
*
* @param me the deque to add an element to
* @param data the element to add
@@ -268,7 +281,12 @@ int deque_push_back(deque me, void *const data)
}
/**
* Removes the front element from the deque and copies it to a data value.
* Removes the front element from the deque and copies it to a data value. The
* pointer to the data being obtained should point to the data type which this
* deque holds. For example, if this deque holds integers, the data pointer
* should be a pointer to an integer. Since this data is being copied from the
* array to the data pointer, the pointer only has to be valid when this
* function is called.
*
* @param data the value to copy to
* @param me the deque to remove from
@@ -294,7 +312,12 @@ int deque_pop_front(void *const data, deque me)
}
/**
* Removes the back element from the deque and copies it to a data value.
* Removes the back element from the deque and copies it to a data value. The
* pointer to the data being obtained should point to the data type which this
* deque holds. For example, if this deque holds integers, the data pointer
* should be a pointer to an integer. Since this data is being copied from the
* array to the data pointer, the pointer only has to be valid when this
* function is called.
*
* @param data the value to copy to
* @param me the deque to remove from
@@ -320,7 +343,11 @@ int deque_pop_back(void *const data, deque me)
}
/**
* Sets the first value of the deque.
* Sets the first value of the deque. The pointer to the data being passed in
* should point to the data type which this deque holds. For example, if this
* deque holds integers, the data pointer should be a pointer to an integer.
* Since the data is being copied, the pointer only has to be valid when this
* function is called.
*
* @param me the deque to set value of
* @param data the data to set
@@ -334,7 +361,11 @@ int deque_set_first(deque me, void *const data)
}
/**
* Sets the value of the deque at the specified index.
* Sets the value of the deque at the specified index. The pointer to the data
* being passed in should point to the data type which this deque holds. For
* example, if this deque holds integers, the data pointer should be a pointer
* to an integer. Since the data is being copied, the pointer only has to be
* valid when this function is called.
*
* @param me the deque to set value of
* @param index the index to set at
@@ -361,7 +392,11 @@ int deque_set_at(deque me, int index, void *const data)
}
/**
* Sets the last value of the deque.
* Sets the last value of the deque. The pointer to the data being passed in
* should point to the data type which this deque holds. For example, if this
* deque holds integers, the data pointer should be a pointer to an integer.
* Since the data is being copied, the pointer only has to be valid when this
* function is called.
*
* @param me the deque to set value of
* @param data the data to set
@@ -375,7 +410,11 @@ int deque_set_last(deque me, void *const data)
}
/**
* Gets the first value of the deque.
* Gets the first value of the deque. The pointer to the data being obtained
* should point to the data type which this deque holds. For example, if this
* deque holds integers, the data pointer should be a pointer to an integer.
* Since this data is being copied from the array to the data pointer, the
* pointer only has to be valid when this function is called.
*
* @param data the data to set
* @param me the deque to set value of
@@ -389,7 +428,11 @@ int deque_get_first(void *const data, deque me)
}
/**
* Gets the value of the deque at the specified index.
* Gets the value of the deque at the specified index. The pointer to the data
* being obtained should point to the data type which this deque holds. For
* example, if this deque holds integers, the data pointer should be a pointer
* to an integer. Since this data is being copied from the array to the data
* pointer, the pointer only has to be valid when this function is called.
*
* @param data the data to set
* @param me the deque to set value of
@@ -416,7 +459,11 @@ int deque_get_at(void *const data, deque me, int index)
}
/**
* Gets the last value of the deque.
* Gets the last value of the deque. The pointer to the data being obtained
* should point to the data type which this deque holds. For example, if this
* deque holds integers, the data pointer should be a pointer to an integer.
* Since this data is being copied from the array to the data pointer, the
* pointer only has to be valid when this function is called.
*
* @param data the data to set
* @param me the deque to set value of

67
src/forward_list.c
View File

@@ -40,8 +40,9 @@ struct node {
*
* @param data_size the size of data to store; must be positive
*
* @return the newly-initialized singly-linked list, or NULL if memory
* allocation error
* @return the newly-initialized singly-linked list, or NULL if it was not
* successfully initialized due to either invalid input arguments or
* memory allocation error
*/
forward_list forward_list_init(const size_t data_size)
{
@@ -84,7 +85,10 @@ int forward_list_is_empty(forward_list me)
}
/**
* Copies the nodes of the singly-linked list to an array.
* Copies the nodes of the singly-linked list to an array. Since it is a copy,
* the array may be modified without causing side effects to the singly-linked
* list data structure. Memory is not allocated, thus the array being used for
* the copy must be allocated before this function is called.
*
* @param arr the initialized array to copy the singly-linked list to
* @param me the singly-linked list to copy to the array
@@ -114,7 +118,11 @@ static struct node *forward_list_get_node_at(forward_list me, const int index)
}
/**
* Adds data at the first index in the singly-linked list.
* Adds data at the first index in the singly-linked list. The pointer to the
* data being passed in should point to the data type which this singly-linked
* list holds. For example, if this singly-linked list holds integers, the data
* pointer should be a pointer to an integer. Since the data is being copied,
* the pointer only has to be valid when this function is called.
*
* @param me the singly-linked list to add data to
* @param data the data to add to the singly-linked list
@@ -128,7 +136,11 @@ int forward_list_add_first(forward_list me, void *const data)
}
/**
* Adds data at a specified index in the singly-linked list.
* Adds data at a specified index in the singly-linked list. The pointer to the
* data being passed in should point to the data type which this singly-linked
* list holds. For example, if this singly-linked list holds integers, the data
* pointer should be a pointer to an integer. Since the data is being copied,
* the pointer only has to be valid when this function is called.
*
* @param me the singly-linked list to add data to
* @param index the index to add the data at
@@ -167,7 +179,11 @@ int forward_list_add_at(forward_list me, const int index, void *const data)
}
/**
* Adds data at the last index in the singly-linked list.
* Adds data at the last index in the singly-linked list. The pointer to the
* data being passed in should point to the data type which this singly-linked
* list holds. For example, if this singly-linked list holds integers, the data
* pointer should be a pointer to an integer. Since the data is being copied,
* the pointer only has to be valid when this function is called.
*
* @param me the singly-linked list to add data to
* @param data the data to add to the singly-linked list
@@ -250,7 +266,11 @@ int forward_list_remove_last(forward_list me)
}
/**
* Sets the data at the first index in the singly-linked list.
* Sets the data at the first index in the singly-linked list. The pointer to
* the data being passed in should point to the data type which this singly-
* linked list holds. For example, if this singly-linked list holds integers,
* the data pointer should be a pointer to an integer. Since the data is being
* copied, the pointer only has to be valid when this function is called.
*
* @param me the singly-linked list to set data for
* @param data the data to set in the singly-linked list
@@ -264,7 +284,11 @@ int forward_list_set_first(forward_list me, void *const data)
}
/**
* Sets the data at the specified index in the singly-linked list.
* Sets the data at the specified index in the singly-linked list. The pointer
* to the data being passed in should point to the data type which this singly-
* linked list holds. For example, if this singly-linked list holds integers,
* the data pointer should be a pointer to an integer. Since the data is being
* copied, the pointer only has to be valid when this function is called.
*
* @param me the singly-linked list to set data for
* @param index the index to set data in the singly-linked list
@@ -285,7 +309,11 @@ int forward_list_set_at(forward_list me, const int index, void *const data)
}
/**
* Sets the data at the last index in the singly-linked list.
* Sets the data at the last index in the singly-linked list. The pointer to
* the data being passed in should point to the data type which this singly-
* linked list holds. For example, if this singly-linked list holds integers,
* the data pointer should be a pointer to an integer. Since the data is being
* copied, the pointer only has to be valid when this function is called.
*
* @param me the singly-linked list to set data for
* @param data the data to set in the singly-linked list
@@ -299,7 +327,12 @@ int forward_list_set_last(forward_list me, void *const data)
}
/**
* Gets the data at the first index in the singly-linked list.
* Gets the data at the first index in the singly-linked list. The pointer to
* the data being obtained should point to the data type which this singly-
* linked list holds. For example, if this singly-linked list holds integers,
* the data pointer should be a pointer to an integer. Since this data is being
* copied from the array to the data pointer, the pointer only has to be valid
* when this function is called.
*
* @param data the data to get
* @param me the singly-linked list to get data from
@@ -313,7 +346,12 @@ int forward_list_get_first(void *const data, forward_list me)
}
/**
* Gets the data at the specified index in the singly-linked list.
* Gets the data at the specified index in the singly-linked list. The pointer
* to the data being obtained should point to the data type which this singly-
* linked list holds. For example, if this singly-linked list holds integers,
* the data pointer should be a pointer to an integer. Since this data is being
* copied from the array to the data pointer, the pointer only has to be valid
* when this function is called.
*
* @param data the data to get
* @param me the singly-linked list to get data from
@@ -334,7 +372,12 @@ int forward_list_get_at(void *const data, forward_list me, const int index)
}
/**
* Gets the data at the last index in the singly-linked list.
* Gets the data at the last index in the singly-linked list. The pointer to
* the data being obtained should point to the data type which this singly-
* linked list holds. For example, if this singly-linked list holds integers,
* the data pointer should be a pointer to an integer. Since this data is being
* copied from the array to the data pointer, the pointer only has to be valid
* when this function is called.
*
* @param data the data to get
* @param me the singly-linked list to get data from

67
src/list.c
View File

@@ -42,8 +42,9 @@ struct node {
*
* @param data_size the size of data to store; must be positive
*
* @return the newly-initialized doubly-linked list, or NULL if memory
* allocation error
* @return the newly-initialized doubly-linked list, or NULL if it was not
* successfully initialized due to either invalid input arguments or
* memory allocation error
*/
list list_init(const size_t data_size)
{
@@ -87,7 +88,10 @@ int list_is_empty(list me)
}
/**
* Copies the nodes of the doubly-linked list to an array.
* Copies the nodes of the doubly-linked list to an array.Since it is a copy,
* the array may be modified without causing side effects to the doubly-linked
* list data structure. Memory is not allocated, thus the array being used for
* the copy must be allocated before this function is called.
*
* @param arr the initialized array to copy the doubly-linked list to
* @param me the doubly-linked list to copy to the array
@@ -142,7 +146,11 @@ static struct node *list_get_node_at(list me, const int index)
}
/**
* Adds data at the first index in the doubly-linked list.
* Adds data at the first index in the doubly-linked list. The pointer to the
* data being passed in should point to the data type which this doubly-linked
* list holds. For example, if this doubly-linked list holds integers, the data
* pointer should be a pointer to an integer. Since the data is being copied,
* the pointer only has to be valid when this function is called.
*
* @param me the doubly-linked list to add data to
* @param data the data to add to the doubly-linked list
@@ -156,7 +164,11 @@ int list_add_first(list me, void *const data)
}
/**
* Adds data at a specified index in the doubly-linked list.
* Adds data at a specified index in the doubly-linked list. The pointer to the
* data being passed in should point to the data type which this doubly-linked
* list holds. For example, if this doubly-linked list holds integers, the data
* pointer should be a pointer to an integer. Since the data is being copied,
* the pointer only has to be valid when this function is called.
*
* @param me the doubly-linked list to add data to
* @param index the index to add the data at
@@ -211,7 +223,11 @@ int list_add_at(list me, const int index, void *const data)
}
/**
* Adds data at the last index in the doubly-linked list.
* Adds data at the last index in the doubly-linked list. The pointer to the
* data being passed in should point to the data type which this doubly-linked
* list holds. For example, if this doubly-linked list holds integers, the data
* pointer should be a pointer to an integer. Since the data is being copied,
* the pointer only has to be valid when this function is called.
*
* @param me the doubly-linked list to add data to
* @param data the data to add to the doubly-linked list
@@ -291,7 +307,11 @@ int list_remove_last(list me)
}
/**
* Sets the data at the first index in the doubly-linked list.
* Sets the data at the first index in the doubly-linked list. The pointer to
* the data being passed in should point to the data type which this doubly-
* linked list holds. For example, if this doubly-linked list holds integers,
* the data pointer should be a pointer to an integer. Since the data is being
* copied, the pointer only has to be valid when this function is called.
*
* @param me the doubly-linked list to set data for
* @param data the data to set in the doubly-linked list
@@ -305,7 +325,11 @@ int list_set_first(list me, void *const data)
}
/**
* Sets the data at the specified index in the doubly-linked list.
* Sets the data at the specified index in the doubly-linked list. The pointer
* to the data being passed in should point to the data type which this doubly-
* linked list holds. For example, if this doubly-linked list holds integers,
* the data pointer should be a pointer to an integer. Since the data is being
* copied, the pointer only has to be valid when this function is called.
*
* @param me the doubly-linked list to set data for
* @param index the index to set data in the doubly-linked list
@@ -326,7 +350,11 @@ int list_set_at(list me, const int index, void *const data)
}
/**
* Sets the data at the last index in the doubly-linked list.
* Sets the data at the last index in the doubly-linked list. The pointer to
* the data being passed in should point to the data type which this doubly-
* linked list holds. For example, if this doubly-linked list holds integers,
* the data pointer should be a pointer to an integer. Since the data is being
* copied, the pointer only has to be valid when this function is called.
*
* @param me the doubly-linked list to set data for
* @param data the data to set in the doubly-linked list
@@ -340,7 +368,12 @@ int list_set_last(list me, void *const data)
}
/**
* Gets the data at the first index in the doubly-linked list.
* Gets the data at the first index in the doubly-linked list. The pointer to
* the data being obtained should point to the data type which this doubly-
* linked list holds. For example, if this doubly-linked list holds integers,
* the data pointer should be a pointer to an integer. Since this data is being
* copied from the array to the data pointer, the pointer only has to be valid
* when this function is called.
*
* @param data the data to get
* @param me the doubly-linked list to get data from
@@ -354,7 +387,12 @@ int list_get_first(void *const data, list me)
}
/**
* Gets the data at the specified index in the doubly-linked list.
* Gets the data at the specified index in the doubly-linked list. The pointer
* to the data being obtained should point to the data type which this doubly-
* linked list holds. For example, if this doubly-linked list holds integers,
* the data pointer should be a pointer to an integer. Since this data is being
* copied from the array to the data pointer, the pointer only has to be valid
* when this function is called.
*
* @param data the data to get
* @param me the doubly-linked list to get data from
@@ -375,7 +413,12 @@ int list_get_at(void *const data, list me, const int index)
}
/**
* Gets the data at the last index in the doubly-linked list.
* Gets the data at the last index in the doubly-linked list. The pointer to
* the data being obtained should point to the data type which this doubly-
* linked list holds. For example, if this doubly-linked list holds integers,
* the data pointer should be a pointer to an integer. Since this data is being
* copied from the array to the data pointer, the pointer only has to be valid
* when this function is called.
*
* @param data the data to get
* @param me the doubly-linked list to get data from

29
src/map.c
View File

@@ -49,7 +49,9 @@ struct node {
* @param comparator the comparator function used for key ordering; must not be
* NULL
*
* @return the newly-initialized map, or NULL if memory allocation error
* @return the newly-initialized map, or NULL if it was not successfully
* initialized due to either invalid input arguments or memory
* allocation error
*/
map map_init(const size_t key_size,
const size_t value_size,
@@ -318,7 +320,11 @@ static struct node *map_create_node(map me,
/**
* Adds a key-value pair to the map. If the map already contains the key, the
* value is updated to the new value.
* value is updated to the new value. The pointer to the key and value being
* passed in should point to the key and value type which this map holds. For
* example, if this map holds integer keys and values, the key and value pointer
* should be a pointer to an integer. Since the key and value are being copied,
* the pointer only has to be valid when this function is called.
*
* @param me the map to add to
* @param key the key to add
@@ -402,7 +408,12 @@ static struct node *map_equal_match(map me, const void *const key)
}
/**
* Gets the value associated with a key in the map.
* Gets the value associated with a key in the map. The pointer to the key being
* passed in and the value being obtained should point to the key and value
* types which this map holds. For example, if this map holds integer keys and
* values, the key and value pointers should be a pointer to an integer. Since
* the key and value are being copied, the pointer only has to be valid when
* this function is called.
*
* @param value the value to copy to
* @param me the map to get from
@@ -421,7 +432,11 @@ int map_get(void *const value, map me, void *const key)
}
/**
* Determines if the map contains the specified key.
* Determines if the map contains the specified key. The pointer to the key
* being passed in should point to the key type which this map holds. For
* example, if this map holds key integers, the key pointer should be a pointer
* to an integer. Since the key is being copied, the pointer only has to be
* valid when this function is called.
*
* @param me the map to check for the element
* @param key the key to check
@@ -626,7 +641,11 @@ static void map_remove_element(map me, struct node *const traverse)
}
/**
* Removes the key-value pair from the map if it contains it.
* Removes the key-value pair from the map if it contains it. The pointer to the
* key being passed in should point to the key type which this map holds. For
* example, if this map holds key integers, the key pointer should be a pointer
* to an integer. Since the key is being copied, the pointer only has to be
* valid when this function is called.
*
* @param me the map to remove an element from
* @param key the key to remove

46
src/multimap.c
View File

@@ -59,7 +59,9 @@ struct value_node {
* @param key_comparator the key comparator function; must not be NULL
* @param value_comparator the value comparator function; must not be NULL
*
* @return the newly-initialized multi-map, or NULL if memory allocation error
* @return the newly-initialized multi-map, or NULL if it was not successfully
* initialized due to either invalid input arguments or memory
* allocation error
*/
multimap multimap_init(const size_t key_size,
const size_t value_size,
@@ -353,7 +355,13 @@ static struct node *multimap_create_node(multimap me,
}
/**
* Adds a key-value pair to the multi-map.
* Adds a key-value pair to the multi-map. If the multi-map already contains the
* key, the value is updated to the new value. The pointer to the key and value
* being passed in should point to the key and value type which this multi-map
* holds. For example, if this multi-map holds integer keys and values, the key
* and value pointer should be a pointer to an integer. Since the key and value
* are being copied, the pointer only has to be valid when this function is
* called.
*
* @param me the multi-map to add to
* @param key the key to add
@@ -447,7 +455,10 @@ static struct node *multimap_equal_match(multimap me, const void *const key)
/**
* Creates the iterator for the specified key. To iterate over the values, keep
* getting the next value. Between starting and iterations, the multi-map must
* not be mutated.
* not be mutated. The pointer to the key being passed in should point to the
* key type which this multi-map holds. For example, if this multi-map holds key
* integers, the key pointer should be a pointer to an integer. Since the key is
* being copied, the pointer only has to be valid when this function is called.
*
* @param me the multi-map to start the iterator for
* @param key the key to start the iterator for
@@ -463,6 +474,10 @@ void multimap_get_start(multimap me, void *const key)
/**
* Iterates over the values for the specified key. Must be called after starting
* the iterator. The multi-map must not be mutated between start and iterations.
* The pointer to the value being obtained should point to the value type which
* this multi-map holds. For example, if this multi-map holds value integers,
* the value pointer should be a pointer to an integer. Since the value is being
* copied, the pointer only has to be valid when this function is called.
*
* @param value the value to be copied to from iteration
* @param me the multi-map to iterate over
@@ -483,7 +498,11 @@ int multimap_get_next(void *const value, multimap me)
}
/**
* Determines the amount of times the key appears in the multi-map.
* Determines the amount of times the key appears in the multi-map. The pointer
* to the key being passed in should point to the key type which this multi-map
* holds. For example, if this multi-map holds key integers, the key pointer
* should be a pointer to an integer. Since the key is being copied, the pointer
* only has to be valid when this function is called.
*
* @param me the multi-map to check for the key
* @param key the key to check
@@ -500,7 +519,11 @@ int multimap_count(multimap me, void *const key)
}
/**
* Determines if the multi-map contains the specified key.
* Determines if the multi-map contains the specified key. The pointer to the
* key being passed in should point to the key type which this multi-map holds.
* For example, if this multi-map holds key integers, the key pointer should be
* a pointer to an integer. Since the key is being copied, the pointer only has
* to be valid when this function is called.
*
* @param me the multi-map to check for the key
* @param key the key to check
@@ -706,7 +729,12 @@ static void multimap_remove_element(multimap me, struct node *const traverse)
}
/**
* Removes the key-value pair from the multi-map if it contains it.
* Removes the key-value pair from the multi-map if it contains it. The pointer
* to the key and value being passed in should point to the key and value type
* which this multi-map holds. For example, if this multi-map holds integer keys
* and values, the key and value pointer should be a pointer to an integer.
* Since the key and value are being copied, the pointer only has to be valid
* when this function is called.
*
* @param me the multi-map to remove an key from
* @param key the key to remove
@@ -764,7 +792,11 @@ static void multimap_remove_all_element(multimap me,
}
/**
* Removes all the key-value pairs from the multi-map specified by the key.
* Removes all the key-value pairs from the multi-map specified by the key. The
* pointer to the key being passed in should point to the key type which this
* multi-map holds. For example, if this multi-map holds key integers, the key
* pointer should be a pointer to an integer. Since the key is being copied,
* the pointer only has to be valid when this function is called.
*
* @param me the multi-map to remove a key-value pair from
* @param key the key to remove

34
src/multiset.c
View File

@@ -48,7 +48,9 @@ struct node {
* @param comparator the comparator function used for key ordering; must not be
* NULL
*
* @return the newly-initialized multi-set, or NULL if memory allocation error
* @return the newly-initialized multi-set, or NULL if it was not successfully
* initialized due to either invalid input arguments or memory
* allocation error
*/
multiset multiset_init(const size_t key_size,
int (*const comparator)(const void *const,
@@ -308,7 +310,11 @@ static struct node *multiset_create_node(multiset me,
}
/**
* Adds a key to the multi-set.
* Adds a key to the multi-set. The pointer to the key being passed in should
* point to the key type which this multi-set holds. For example, if this
* multi-set holds key integers, the key pointer should be a pointer to an
* integer. Since the key is being copied, the pointer only has to be valid
* when this function is called.
*
* @param me the multi-set to add to
* @param key the key to add
@@ -392,7 +398,11 @@ static struct node *multiset_equal_match(multiset me, const void *const key)
}
/**
* Determines the count of a specific key in the multi-set.
* Determines the count of a specific key in the multi-set. The pointer to the
* key being passed in should point to the key type which this multi-set holds.
* For example, if this multi-set holds key integers, the key pointer should be
* a pointer to an integer. Since the key is being copied, the pointer only has
* to be valid when this function is called.
*
* @param me the multi-set to check for the count
* @param key the key to check
@@ -409,7 +419,11 @@ int multiset_count(multiset me, void *const key)
}
/**
* Determines if the multi-set contains the specified key.
* Determines if the multi-set contains the specified key. The pointer to the
* key being passed in should point to the key type which this multi-set holds.
* For example, if this multi-set holds key integers, the key pointer should be
* a pointer to an integer. Since the key is being copied, the pointer only has
* to be valid when this function is called.
*
* @param me the multi-set to check for the key
* @param key the key to check
@@ -615,7 +629,11 @@ static void multiset_remove_element(multiset me, struct node *const traverse)
}
/**
* Removes a key from the multi-set if it contains it.
* Removes a key from the multi-set if it contains it. The pointer to the key
* being passed in should point to the key type which this multi-set holds. For
* example, if this multi-set holds key integers, the key pointer should be a
* pointer to an integer. Since the key is being copied, the pointer only has
* to be valid when this function is called.
*
* @param me the multi-set to remove a key from
* @param key the key to remove
@@ -637,7 +655,11 @@ int multiset_remove(multiset me, void *const key)
}
/**
* Removes all the occurrences of a specified key in the multi-set.
* Removes all the occurrences of a specified key in the multi-set. The pointer
* to the key being passed in should point to the key type which this multi-set
* holds. For example, if this multi-set holds key integers, the key pointer
* should be a pointer to an integer. Since the key is being copied, the pointer
* only has to be valid when this function is called.
*
* @param me the multi-set to remove a key from
* @param key the key to remove

25
src/priority_queue.c
View File

@@ -38,8 +38,9 @@ struct internal_priority_queue {
* positive
* @param comparator the priority comparator function; must not be NULL
*
* @return the newly-initialized priority queue, or NULL if memory allocation
* error
* @return the newly-initialized priority queue, or NULL if it was not
* successfully initialized due to either invalid input arguments or
* memory allocation error
*/
priority_queue priority_queue_init(const size_t data_size,
int (*comparator)(const void *const,
@@ -88,7 +89,11 @@ int priority_queue_is_empty(priority_queue me)
}
/**
* Adds an element to the priority queue.
* Adds an element to the priority queue. The pointer to the data being passed
* in should point to the data type which this priority queue holds. For
* example, if this priority queue holds integers, the data pointer should be a
* pointer to an integer. Since the data is being copied, the pointer only has
* to be valid when this function is called.
*
* @param me the priority queue to add an element to
* @param data the data to add to the queue
@@ -133,7 +138,12 @@ int priority_queue_push(priority_queue me, void *const data)
}
/**
* Removes the highest priority element from the priority queue.
* Removes the highest priority element from the priority queue. The pointer to
* the data being obtained should point to the data type which this priority
* queue holds. For example, if this priority queue holds integers, the data
* pointer should be a pointer to an integer. Since this data is being copied
* from the array to the data pointer, the pointer only has to be valid when
* this function is called.
*
* @param data the data to have copied from the priority queue
* @param me the priority queue to pop the next element from
@@ -195,7 +205,12 @@ int priority_queue_pop(void *const data, priority_queue me)
}
/**
* Gets the highest priority element in the priority queue.
* Gets the highest priority element in the priority queue. The pointer to the
* data being obtained should point to the data type which this priority queue
* holds. For example, if this priority queue holds integers, the data pointer
* should be a pointer to an integer. Since this data is being copied from the
* array to the data pointer, the pointer only has to be valid when this
* function is called.
*
* @param data the out copy of the highest priority element in the priority
* queue

33
src/queue.c
View File

@@ -35,7 +35,9 @@ struct internal_queue {
*
* @param data_size the size of each element; must be positive
*
* @return the newly-initialized queue, or NULL if memory allocation error
* @return the newly-initialized queue, or NULL if it was not successfully
* initialized due to either invalid input arguments or memory
* allocation error
*/
queue queue_init(const size_t data_size)
{
@@ -95,7 +97,10 @@ int queue_trim(queue me)
}
/**
* Copies the queue to an array.
* Copies the queue to an array. Since it is a copy, the array may be modified
* without causing side effects to the queue data structure. Memory is not
* allocated, thus the array being used for the copy must be allocated before
* this function is called.
*
* @param arr the initialized array to copy the queue to
* @param me the queue to copy to the array
@@ -106,7 +111,11 @@ void queue_copy_to_array(void *const arr, queue me)
}
/**
* Adds an element to the queue.
* Adds an element to the queue. The pointer to the data being passed in should
* point to the data type which this queue holds. For example, if this queue
* holds integers, the data pointer should be a pointer to an integer. Since the
* data is being copied, the pointer only has to be valid when this function is
* called.
*
* @param me the queue to add an element to
* @param data the data to add to the queue
@@ -120,7 +129,11 @@ int queue_push(queue me, void *const data)
}
/**
* Removes the next element in the queue and copies the data.
* Removes the next element in the queue and copies the data. The pointer to the
* data being obtained should point to the data type which this queue holds. For
* example, if this queue holds integers, the data pointer should be a pointer
* to an integer. Since this data is being copied from the array to the data
* pointer, the pointer only has to be valid when this function is called.
*
* @param data the data to have copied from the queue
* @param me the queue to pop the next element from
@@ -138,7 +151,11 @@ int queue_pop(void *const data, queue me)
}
/**
* Gets the front element of the queue.
* Gets the front element of the queue. The pointer to the data being obtained
* should point to the data type which this queue holds. For example, if this
* queue holds integers, the data pointer should be a pointer to an integer.
* Since this data is being copied from the array to the data pointer, the
* pointer only has to be valid when this function is called.
*
* @param data the copy of the front element of the queue
* @param me the queue to copy from
@@ -151,7 +168,11 @@ int queue_front(void *const data, queue me)
}
/**
* Gets the back element of the queue.
* Gets the back element of the queue. The pointer to the data being obtained
* should point to the data type which this queue holds. For example, if this
* queue holds integers, the data pointer should be a pointer to an integer.
* Since this data is being copied from the array to the data pointer, the
* pointer only has to be valid when this function is called.
*
* @param data the copy of the back element of the queue
* @param me the queue to copy from

22
src/set.c
View File

@@ -46,7 +46,9 @@ struct node {
* @param comparator the comparator function used for key ordering; must not be
* NULL
*
* @return the newly-initialized set, or NULL if memory allocation error
* @return the newly-initialized set, or NULL if it was not successfully
* initialized due to either invalid input arguments or memory
* allocation error
*/
set set_init(const size_t key_size,
int (*const comparator)(const void *const, const void *const))
@@ -304,7 +306,11 @@ static struct node *set_create_node(set me,
}
/**
* Adds a key to the set if the set does not already contain it.
* Adds a key to the set if the set does not already contain it. The pointer to
* the key being passed in should point to the key type which this set holds.
* For example, if this set holds key integers, the key pointer should be a
* pointer to an integer. Since the key is being copied, the pointer only has
* to be valid when this function is called.
*
* @param me the set to add to
* @param key the key to add
@@ -386,7 +392,11 @@ static struct node *set_equal_match(set me, const void *const key)
}
/**
* Determines if the set contains the specified key.
* Determines if the set contains the specified key. The pointer to the key
* being passed in should point to the key type which this set holds. For
* example, if this set holds key integers, the key pointer should be a pointer
* to an integer. Since the key is being copied, the pointer only has to be
* valid when this function is called.
*
* @param me the set to check for the key
* @param key the key to check
@@ -590,7 +600,11 @@ static void set_remove_element(set me, struct node *const traverse)
}
/**
* Removes the key from the set if it contains it.
* Removes the key from the set if it contains it. The pointer to the key
* being passed in should point to the key type which this set holds. For
* example, if this set holds key integers, the key pointer should be a pointer
* to an integer. Since the key is being copied, the pointer only has to be
* valid when this function is called.
*
* @param me the set to remove an key from
* @param key the key to remove

27
src/stack.c
View File

@@ -33,7 +33,9 @@ struct internal_stack {
* @param data_size the size of each data element in the stack; must be
* positive
*
* @return the newly-initialized stack, or NULL if memory allocation error
* @return the newly-initialized stack, or NULL if it was not successfully
* initialized due to either invalid input arguments or memory
* allocation error
*/
stack stack_init(const size_t data_size)
{
@@ -91,7 +93,10 @@ int stack_trim(stack me)
}
/**
* Copies the stack to an array.
* Copies the stack to an array. Since it is a copy, the array may be modified
* without causing side effects to the stack data structure. Memory is not
* allocated, thus the array being used for the copy must be allocated before
* this function is called.
*
* @param arr the initialized array to copy the stack to
* @param me the stack to copy to the array
@@ -102,7 +107,11 @@ void stack_copy_to_array(void *const arr, stack me)
}
/**
* Adds an element to the top of the stack.
* Adds an element to the top of the stack. The pointer to the data being passed
* in should point to the data type which this stack holds. For example, if this
* stack holds integers, the data pointer should be a pointer to an integer.
* Since the data is being copied, the pointer only has to be valid when this
* function is called.
*
* @param me the stack to add an element to
* @param data the data to add to the stack
@@ -117,7 +126,11 @@ int stack_push(stack me, void *const data)
/**
* Removes the top element of the stack, and copies the data which is being
* removed.
* removed. The pointer to the data being obtained should point to the data type
* which this stack holds. For example, if this stack holds integers, the data
* pointer should be a pointer to an integer. Since this data is being copied
* from the array to the data pointer, the pointer only has to be valid when
* this function is called.
*
* @param data the copy of the element being removed
* @param me the stack to remove the top element from
@@ -130,7 +143,11 @@ int stack_pop(void *const data, stack me)
}
/**
* Copies the top element of the stack.
* Copies the top element of the stack. The pointer to the data being obtained
* should point to the data type which this stack holds. For example, if this
* stack holds integers, the data pointer should be a pointer to an integer.
* Since this data is being copied from the array to the data pointer, the
* pointer only has to be valid when this function is called.
*
* @param data the copy of the top element of the stack
* @param me the stack to copy from

33
src/unordered_map.c
View File

@@ -70,8 +70,9 @@ static unsigned long unordered_map_hash(unordered_map me,
* @param comparator the comparator function which compares two keys; must not
* be NULL
*
* @return the newly-initialized unordered map, or NULL if memory allocation
* error
* @return the newly-initialized unordered map, or NULL if it was not
* successfully initialized due to either invalid input arguments or
* memory allocation error
*/
unordered_map unordered_map_init(const size_t key_size,
const size_t value_size,
@@ -216,7 +217,7 @@ static int unordered_map_is_equal(unordered_map me,
/*
* Creates an element to add.
*/
static struct node *const unordered_map_create_element(unordered_map me,
static struct node *unordered_map_create_element(unordered_map me,
const unsigned long hash,
const void *const key,
const void *const value)
@@ -245,7 +246,12 @@ static struct node *const unordered_map_create_element(unordered_map me,
/**
* Adds a key-value pair to the unordered map. If the unordered map already
* contains the key, the value is updated to the new value.
* contains the key, the value is updated to the new value. The pointer to the
* key and value being passed in should point to the key and value type which
* this unordered map holds. For example, if this unordered map holds integer
* keys and values, the key and value pointer should be a pointer to an integer.
* Since the key and value are being copied, the pointer only has to be valid
* when this function is called.
*
* @param me the unordered map to add to
* @param key the key to add
@@ -293,7 +299,12 @@ int unordered_map_put(unordered_map me, void *const key, void *const value)
}
/**
* Gets the value associated with a key in the unordered map.
* Gets the value associated with a key in the unordered map. The pointer to the
* key being passed in and the value being obtained should point to the key and
* value types which this unordered map holds. For example, if this unordered
* map holds integer keys and values, the key and value pointers should be a
* pointer to an integer. Since the key and value are being copied, the pointer
* only has to be valid when this function is called.
*
* @param value the value to copy to
* @param me the unordered map to get from
@@ -317,7 +328,11 @@ int unordered_map_get(void *const value, unordered_map me, void *const key)
}
/**
* Determines if the unordered map contains the specified key.
* Determines if the unordered map contains the specified key. The pointer to
* the key being passed in should point to the key type which this unordered map
* holds. For example, if this unordered map holds key integers, the key pointer
* should be a pointer to an integer. Since the key is being copied, the pointer
* only has to be valid when this function is called.
*
* @param me the unordered map to check for the key
* @param key the key to check
@@ -339,7 +354,11 @@ int unordered_map_contains(unordered_map me, void *const key)
}
/**
* Removes the key-value pair from the unordered map if it contains it.
* Removes the key-value pair from the unordered map if it contains it. The
* pointer to the key being passed in should point to the key type which this
* unordered map holds. For example, if this unordered map holds key integers,
* the key pointer should be a pointer to an integer. Since the key is being
* copied, the pointer only has to be valid when this function is called.
*
* @param me the unordered map to remove an key from
* @param key the key to remove

51
src/unordered_multimap.c
View File

@@ -76,8 +76,9 @@ static unsigned long unordered_multimap_hash(unordered_multimap me,
* @param value_comparator the comparator function which compares two values;
* must not be NULL
*
* @return the newly-initialized unordered multi-map, or NULL if memory
* allocation error
* @return the newly-initialized unordered multi-map, or NULL if it was not
* successfully initialized due to either invalid input arguments or
* memory allocation error
*/
unordered_multimap
unordered_multimap_init(const size_t key_size,
@@ -236,8 +237,7 @@ static int unordered_multimap_is_equal(unordered_multimap me,
/*
* Creates an element to add.
*/
static struct node *const
unordered_multimap_create_element(unordered_multimap me,
static struct node *unordered_multimap_create_element(unordered_multimap me,
const unsigned long hash,
const void *const key,
const void *const value)
@@ -265,7 +265,12 @@ unordered_multimap_create_element(unordered_multimap me,
}
/**
* Adds a key-value pair to the unordered multi-map.
* Adds a key-value pair to the unordered multi-map. The pointer to the key and
* value being passed in should point to the key and value type which this
* unordered multi-map holds. For example, if this unordered multi-map holds
* integer keys and values, the key and value pointer should be a pointer to an
* integer. Since the key and value are being copied, the pointer only has to be
* valid when this function is called.
*
* @param me the unordered multi-map to add to
* @param key the key to add
@@ -311,7 +316,11 @@ int unordered_multimap_put(unordered_multimap me,
/**
* Creates the iterator for the specified key. To iterate over the values, keep
* getting the next value. Between starting and iterations, the unordered
* multi-map must not be mutated.
* multi-map must not be mutated. The pointer to the key being passed in should
* point to the key type which this unordered multi-map holds. For example, if
* this unordered multi-map holds key integers, the key pointer should be a
* pointer to an integer. Since the key is being copied, the pointer only has
* to be valid when this function is called.
*
* @param me the unordered multi-map to start the iterator for
* @param key the key to start the iterator for
@@ -337,7 +346,11 @@ void unordered_multimap_get_start(unordered_multimap me, void *const key)
/**
* Iterates over the values for the specified key. Must be called after starting
* the iterator. The unordered multi-map must not be mutated between start and
* iterations.
* iterations.The pointer to the value being obtained should point to the value
* type which this unordered multi-map holds. For example, if this unordered
* multi-map holds value integers, the value pointer should be a pointer to an
* integer. Since the value is being copied, the pointer only has to be valid
* when this function is called.
*
* @param value the value to be copied to from iteration
* @param me the unordered multi-map to iterate over
@@ -370,6 +383,11 @@ int unordered_multimap_get_next(void *const value, unordered_multimap me)
/**
* Determines the amount of times the key appears in the unordered multi-map.
* The pointer to the key being passed in should point to the key type which
* this unordered multi-map holds. For example, if this unordered multi-map
* holds key integers, the key pointer should be a pointer to an integer. Since
* the key is being copied, the pointer only has to be valid when this function
* is called.
*
* @param me the unordered multi-map to check for the key
* @param key the key to check
@@ -392,7 +410,11 @@ int unordered_multimap_count(unordered_multimap me, void *const key)
}
/**
* Determines if the unordered multi-map contains the specified key.
* Determines if the unordered multi-map contains the specified key. The pointer
* to the key being passed in should point to the key type which this unordered
* multi-map holds. For example, if this unordered multi-map holds key integers,
* the key pointer should be a pointer to an integer. Since the key is being
* copied, the pointer only has to be valid when this function is called.
*
* @param me the unordered multi-map to check for the key
* @param key the key to check
@@ -415,6 +437,11 @@ int unordered_multimap_contains(unordered_multimap me, void *const key)
/**
* Removes the key-value pair from the unordered multi-map if it contains it.
* The pointer to the key and value being passed in should point to the key and
* value type which this unordered multi-map holds. For example, if this
* unordered multi-map holds integer keys and values, the key and value pointer
* should be a pointer to an integer. Since the key and value are being copied,
* the pointer only has to be valid when this function is called.
*
* @param me the unordered multi-map to remove an key from
* @param key the key to remove
@@ -461,8 +488,12 @@ int unordered_multimap_remove(unordered_multimap me,
}
/**
* Removes all the key-value pairs from the unordered multi-map specified by the
* key.
* Removes all the key-value pairs from the unordered multi-map specified by
* the key. The pointer to the key being passed in should point to the key
* type which this unordered multi-map holds. For example, if this unordered
* multi-map holds key integers, the key pointer should be a pointer to an
* integer. Since the key is being copied, the pointer only has to be valid
* when this function is called.
*
* @param me the unordered multi-map to remove a key-value pair from
* @param key the key to remove

37
src/unordered_multiset.c
View File

@@ -68,8 +68,9 @@ static unsigned long unordered_multiset_hash(unordered_multiset me,
* @param comparator the comparator function which compares two keys; must not
* be NULL
*
* @return the newly-initialized unordered multi-set, or NULL if memory
* allocation error
* @return the newly-initialized unordered multi-set, or NULL if it was not
* successfully initialized due to either invalid input arguments or
* memory allocation error
*/
unordered_multiset
unordered_multiset_init(const size_t key_size,
@@ -214,8 +215,7 @@ static int unordered_multiset_is_equal(unordered_multiset me,
/*
* Creates an element to add.
*/
static struct node *const
unordered_multiset_create_element(unordered_multiset me,
static struct node *unordered_multiset_create_element(unordered_multiset me,
const unsigned long hash,
const void *const key)
{
@@ -236,7 +236,11 @@ unordered_multiset_create_element(unordered_multiset me,
}
/**
* Adds an element to the unordered multi-set.
* Adds an element to the unordered multi-set. The pointer to the key being
* passed in should point to the key type which this unordered multi-set holds.
* For example, if this multi-set holds key integers, the key pointer should be
* a pointer to an integer. Since the key is being copied, the pointer only has
* to be valid when this function is called.
*
* @param me the unordered multi-set to add to
* @param key the element to add
@@ -286,7 +290,11 @@ int unordered_multiset_put(unordered_multiset me, void *const key)
}
/**
* Determines the count of a specific key in the unordered multi-set.
* Determines the count of a specific key in the unordered multi-set. The
* pointer to the key being passed in should point to the key type which this
* unordered multi-set holds. For example, if this unordered multi-set holds key
* integers, the key pointer should be a pointer to an integer. Since the key is
* being copied, the pointer only has to be valid when this function is called.
*
* @param me the unordered multi-set to check for the count
* @param key the element to check
@@ -308,7 +316,11 @@ int unordered_multiset_count(unordered_multiset me, void *const key)
}
/**
* Determines if the unordered multi-set contains the specified element.
* Determines if the unordered multi-set contains the specified element. The
* pointer to the key being passed in should point to the key type which this
* unordered multi-set holds. For example, if this unordered multi-set holds key
* integers, the key pointer should be a pointer to an integer. Since the key is
* being copied, the pointer only has to be valid when this function is called.
*
* @param me the unordered multi-set to check for the key
* @param key the key to check
@@ -321,7 +333,11 @@ int unordered_multiset_contains(unordered_multiset me, void *const key)
}
/**
* Removes a key from the unordered multi-set if it contains it.
* Removes a key from the unordered multi-set if it contains it. The pointer to
* the key being passed in should point to the key type which this unordered
* multi-set holds. For example, if this unordered multi-set holds key integers,
* the key pointer should be a pointer to an integer. Since the key is being
* copied, the pointer only has to be valid when this function is called.
*
* @param me the unordered multi-set to remove a key from
* @param key the key to remove
@@ -368,7 +384,10 @@ int unordered_multiset_remove(unordered_multiset me, void *const key)
/**
* Removes all the keys specified by the key from an unordered multi-set if it
* contains the key.
* contains the key. The pointer to the key being passed in should point to the
* key type which this multi-set holds. For example, if this multi-set holds key
* integers, the key pointer should be a pointer to an integer. Since the key is
* being copied, the pointer only has to be valid when this function is called.
*
* @param me the unordered multi-set to remove a key from
* @param key the key to remove

25
src/unordered_set.c
View File

@@ -65,8 +65,9 @@ static unsigned long unordered_set_hash(unordered_set me, const void *const key)
* @param comparator the comparator function which compares two keys; must not
* be NULL
*
* @return the newly-initialized unordered set, or NULL if memory allocation
* error
* @return the newly-initialized unordered set, or NULL if it was not
* successfully initialized due to either invalid input arguments or
* memory allocation error
*/
unordered_set unordered_set_init(const size_t key_size,
unsigned long (*hash)(const void *const),
@@ -209,7 +210,7 @@ static int unordered_set_is_equal(unordered_set me,
/*
* Creates an element to add.
*/
static struct node *const unordered_set_create_element(unordered_set me,
static struct node *unordered_set_create_element(unordered_set me,
const unsigned long hash,
const void *const key)
{
@@ -230,7 +231,11 @@ static struct node *const unordered_set_create_element(unordered_set me,
/**
* Adds an element to the unordered set if the unordered set does not already
* contain it.
* contain it. The pointer to the key being passed in should point to the key
* type which this unordered set holds. For example, if this unordered set holds
* key integers, the key pointer should be a pointer to an integer. Since the
* key is being copied, the pointer only has to be valid when this function is
* called.
*
* @param me the unordered set to add to
* @param key the element to add
@@ -275,7 +280,11 @@ int unordered_set_put(unordered_set me, void *const key)
}
/**
* Determines if the unordered set contains the specified element.
* Determines if the unordered set contains the specified element. The pointer
* to the key being passed in should point to the key type which this unordered
* set holds. For example, if this unordered set holds key integers, the key
* pointer should be a pointer to an integer. Since the key is being copied,
* the pointer only has to be valid when this function is called.
*
* @param me the unordered set to check for the element
* @param key the element to check
@@ -297,7 +306,11 @@ int unordered_set_contains(unordered_set me, void *const key)
}
/**
* Removes the key from the unordered set if it contains it.
* Removes the key from the unordered set if it contains it. The pointer to the
* key being passed in should point to the key type which this unordered set
* holds. For example, if this unordered set holds key integers, the key pointer
* should be a pointer to an integer. Since the key is being copied, the pointer
* only has to be valid when this function is called.
*
* @param me the unordered set to remove an key from
* @param key the key to remove

66
src/vector.c
View File

@@ -39,7 +39,9 @@ struct internal_vector {
*
* @param data_size the size of each element in the vector; must be positive
*
* @return the newly-initialized vector, or NULL if memory allocation error
* @return the newly-initialized vector, or NULL if it was not successfully
* initialized due to either invalid input arguments or memory
* allocation error
*/
vector vector_init(const size_t data_size)
{
@@ -145,7 +147,10 @@ int vector_trim(vector me)
}
/**
* Copies the vector to an array.
* Copies the vector to an array. Since it is a copy, the array may be modified
* without causing side effects to the vector data structure. Memory is not
* allocated, thus the array being used for the copy must be allocated before
* this function is called.
*
* @param arr the initialized array to copy the vector to
* @param me the vector to copy to the array
@@ -156,10 +161,11 @@ void vector_copy_to_array(void *const arr, vector me)
}
/**
* Gets the storage element of the vector which is contiguous in memory. If the
* data is modified, the data in the vector is modified. Also, any vector
* operation may invalidate this data pointer. The vector owns the data pointer,
* thus it must not be freed.
* Gets the storage element of the vector which is contiguous in memory. This
* pointer is not a copy, thus any modification to the data will cause the
* vector structure data to be modified. Operations using the vector functions
* may invalidate this pointer. The vector owns this memory, thus it should not
* be freed.
*
* @param me the vector to get the storage element from
*
@@ -171,7 +177,11 @@ void *vector_get_data(vector me)
}
/**
* Adds an element to the start of the vector.
* Adds an element to the start of the vector. The pointer to the data being
* passed in should point to the data type which this vector holds. For example,
* if this vector holds integers, the data pointer should be a pointer to an
* integer. Since the data is being copied, the pointer only has to be valid
* when this function is called.
*
* @param me the vector to add to
* @param data the data to add to the vector
@@ -185,7 +195,11 @@ int vector_add_first(vector me, void *const data)
}
/**
* Adds an element to the location specified.
* Adds an element to the location specified. The pointer to the data being
* passed in should point to the data type which this vector holds. For example,
* if this vector holds integers, the data pointer should be a pointer to an
* integer. Since the data is being copied, the pointer only has to be valid
* when this function is called.
*
* @param me the vector to add to
* @param index the location in the vector to add the data to
@@ -294,7 +308,11 @@ int vector_remove_last(vector me)
}
/**
* Sets the data for the first element in the vector.
* Sets the data for the first element in the vector. The pointer to the data
* being passed in should point to the data type which this vector holds. For
* example, if this vector holds integers, the data pointer should be a pointer
* to an integer. Since the data is being copied, the pointer only has to be
* valid when this function is called.
*
* @param me the vector to set data for
* @param data the data to set at the start of the vector
@@ -308,7 +326,11 @@ int vector_set_first(vector me, void *const data)
}
/**
* Sets the data for a specified element in the vector.
* Sets the data for a specified element in the vector. The pointer to the data
* being passed in should point to the data type which this vector holds. For
* example, if this vector holds integers, the data pointer should be a pointer
* to an integer. Since the data is being copied, the pointer only has to be
* valid when this function is called.
*
* @param me the vector to set data for
* @param index the location to set data at in the vector
@@ -328,7 +350,11 @@ int vector_set_at(vector me, const int index, void *const data)
}
/**
* Sets the data for the last element in the vector.
* Sets the data for the last element in the vector. The pointer to the data
* being passed in should point to the data type which this vector holds. For
* example, if this vector holds integers, the data pointer should be a pointer
* to an integer. Since the data is being copied, the pointer only has to be
* valid when this function is called.
*
* @param me the vector to set data for
* @param data the data to set at the end of the vector
@@ -342,7 +368,11 @@ int vector_set_last(vector me, void *const data)
}
/**
* Copies the first element of the vector to data.
* Copies the first element of the vector to data. The pointer to the data being
* obtained should point to the data type which this vector holds. For example,
* if this vector holds integers, the data pointer should be a pointer to an
* integer. Since this data is being copied from the array to the data pointer,
* the pointer only has to be valid when this function is called.
*
* @param data the data to copy to
* @param me the vector to copy from
@@ -356,7 +386,11 @@ int vector_get_first(void *const data, vector me)
}
/**
* Copies the element at index of the vector to data.
* Copies the element at index of the vector to data. The pointer to the data
* being obtained should point to the data type which this vector holds. For
* example, if this vector holds integers, the data pointer should be a pointer
* to an integer. Since this data is being copied from the array to the data
* pointer, the pointer only has to be valid when this function is called.
*
* @param data the data to copy to
* @param me the vector to copy from
@@ -376,7 +410,11 @@ int vector_get_at(void *const data, vector me, const int index)
}
/**
* Copies the last element of the vector to data.
* Copies the last element of the vector to data. The pointer to the data being
* obtained should point to the data type which this vector holds. For example,
* if this vector holds integers, the data pointer should be a pointer to an
* integer. Since this data is being copied from the array to the data pointer,
* the pointer only has to be valid when this function is called.
*
* @param data the data to copy to
* @param me the vector to copy from