12 days ago
json: enable multiple subsequent fills - relates to #431
/* * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. * * Copyright 2021 Mike Becker, Olaf Wintermann All rights reserved. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions are met: * * 1. Redistributions of source code must retain the above copyright * notice, this list of conditions and the following disclaimer. * * 2. Redistributions in binary form must reproduce the above copyright * notice, this list of conditions and the following disclaimer in the * documentation and/or other materials provided with the distribution. * * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE * POSSIBILITY OF SUCH DAMAGE. */ /** * \file list.h * \brief Interface for list implementations. * \author Mike Becker * \author Olaf Wintermann * \copyright 2-Clause BSD License */ #ifndef UCX_LIST_H #define UCX_LIST_H #include "common.h" #include "collection.h" #ifdef __cplusplus extern "C" { #endif /** * List class type. */ typedef struct cx_list_class_s cx_list_class; /** * Structure for holding the base data of a list. */ struct cx_list_s { /** * Common members for collections. */ CX_COLLECTION_BASE; /** * The list class definition. */ const cx_list_class *cl; /** * The actual implementation in case the list class is delegating. */ const cx_list_class *climpl; }; /** * The class definition for arbitrary lists. */ struct cx_list_class_s { /** * Destructor function. * * Implementations SHALL invoke the content destructor functions if provided * and SHALL deallocate the entire list memory. */ cx_attr_nonnull void (*deallocate)(struct cx_list_s *list); /** * Member function for inserting a single element. * Implementors SHOULD see to performant implementations for corner cases. */ cx_attr_nonnull int (*insert_element)( struct cx_list_s *list, size_t index, const void *data ); /** * Member function for inserting multiple elements. * Implementors SHOULD see to performant implementations for corner cases. * @see cx_list_default_insert_array() */ cx_attr_nonnull size_t (*insert_array)( struct cx_list_s *list, size_t index, const void *data, size_t n ); /** * Member function for inserting sorted elements into a sorted list. * * @see cx_list_default_insert_sorted() */ cx_attr_nonnull size_t (*insert_sorted)( struct cx_list_s *list, const void *sorted_data, size_t n ); /** * Member function for inserting an element relative to an iterator position. */ cx_attr_nonnull int (*insert_iter)( struct cx_iterator_s *iter, const void *elem, int prepend ); /** * Member function for removing elements. * * Implementations SHALL check if \p targetbuf is set and copy the elements * to the buffer without invoking any destructor. * When \p targetbuf is not set, the destructors SHALL be invoked. * * The function SHALL return the actual number of elements removed, which * might be lower than \p num when going out of bounds. */ cx_attr_nonnull_arg(1) cx_attr_access_w(4) size_t (*remove)( struct cx_list_s *list, size_t index, size_t num, void *targetbuf ); /** * Member function for removing all elements. */ cx_attr_nonnull void (*clear)(struct cx_list_s *list); /** * Member function for swapping two elements. * @see cx_list_default_swap() */ cx_attr_nonnull int (*swap)( struct cx_list_s *list, size_t i, size_t j ); /** * Member function for element lookup. */ cx_attr_nonnull cx_attr_nodiscard void *(*at)( const struct cx_list_s *list, size_t index ); /** * Member function for finding and optionally removing an element. */ cx_attr_nonnull cx_attr_nodiscard ssize_t (*find_remove)( struct cx_list_s *list, const void *elem, bool remove ); /** * Member function for sorting the list in-place. * @see cx_list_default_sort() */ cx_attr_nonnull void (*sort)(struct cx_list_s *list); /** * Optional member function for comparing this list * to another list of the same type. * If set to \c NULL, comparison won't be optimized. */ cx_attr_nonnull int (*compare)( const struct cx_list_s *list, const struct cx_list_s *other ); /** * Member function for reversing the order of the items. */ cx_attr_nonnull void (*reverse)(struct cx_list_s *list); /** * Member function for returning an iterator pointing to the specified index. */ cx_attr_nonnull struct cx_iterator_s (*iterator)( const struct cx_list_s *list, size_t index, bool backward ); }; /** * Default implementation of an array insert. * * This function uses the element insert function for each element of the array. * * Use this in your own list class if you do not want to implement an optimized * version for your list. * * @param list the list * @param index the index where to insert the data * @param data a pointer to the array of data to insert * @param n the number of elements to insert * @return the number of elements actually inserted */ cx_attr_nonnull size_t cx_list_default_insert_array( struct cx_list_s *list, size_t index, const void *data, size_t n ); /** * Default implementation of a sorted insert. * * This function uses the array insert function to insert consecutive groups * of sorted data. * * The source data \em must already be sorted wrt. the list's compare function. * * Use this in your own list class if you do not want to implement an optimized * version for your list. * * @param list the list * @param sorted_data a pointer to the array of pre-sorted data to insert * @param n the number of elements to insert * @return the number of elements actually inserted */ cx_attr_nonnull size_t cx_list_default_insert_sorted( struct cx_list_s *list, const void *sorted_data, size_t n ); /** * Default unoptimized sort implementation. * * This function will copy all data to an array, sort the array with standard * qsort, and then copy the data back to the list memory. * * Use this in your own list class if you do not want to implement an optimized * version for your list. * * @param list the list that shall be sorted */ cx_attr_nonnull void cx_list_default_sort(struct cx_list_s *list); /** * Default unoptimized swap implementation. * * Use this in your own list class if you do not want to implement an optimized * version for your list. * * @param list the list in which to swap * @param i index of one element * @param j index of the other element * @return zero on success, non-zero when indices are out of bounds or memory * allocation for the temporary buffer fails */ cx_attr_nonnull int cx_list_default_swap(struct cx_list_s *list, size_t i, size_t j); /** * Common type for all list implementations. */ typedef struct cx_list_s CxList; /** * Advises the list to store copies of the objects (default mode of operation). * * Retrieving objects from this list will yield pointers to the copies stored * within this list. * * @param list the list * @see cxListStorePointers() */ cx_attr_nonnull void cxListStoreObjects(CxList *list); /** * Advises the list to only store pointers to the objects. * * Retrieving objects from this list will yield the original pointers stored. * * @note This function forcibly sets the element size to the size of a pointer. * Invoking this function on a non-empty list that already stores copies of * objects is undefined. * * @param list the list * @see cxListStoreObjects() */ cx_attr_nonnull void cxListStorePointers(CxList *list); /** * Returns true, if this list is storing pointers instead of the actual data. * * @param list * @return true, if this list is storing pointers * @see cxListStorePointers() */ cx_attr_nonnull static inline bool cxListIsStoringPointers(const CxList *list) { return list->collection.store_pointer; } /** * Returns the number of elements currently stored in the list. * * @param list the list * @return the number of currently stored elements */ cx_attr_nonnull static inline size_t cxListSize(const CxList *list) { return list->collection.size; } /** * Adds an item to the end of the list. * * @param list the list * @param elem a pointer to the element to add * @return zero on success, non-zero on memory allocation failure * @see cxListAddArray() */ cx_attr_nonnull static inline int cxListAdd( CxList *list, const void *elem ) { return list->cl->insert_element(list, list->collection.size, elem); } /** * Adds multiple items to the end of the list. * * This method is more efficient than invoking cxListAdd() multiple times. * * If there is not enough memory to add all elements, the returned value is * less than \p n. * * If this list is storing pointers instead of objects \p array is expected to * be an array of pointers. * * @param list the list * @param array a pointer to the elements to add * @param n the number of elements to add * @return the number of added elements */ cx_attr_nonnull static inline size_t cxListAddArray( CxList *list, const void *array, size_t n ) { return list->cl->insert_array(list, list->collection.size, array, n); } /** * Inserts an item at the specified index. * * If \p index equals the list \c size, this is effectively cxListAdd(). * * @param list the list * @param index the index the element shall have * @param elem a pointer to the element to add * @return zero on success, non-zero on memory allocation failure * or when the index is out of bounds * @see cxListInsertAfter() * @see cxListInsertBefore() */ cx_attr_nonnull static inline int cxListInsert( CxList *list, size_t index, const void *elem ) { return list->cl->insert_element(list, index, elem); } /** * Inserts an item into a sorted list. * * @param list the list * @param elem a pointer to the element to add * @return zero on success, non-zero on memory allocation failure */ cx_attr_nonnull static inline int cxListInsertSorted( CxList *list, const void *elem ) { const void *data = list->collection.store_pointer ? &elem : elem; return list->cl->insert_sorted(list, data, 1) == 0; } /** * Inserts multiple items to the list at the specified index. * If \p index equals the list size, this is effectively cxListAddArray(). * * This method is usually more efficient than invoking cxListInsert() * multiple times. * * If there is not enough memory to add all elements, the returned value is * less than \p n. * * If this list is storing pointers instead of objects \p array is expected to * be an array of pointers. * * @param list the list * @param index the index where to add the elements * @param array a pointer to the elements to add * @param n the number of elements to add * @return the number of added elements */ cx_attr_nonnull static inline size_t cxListInsertArray( CxList *list, size_t index, const void *array, size_t n ) { return list->cl->insert_array(list, index, array, n); } /** * Inserts a sorted array into a sorted list. * * This method is usually more efficient than inserting each element separately, * because consecutive chunks of sorted data are inserted in one pass. * * If there is not enough memory to add all elements, the returned value is * less than \p n. * * If this list is storing pointers instead of objects \p array is expected to * be an array of pointers. * * @param list the list * @param array a pointer to the elements to add * @param n the number of elements to add * @return the number of added elements */ cx_attr_nonnull static inline size_t cxListInsertSortedArray( CxList *list, const void *array, size_t n ) { return list->cl->insert_sorted(list, array, n); } /** * Inserts an element after the current location of the specified iterator. * * The used iterator remains operational, but all other active iterators should * be considered invalidated. * * If \p iter is not a list iterator, the behavior is undefined. * If \p iter is a past-the-end iterator, the new element gets appended to the list. * * @param iter an iterator * @param elem the element to insert * @return zero on success, non-zero on memory allocation failure * @see cxListInsert() * @see cxListInsertBefore() */ cx_attr_nonnull static inline int cxListInsertAfter( CxIterator *iter, const void *elem ) { return ((struct cx_list_s *) iter->src_handle.m)->cl->insert_iter(iter, elem, 0); } /** * Inserts an element before the current location of the specified iterator. * * The used iterator remains operational, but all other active iterators should * be considered invalidated. * * If \p iter is not a list iterator, the behavior is undefined. * If \p iter is a past-the-end iterator, the new element gets appended to the list. * * @param iter an iterator * @param elem the element to insert * @return zero on success, non-zero on memory allocation failure * @see cxListInsert() * @see cxListInsertAfter() */ cx_attr_nonnull static inline int cxListInsertBefore( CxIterator *iter, const void *elem ) { return ((struct cx_list_s *) iter->src_handle.m)->cl->insert_iter(iter, elem, 1); } /** * Removes the element at the specified index. * * If an element destructor function is specified, it is called before * removing the element. * * @param list the list * @param index the index of the element * @return zero on success, non-zero if the index is out of bounds */ cx_attr_nonnull static inline int cxListRemove( CxList *list, size_t index ) { return list->cl->remove(list, index, 1, NULL) == 0; } /** * Removes and returns the element at the specified index. * * No destructor is called and instead the element is copied to the * \p targetbuf which MUST be large enough to hold the removed element. * * @param list the list * @param index the index of the element * @param targetbuf a buffer where to copy the element * @return zero on success, non-zero if the index is out of bounds */ cx_attr_nonnull cx_attr_access_w(3) static inline int cxListRemoveAndGet( CxList *list, size_t index, void *targetbuf ) { return list->cl->remove(list, index, 1, targetbuf) == 0; } /** * Removes multiple element starting at the specified index. * * If an element destructor function is specified, it is called for each * element. It is guaranteed that the destructor is called before removing * the element, however, due to possible optimizations it is neither guaranteed * that the destructors are invoked for all elements before starting to remove * them, nor that the element is removed immediately after the destructor call * before proceeding to the next element. * * @param list the list * @param index the index of the element * @param num the number of elements to remove * @return the actual number of removed elements */ cx_attr_nonnull static inline size_t cxListRemoveArray( CxList *list, size_t index, size_t num ) { return list->cl->remove(list, index, num, NULL); } /** * Removes and returns multiple element starting at the specified index. * * No destructor is called and instead the elements are copied to the * \p targetbuf which MUST be large enough to hold all removed elements. * * @param list the list * @param index the index of the element * @param num the number of elements to remove * @param targetbuf a buffer where to copy the elements * @return the actual number of removed elements */ cx_attr_nonnull cx_attr_access_w(4) static inline size_t cxListRemoveArrayAndGet( CxList *list, size_t index, size_t num, void *targetbuf ) { return list->cl->remove(list, index, num, targetbuf); } /** * Removes all elements from this list. * * If an element destructor function is specified, it is called for each * element before removing them. * * @param list the list */ cx_attr_nonnull static inline void cxListClear(CxList *list) { list->cl->clear(list); } /** * Swaps two items in the list. * * Implementations should only allocate temporary memory for the swap, if * it is necessary. * * @param list the list * @param i the index of the first element * @param j the index of the second element * @return zero on success, non-zero if one of the indices is out of bounds */ cx_attr_nonnull static inline int cxListSwap( CxList *list, size_t i, size_t j ) { return list->cl->swap(list, i, j); } /** * Returns a pointer to the element at the specified index. * * @param list the list * @param index the index of the element * @return a pointer to the element or \c NULL if the index is out of bounds */ cx_attr_nonnull static inline void *cxListAt( const CxList *list, size_t index ) { return list->cl->at(list, index); } /** * Returns an iterator pointing to the item at the specified index. * * The returned iterator is position-aware. * * If the index is out of range, a past-the-end iterator will be returned. * * @param list the list * @param index the index where the iterator shall point at * @return a new iterator */ cx_attr_nonnull cx_attr_nodiscard static inline CxIterator cxListIteratorAt( const CxList *list, size_t index ) { return list->cl->iterator(list, index, false); } /** * Returns a backwards iterator pointing to the item at the specified index. * * The returned iterator is position-aware. * * If the index is out of range, a past-the-end iterator will be returned. * * @param list the list * @param index the index where the iterator shall point at * @return a new iterator */ cx_attr_nonnull cx_attr_nodiscard static inline CxIterator cxListBackwardsIteratorAt( const CxList *list, size_t index ) { return list->cl->iterator(list, index, true); } /** * Returns a mutating iterator pointing to the item at the specified index. * * The returned iterator is position-aware. * * If the index is out of range, a past-the-end iterator will be returned. * * @param list the list * @param index the index where the iterator shall point at * @return a new iterator */ cx_attr_nonnull cx_attr_nodiscard CxIterator cxListMutIteratorAt( CxList *list, size_t index ); /** * Returns a mutating backwards iterator pointing to the item at the * specified index. * * The returned iterator is position-aware. * * If the index is out of range, a past-the-end iterator will be returned. * * @param list the list * @param index the index where the iterator shall point at * @return a new iterator */ cx_attr_nonnull cx_attr_nodiscard CxIterator cxListMutBackwardsIteratorAt( CxList *list, size_t index ); /** * Returns an iterator pointing to the first item of the list. * * The returned iterator is position-aware. * * If the list is empty, a past-the-end iterator will be returned. * * @param list the list * @return a new iterator */ cx_attr_nonnull cx_attr_nodiscard static inline CxIterator cxListIterator(const CxList *list) { return list->cl->iterator(list, 0, false); } /** * Returns a mutating iterator pointing to the first item of the list. * * The returned iterator is position-aware. * * If the list is empty, a past-the-end iterator will be returned. * * @param list the list * @return a new iterator */ cx_attr_nonnull cx_attr_nodiscard static inline CxIterator cxListMutIterator(CxList *list) { return cxListMutIteratorAt(list, 0); } /** * Returns a backwards iterator pointing to the last item of the list. * * The returned iterator is position-aware. * * If the list is empty, a past-the-end iterator will be returned. * * @param list the list * @return a new iterator */ cx_attr_nonnull cx_attr_nodiscard static inline CxIterator cxListBackwardsIterator(const CxList *list) { return list->cl->iterator(list, list->collection.size - 1, true); } /** * Returns a mutating backwards iterator pointing to the last item of the list. * * The returned iterator is position-aware. * * If the list is empty, a past-the-end iterator will be returned. * * @param list the list * @return a new iterator */ cx_attr_nonnull cx_attr_nodiscard static inline CxIterator cxListMutBackwardsIterator(CxList *list) { return cxListMutBackwardsIteratorAt(list, list->collection.size - 1); } /** * Returns the index of the first element that equals \p elem. * * Determining equality is performed by the list's comparator function. * * @param list the list * @param elem the element to find * @return the index of the element or a negative * value when the element is not found */ cx_attr_nonnull cx_attr_nodiscard static inline ssize_t cxListFind( const CxList *list, const void *elem ) { return list->cl->find_remove((CxList*)list, elem, false); } /** * Removes and returns the index of the first element that equals \p elem. * * Determining equality is performed by the list's comparator function. * * @param list the list * @param elem the element to find and remove * @return the index of the now removed element or a negative * value when the element is not found or could not be removed */ cx_attr_nonnull static inline ssize_t cxListFindRemove( CxList *list, const void *elem ) { return list->cl->find_remove(list, elem, true); } /** * Sorts the list in-place. * * \remark The underlying sort algorithm is implementation defined. * * @param list the list */ cx_attr_nonnull static inline void cxListSort(CxList *list) { list->cl->sort(list); } /** * Reverses the order of the items. * * @param list the list */ cx_attr_nonnull static inline void cxListReverse(CxList *list) { list->cl->reverse(list); } /** * Compares a list to another list of the same type. * * First, the list sizes are compared. * If they match, the lists are compared element-wise. * * @param list the list * @param other the list to compare to * @return zero, if both lists are equal element wise, * negative if the first list is smaller, positive if the first list is larger */ cx_attr_nonnull cx_attr_nodiscard int cxListCompare( const CxList *list, const CxList *other ); /** * Deallocates the memory of the specified list structure. * * Also calls the content destructor function for each element, if specified. * * @param list the list which shall be freed */ static inline void cxListFree(CxList *list) { if (list == NULL) return; list->cl->deallocate(list); } /** * A shared instance of an empty list. * * Writing to that list is not allowed. */ extern CxList *const cxEmptyList; #ifdef __cplusplus } // extern "C" #endif #endif // UCX_LIST_H