Read Me

=============================
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