This is the README for "libjvs".

Copyright: (c) 2013-2023 Jacco van Schaik (jacco@jaccovanschaik.net)

Introduction
------------

Libjvs is a library of utilities in the C programming language. It is
distributed under the MIT license.

Instructions for use is (or should be) contained in the various .h
files. An overview of which source file contains what is provided below.

There are a few "ground rules" regarding use of the various structs and
functions contained herein:

* (Almost) all functions use a lower-case prefix to show which module
  they come from, followed by the rest of the name in camel-case
  (e.g. bufCreate() in buffer.c, hashAdd() in hash.c). Static functions
  (i.e. internal to the module) have the same prefix, but the rest of
  the name is underscore-separated lower case.
* There are a few functions that are meant to be called through a macro
  instead of directly by the user. These have a leading underscore.
* Abstract types (structs and enums) are typedef'ed so they can be
  referenced just by their name.
* If the definition of a struct is given in the .h file, it can be
  automatically allocated on the stack, *provided* that it is zeroed
  before use. Also be sure to ..Clear() the struct before the end of the
  scope, or you might end up with a memory leak.
* Many modules contain test code. When compiled with a macro TEST
  defined they include a main() function that calls a number of (ideally
  all) functions in the module with test data and checks the result. Use
  "make test" to run all the available tests.
* I like variable argument lists. In some cases I use them to implement
  a prinf-like interface, in which case I try to use GCC's __attribute__
  syntax to check the format string against the arguments. In other
  cases I use them to be able to pass in an arbitrary number of
  arguments, in which case the end is usually marked using the END macro
  (defined in defs.h).
* Some "standard" functions:
  xCreate()     Create a new, initialized <x> and return a pointer to it.
  xInit()       Initialize an <x>. May be necessary if you've allocated
                an <x> on the stack and haven't set it to all zeroes, or
                if you've allocated it using malloc(). Usually simply
                sets the struct to all zeroes. Note: this does *not*
                discard its contents, because it may have uninitialized
                pointers that we don't want to free().
  xClear()      Clear out the contents of an <x>. After this you should
                be able to free() the <x> without getting a memory leak.
                The <x> must have been initialized.
  xDestroy()    Clear *and* free() an <x>.

Overview
--------

bitmask.c, bitmask.h
    Handles bitmasks of unlimited size.

buffer.c, buffer.h
    Provides growing byte buffers.

debug.c, debug.h
    Functions to assist in debugging.

defs.h
    Some useful definitions.

dis.h, dis.h, dis-types.h
    Network dispatcher.

geo2d.c, geo2d.h
    2-D geometry calculations. Obsolescent, due to:

geometry2.c, geometry2.h
    2-D calculations that use vector2.[ch] further down. The new hotness!

hash.c, hash.h
    Provides hash tables.

hashlist.c, hashlist.h
    Combines the best bits of lists and hash tables.

list.c, list.h
    Provides doubly-linked lists.

log.c, log.h
    Provides logging functions.

matrix2.c, matrix2.h, matrix3.c, matrix3.h
    Provides calculations with 2x2 and 3x3 matrices.

mdf.c, mdf.h
    Minimal Data Format parser.

ml.c, ml.h
    Multi-list. Lists where items can be in multiple lists at the same 
    time. However, a consequence is that it can't have the same level of 
    checks that list.[ch] has.

net.c, net.h
    Provides general networking utilities.

ns.c, ns.h, ns-types.h
    Network Server.

options.c, options.h
    Option parser.

pa.c, pa.h
    Pointer arrays.

tcp.c, tcp.h
    Provides TCP networking utilities.

tree.c, tree.h
    Store data in a tree structure. Works much like hash.[ch] from a 
    user perspective, but uses much less memory.

udp.c, udp.h
    Provides UDP networking utilities.

units.h
    Provides conversion from/to SI units.

utils.c, utils.h
    General utilities.

vector2.c, vector2.h, vector3.c, vector3.h
    Provides calculations with 2D and 3D vectors.