list.h

Go to the documentation of this file.

/*
 * 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.
 */
 
#ifndef UCX_LIST_H
#define UCX_LIST_H
 
#include "common.h"
#include "collection.h"

typedef struct cx_list_class_s cx_list_class;

struct cx_list_s {
    CX_COLLECTION_BASE;
    const cx_list_class *cl;
};

struct cx_list_class_s {
    void (*deallocate)(struct cx_list_s *list);

    void *(*insert_element)(struct cx_list_s *list, size_t index, const void *data);

    size_t (*insert_array)(struct cx_list_s *list, size_t index, const void *data, size_t n);

    size_t (*insert_sorted)(struct cx_list_s *list, const void *sorted_data, size_t n);

    size_t (*insert_unique)(struct cx_list_s *list, const void *sorted_data, size_t n);

    int (*insert_iter)(struct cx_iterator_s *iter, const void *elem, int prepend);

    size_t (*remove)(struct cx_list_s *list, size_t index, size_t num, void *targetbuf);

    void (*clear)(struct cx_list_s *list);

    int (*swap)(struct cx_list_s *list, size_t i, size_t j);

    void *(*at)(const struct cx_list_s *list, size_t index);

    size_t (*find_remove)(struct cx_list_s *list, const void *elem, bool remove);

    void (*sort)(struct cx_list_s *list);

    int (*compare)(const struct cx_list_s *list, const struct cx_list_s *other);

    void (*reverse)(struct cx_list_s *list);

    int (*change_capacity)(struct cx_list_s *list, size_t new_capacity);

    struct cx_iterator_s (*iterator)(const struct cx_list_s *list, size_t index, bool backward);
};

typedef struct cx_list_s CxList;

CX_EXPORT extern CxList *const cxEmptyList;

CX_EXTERN CX_NONNULL_ARG(1)
size_t cx_list_default_insert_array(struct cx_list_s *list,
        size_t index, const void *data, size_t n);

CX_EXTERN CX_NONNULL
size_t cx_list_default_insert_sorted(struct cx_list_s *list,
        const void *sorted_data, size_t n);

CX_EXTERN CX_NONNULL
size_t cx_list_default_insert_unique(struct cx_list_s *list,
        const void *sorted_data, size_t n);

CX_EXTERN CX_NONNULL
void cx_list_default_sort(struct cx_list_s *list);

CX_EXTERN CX_NONNULL
int cx_list_default_swap(struct cx_list_s *list, size_t i, size_t j);

CX_EXTERN CX_NONNULL_ARG(1, 2, 3)
void cx_list_init(struct cx_list_s *list,
    struct cx_list_class_s *cl, const struct cx_allocator_s *allocator,
    size_t elem_size);

CX_EXTERN CX_NONNULL
int cx_list_compare_wrapper(
    const void *left, const void *right, void *list);

CX_EXTERN CX_NONNULL
size_t cxListSize(const CxList *list);

CX_EXTERN CX_NONNULL
int cxListAdd(CxList *list, const void *elem);

CX_EXTERN CX_NONNULL
size_t cxListAddArray(CxList *list, const void *array, size_t n);

CX_EXTERN CX_NONNULL
int cxListInsert(CxList *list, size_t index, const void *elem);

CX_EXTERN CX_NONNULL CX_NODISCARD
void *cxListEmplaceAt(CxList *list, size_t index);

CX_EXTERN CX_NONNULL CX_NODISCARD
void *cxListEmplace(CxList *list);

CX_EXTERN CX_NONNULL CX_NODISCARD
CxIterator cxListEmplaceArrayAt(CxList *list, size_t index, size_t n);

CX_EXTERN CX_NONNULL CX_NODISCARD
CxIterator cxListEmplaceArray(CxList *list, size_t n);

CX_EXTERN CX_NONNULL
int cxListInsertSorted(CxList *list, const void *elem);

CX_EXTERN CX_NONNULL
int cxListInsertUnique(CxList *list, const void *elem);

CX_EXTERN CX_NONNULL
size_t cxListInsertArray(CxList *list, size_t index, const void *array, size_t n);

CX_EXTERN CX_NONNULL
size_t cxListInsertSortedArray(CxList *list, const void *array, size_t n);

CX_EXTERN CX_NONNULL
size_t cxListInsertUniqueArray(CxList *list, const void *array, size_t n);

CX_EXTERN CX_NONNULL
int cxListInsertAfter(CxIterator *iter, const void *elem);

CX_EXTERN CX_NONNULL
int cxListInsertBefore(CxIterator *iter, const void *elem);

CX_EXTERN CX_NONNULL
int cxListRemove(CxList *list, size_t index);

CX_EXTERN CX_NONNULL CX_ACCESS_W(3)
int cxListRemoveAndGet(CxList *list, size_t index, void *targetbuf);

CX_EXTERN CX_NONNULL CX_ACCESS_W(2)
int cxListRemoveAndGetFirst(CxList *list, void *targetbuf);

#define cxListPopFront(list, targetbuf) cxListRemoveAndGetFirst((list), (targetbuf))
 

CX_EXTERN CX_NONNULL CX_ACCESS_W(2)
int cxListRemoveAndGetLast(CxList *list, void *targetbuf);

#define cxListPop(list, targetbuf) cxListRemoveAndGetLast((list), (targetbuf))

CX_EXTERN CX_NONNULL
size_t cxListRemoveArray(CxList *list, size_t index, size_t num);

CX_EXTERN CX_NONNULL CX_ACCESS_W(4)
size_t cxListRemoveArrayAndGet(CxList *list, size_t index, size_t num, void *targetbuf);

CX_EXTERN CX_NONNULL
void cxListClear(CxList *list);

CX_EXTERN CX_NONNULL
int cxListSwap(CxList *list, size_t i, size_t j);

CX_EXTERN CX_NONNULL
void *cxListAt(const CxList *list, size_t index);

CX_EXTERN CX_NONNULL
void *cxListFirst(const CxList *list);

CX_EXTERN CX_NONNULL
void *cxListLast(const CxList *list);

CX_EXTERN CX_NONNULL
int cxListSet(CxList *list, size_t index, const void *elem);

CX_EXTERN CX_NODISCARD
CxIterator cxListIteratorAt(const CxList *list, size_t index);

CX_EXTERN CX_NODISCARD
CxIterator cxListBackwardsIteratorAt(const CxList *list, size_t index);

CX_EXTERN CX_NODISCARD
CxIterator cxListIterator(const CxList *list);

CX_EXTERN CX_NODISCARD
CxIterator cxListBackwardsIterator(const CxList *list);

CX_EXTERN CX_NONNULL CX_NODISCARD
size_t cxListFind(const CxList *list, const void *elem);

CX_EXTERN CX_NONNULL CX_NODISCARD
bool cxListContains(const CxList* list, const void* elem);

CX_EXTERN CX_NONNULL CX_NODISCARD
bool cxListIndexValid(const CxList *list, size_t index);

CX_EXTERN CX_NONNULL
size_t cxListFindRemove(CxList *list, const void *elem);

CX_EXTERN CX_NONNULL
void cxListSort(CxList *list);

CX_EXTERN CX_NONNULL
void cxListReverse(CxList *list);

CX_EXTERN CX_NONNULL CX_NODISCARD
int cxListCompare(const CxList *list, const CxList *other);

CX_EXTERN
void cxListFree(CxList *list);
 

CX_EXTERN CX_NONNULL_ARG(1, 2, 3)
int cxListClone(CxList *dst, const CxList *src,
        cx_clone_func clone_func, const CxAllocator *clone_allocator, void *data);

CX_EXTERN CX_NONNULL_ARG(1, 2, 3, 4)
int cxListDifference(CxList *dst,
        const CxList *minuend, const CxList *subtrahend,
        cx_clone_func clone_func, const CxAllocator *clone_allocator, void *data);

CX_EXTERN CX_NONNULL_ARG(1, 2, 3, 4)
int cxListIntersection(CxList *dst, const CxList *src, const CxList *other,
        cx_clone_func clone_func, const CxAllocator *clone_allocator, void *data);

CX_EXTERN CX_NONNULL_ARG(1, 2, 3, 4)
int cxListUnion(CxList *dst, const CxList *src, const CxList *other,
        cx_clone_func clone_func, const CxAllocator *clone_allocator, void *data);

CX_EXTERN CX_NONNULL
int cxListCloneShallow(CxList *dst, const CxList *src);

CX_EXTERN CX_NONNULL
int cxListDifferenceShallow(CxList *dst,
        const CxList *minuend, const CxList *subtrahend);

CX_EXTERN CX_NONNULL
int cxListIntersectionShallow(CxList *dst, const CxList *src, const CxList *other);

CX_EXTERN CX_NONNULL
int cxListUnionShallow(CxList *dst, const CxList *src, const CxList *other);

CX_EXTERN CX_NONNULL
int cxListReserve(CxList *list, size_t capacity);

CX_EXTERN CX_NONNULL
int cxListShrink(CxList *list);
 
#endif // UCX_LIST_H