libstring Documentation

                 _ _ _         _        _             
                | (_) |       | |      (_)            
                | |_| |__  ___| |_ _ __ _ _ __   __ _ 
                | | | '_ \/ __| __| '__| | '_ \ / _` |
                | | | |_) \__ \ |_| |  | | | | | (_| |
                |_|_|_.__/|___/\__|_|  |_|_| |_|\__, |
                                                 __/ |
                           by ohnx              |___/ 

            a simple flexible string manipulation library

ABOUT
    libstring is a simple flexible string manipulation library,
    written in C89. All library functions are able to take both
    C-style char arrays and libstring-style strings as input
    (output from is always libstring-style strings).

    libstring keeps track of memory when appending strings -
    so you don't have to! The only time when you need to manual
    memory manage is when you're done with a string.

GOALS
    libstring tries to provide a simpler way to deal with strings
    in C, so that a programmer can focus on other aspects of a
    project. It aims to be lightweight (it only has ~5 real
    functions) yet powerful. 

LIBSTRING-STYLE STRINGS
    libstring-style strings can be treated as normal C-style
    strings. (ie, all C str* functions are compatible with
    libstring-style strings, provided they do not increase the
    length of the string)

    How does this work? Well, libstring-style strings are actually
    char arrays. However, they have an extra header in front.
    When you call a libstring function, it returns only a pointer
    to the char array afterwards - not the header. This means that
    you can call functions that expect a char array by passing
    them any libstring-returned string.

    If you are concerned about reads before the start of a string,
    string_mknew() will always assume the string passed in to it
    is a non library-compatible string, and return a pointer to a
    newly-allocated library-comptabile string.

    Internally, these strings are represented by a struct of type
    `string_real`. See the documentation generated by doxygen for
    more information on how libstring works behind the scenes.

BUILDING
    Run `make` on systems with make and gcc. This will generate a
    file `libstring.a`. To test libstring, you can also run
    `make test` to compile and run the tests.

DOCUMENTATION
    Run `make docs` on systems with make and doxygen. This will
    generate the HTML and LaTeX documentation in the folder `docs/`

EXAMPLES
    See the link: https://github.com/ohnx/libstring/wiki/EXAMPLES

LICENSE
    MIT-licensed, see the LICENSE file.

A NOTE ON PRINTF
    libstring's printf implementation relies on va_copy, which
    is not part of c89. Instead, it is available as an extension.
    To compile libstring with printf support, run `make printf`.
    Keep in mind that the printf code compiles as c99.