Containers for C Code
ADTs and data structures for C programmers
Status: Inactive
Brought to you by:
ab396356
File | Date | Author | Commit |
---|---|---|---|
ctnr | 2016-11-25 | ab396356 | [r21] improved `dlist_print()` function and added tests |
ctnr_tests | 2020-07-28 | ab396356 | [r22] updated projects to Pelles C 10.00 |
copying.txt | 2016-10-15 | ab396356 | [r1] first commit of work-in-progress |
ctnr_icon.png | 2016-10-15 | ab396356 | [r1] first commit of work-in-progress |
readme.txt | 2016-11-23 | ab396356 | [r12] updated ReadMe to document the `ctnr_count()` v... |
============================= Containers for the C language ============================= 1. Introduction 2. Containers List 3. Basic Usage 4. Iterators 5. Memory Management --------------- 1. Introduction --------------- This software implements various containers for use in C programs. For the most part their interface mimics that of C++ Standard Library containers with a few important differences, covered in section "3. Basic Usage". In the above paragraph the word "software" was used instead of "library" because the code is not a library: it is a 100% macro implementation, in headers. For better or for worse, all code is inlined and having side effects in the passed parameters is highly discouraged. The software can be built with any compiler that is C99 standard compliant and supports the "__typeof__" keyword as an extension. The software was tested to build correctly with the following compilers: * POCC 8.00.170 (Pelles C for Windows) * GCC 5.1.0 (tdm64-1) * GCC 5.3.1 (6.fc23) The software is distributed under the terms of the Creative Commons CC0 1.0 Universal legal code; for more information read the file "copying.txt" or visit the website: https://creativecommons.org/publicdomain/zero/1.0/ ------------------ 2. Containers List ------------------ The container header files are kept in the "ctnr" directory, and are hereby listed: HEADER NAME CONTAINER NAME -------------------------------------- *** ARRAYS *** dynarray.h Dynamic Array string.h Byte String wstring.h Wide String -------------------------------------- *** LISTS *** dlist.h Doubly Linked List -------------------------------------- *** TREES *** -------------------------------------- *** ABSTRACT DATA TYPES *** -------------------------------------- *** HASH TABLES *** -------------------------------------- -------------- 3. Basic Usage -------------- The following examples are for a hypothetical container named "container" which is accessed by including the hypothetical header "ctnr/container.h". Before using the container: (1) include header (2) declare object (3) initialize the object After using the container: (4) deinitialize the object ~~~~ #include "ctnr/container.h" // (1) // ... container(int) ci; // (2) if (container_create(ci)) // (3) { // ... container_destroy(ci); // (4) } ~~~~ Detailed usage instructions are found in the container header files themselves. Each header file lists the available macro functions for the container in question. There are two kinds of macro functions: (1) general (2) container-specific The general macro functions for containers are: RETURN TYPE NAME PARAMETERS (MAY VARY) ------------------------------------------------------------- ContainerType container (ElemType) bool container_create (Container, Capacity) void container_ptrcopy (Container, ElemPtr, Count) void container_destroy (Container) void container_clear (Container) size_t container_size (Container) void container_search (Container, ValidFunc, DynArrayRes) void container_count (Container, ValidFunc, CountRes) void container_counteq (Container, ElemVal, CountRes) bool container_empty (Container) ------------------------------------------------------------- The macros do not enforce the parameter type which is why in the listing above the parameters appear type-less. The parameter types and number may vary between different containers: the specific signatures are documented in each header file. Note that using parameters with side-effects (such as "x++") is highly discouraged because following the macro expansion the parameters may be evaluated multiple times. Finally, some container operations have `assert()` checks for debugging purposes, so remember to define the `NDEBUG` macro for release builds. ------------ 4. Iterators ------------ Some containers may include support for iterators by defining some (or all) of the functions below: RETURN TYPE NAME PARAMETERS (MAY VARY) ------------------------------------------------------------- ElemIterType containeriter (Container) ElemVal containeriter_deref (ElemIter) void containeriter_inc (ElemIter) void containeriter_dec (ElemIter) ElemIter containeriter_begin (Container) ElemIter containeriter_end (Container) void containeriter_rinc (ElemIter) void containeriter_rdec (ElemIter) ElemIter containeriter_rbegin (Container) ElemIter containeriter_rend (Container) ------------------------------------------------------------- -------------------- 4. Memory Management -------------------- By default, all containers use the standard C functions for memory management: * malloc * realloc * free For certain containers, particularly the ones which allocate memory for one element (node) at a time, the default behavior may be overridden. This is done by defining the following macros before including the container's header file: * CONTAINER_MALLOC * CONTAINER_REALLOC * CONTAINER_FREE For example: ~~~~ #include "my_special_stdlib.h" #define SLIST_MALLOC my_special_malloc #define SLIST_REALLOC my_special_realloc #define SLIST_FREE my_special_free #include "ctnr/slist.h" // ... ~~~~ Refer to the container header files to find out which macros need to be redefined to manage memory, or if support for doing so was even added. Note that the user-provided functions for memory management are required to have the same signature and behavior as the standard C functions. For details refer to: http://en.cppreference.com/w/c/memory/malloc http://en.cppreference.com/w/c/memory/realloc http://en.cppreference.com/w/c/memory/free