ucx: src/cx/array_list.h@2e93521145ac

     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  * \version 3.0

    35  * \copyright 2-Clause BSD License

    36  */

    39 #ifndef UCX_ARRAY_LIST_H

    40 #define UCX_ARRAY_LIST_H

    42 #include "cx/list.h"

    44 #ifdef __cplusplus

    45 extern "C" {

    46 #endif

    48 /**

    49  * Defines a reallocation mechanism for arrays.

    50  */

    51 struct cx_array_reallocator_s {

    52     /**

    53      * Re-allocates space for the given array.

    54      *

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

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

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

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

    59      *

    60      * @param array the array to reallocate

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

    62      * @param elem_size the size of each element

    63      * @param data additional data

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

    65      */

    66     void *(*realloc)(

    67             void *array,

    68             size_t capacity,

    69             size_t elem_size,

    70             void *data

    71     );

    73     /**

    74      * Additional data.

    75      */

    76     void *data;

    77 };

    79 /**

    80  * Copies elements from one array to another.

    81  *

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

    83  * overwriting possible elements. The index must be in range of the current

    84  * array \p size. If the number of elements added would extend the array's size,

    85  * and \p capacity is not \c NULL, the remaining capacity is used.

    86  *

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

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

    89  * this function ultimately returns a failure.

    90  *

    91  * @param target the target array

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

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

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

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

    96  * @param src the source array

    97  * @param elem_size the size of one element

    98  * @param elem_count the number of elements to copy

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

   100  * if re-allocation shall not happen

   101  * @return zero on success, non-zero on failure

   102  */

   103 int cx_array_copy(

   104         void **target,

   105         size_t *size,

   106         size_t *capacity,

   107         size_t index,

   108         void const *src,

   109         size_t elem_size,

   110         size_t elem_count,

   111         struct cx_array_reallocator_s const *reallocator

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

   114 /**

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

   116  *

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

   118  * @param comparator the comparator for the elements

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

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

   121  * @return the created list

   122  */

   123 CxList *cxArrayListCreate(

   124         CxAllocator const *allocator,

   125         CxListComparator comparator,

   126         size_t item_size,

   127         size_t initial_capacity

   128 ) __attribute__((__nonnull__));

   131 #ifdef __cplusplus

   132 } /* extern "C" */

   133 #endif

   135 #endif /* UCX_ARRAY_LIST_H */

Mercurial > hg > ucx / file revision