ucx: src/cx/array_list.h@475335643af4

increase version number to 3.1

remove per-file version information
from Doxygen output

     1 /*

     2  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.

     3  *

     4  * Copyright 2021 Mike Becker, Olaf Wintermann All rights reserved.

     5  *

     6  * Redistribution and use in source and binary forms, with or without

     7  * modification, are permitted provided that the following conditions are met:

     8  *

     9  *   1. Redistributions of source code must retain the above copyright

    10  *      notice, this list of conditions and the following disclaimer.

    11  *

    12  *   2. Redistributions in binary form must reproduce the above copyright

    13  *      notice, this list of conditions and the following disclaimer in the

    14  *      documentation and/or other materials provided with the distribution.

    15  *

    16  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"

    17  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE

    18  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE

    19  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE

    20  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR

    21  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF

    22  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS

    23  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN

    24  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)

    25  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE

    26  * POSSIBILITY OF SUCH DAMAGE.

    27  */

    28 /**

    29  * \file array_list.h

    30  * \brief Array list implementation.

    31  * \details Also provides several low-level functions for custom array list implementations.

    32  * \author Mike Becker

    33  * \author Olaf Wintermann

    34  * \copyright 2-Clause BSD License

    35  */

    38 #ifndef UCX_ARRAY_LIST_H

    39 #define UCX_ARRAY_LIST_H

    41 #include "list.h"

    43 #ifdef __cplusplus

    44 extern "C" {

    45 #endif

    47 /**

    48  * Defines a reallocation mechanism for arrays.

    49  */

    50 struct cx_array_reallocator_s {

    51     /**

    52      * Re-allocates space for the given array.

    53      *

    54      * Implementations are not required to free the original array.

    55      * This allows re-allocation of static memory by allocating heap memory

    56      * and copying the array contents. The information in \p data can keep

    57      * track of the state of the memory or other additional allocator info.

    58      *

    59      * @param array the array to reallocate

    60      * @param capacity the new capacity (number of elements)

    61      * @param elem_size the size of each element

    62      * @param alloc a reference to this allocator

    63      * @return a pointer to the reallocated memory or \c NULL on failure

    64      */

    65     void *(*realloc)(

    66             void *array,

    67             size_t capacity,

    68             size_t elem_size,

    69             struct cx_array_reallocator_s *alloc

    70     );

    72     /**

    73      * Custom data pointer.

    74      */

    75     void *ptr1;

    76     /**

    77      * Custom data pointer.

    78      */

    79     void *ptr2;

    80     /**

    81      * Custom data integer.

    82      */

    83     size_t int1;

    84     /**

    85      * Custom data integer.

    86      */

    87     size_t int2;

    88 };

    90 /**

    91  * Return codes for cx_array_copy().

    92  */

    93 enum cx_array_copy_result {

    94     CX_ARRAY_COPY_SUCCESS,

    95     CX_ARRAY_COPY_REALLOC_NOT_SUPPORTED,

    96     CX_ARRAY_COPY_REALLOC_FAILED,

    97 };

    99 /**

   100  * Copies elements from one array to another.

   101  *

   102  * The elements are copied to the \p target array at the specified \p index,

   103  * overwriting possible elements. The \p index does not need to be in range of

   104  * the current array \p size. If the new index plus the number of elements added

   105  * would extend the array's size, and \p capacity is not \c NULL, the remaining

   106  * capacity is used.

   107  *

   108  * If the capacity is insufficient to hold the new data, a reallocation

   109  * attempt is made, unless the allocator is set to \c NULL, in which case

   110  * this function ultimately returns a failure.

   111  *

   112  * @param target the target array

   113  * @param size a pointer to the size of the target array

   114  * @param capacity a pointer to the target array's capacity -

   115  * \c NULL if only the size shall be used to bound the array

   116  * @param index the index where the copied elements shall be placed

   117  * @param src the source array

   118  * @param elem_size the size of one element

   119  * @param elem_count the number of elements to copy

   120  * @param reallocator the array re-allocator to use, or \c NULL

   121  * if re-allocation shall not happen

   122  * @return zero on success, non-zero error code on failure

   123  */

   124 enum cx_array_copy_result cx_array_copy(

   125         void **target,

   126         size_t *size,

   127         size_t *capacity,

   128         size_t index,

   129         void const *src,

   130         size_t elem_size,

   131         size_t elem_count,

   132         struct cx_array_reallocator_s *reallocator

   133 ) __attribute__((__nonnull__(1, 2, 5)));

   136 /**

   137  * Swaps two array elements.

   138  *

   139  * @param arr the array

   140  * @param elem_size the element size

   141  * @param idx1 index of first element

   142  * @param idx2 index of second element

   143  */

   144 void cx_array_swap(

   145         void *arr,

   146         size_t elem_size,

   147         size_t idx1,

   148         size_t idx2

   149 ) __attribute__((__nonnull__));

   151 /**

   152  * Allocates an array list for storing elements with \p item_size bytes each.

   153  *

   154  * If \p item_size is CX_STORE_POINTERS, the created list will be created as if

   155  * cxListStorePointers() was called immediately after creation.

   156  *

   157  * @param allocator the allocator for allocating the list memory

   158  * (if \c NULL the cxDefaultAllocator will be used)

   159  * @param comparator the comparator for the elements

   160  * (if \c NULL sort and find functions will not work)

   161  * @param item_size the size of each element in bytes

   162  * @param initial_capacity the initial number of elements the array can store

   163  * @return the created list

   164  */

   165 CxList *cxArrayListCreate(

   166         CxAllocator const *allocator,

   167         cx_compare_func comparator,

   168         size_t item_size,

   169         size_t initial_capacity

   170 );

   172 /**

   173  * Allocates an array list for storing elements with \p item_size bytes each.

   174  *

   175  * The list will use the cxDefaultAllocator and \em NO compare function.

   176  * If you want to call functions that need a compare function, you have to

   177  * set it immediately after creation or use cxArrayListCreate().

   178  *

   179  * If \p item_size is CX_STORE_POINTERS, the created list will be created as if

   180  * cxListStorePointers() was called immediately after creation.

   181  *

   182  * @param item_size the size of each element in bytes

   183  * @param initial_capacity the initial number of elements the array can store

   184  * @return the created list

   185  */

   186 #define cxArrayListCreateSimple(item_size, initial_capacity) \

   187     cxArrayListCreate(NULL, NULL, item_size, initial_capacity)

   189 #ifdef __cplusplus

   190 } // extern "C"

   191 #endif

   193 #endif // UCX_ARRAY_LIST_H

Mercurial > hg > ucx / file revision