/****************************************************************************/
/*	Copyright (c) 2009, Bendor Research Pty. Ltd. All rights reserved.		*/
/*	This software is released under the GNU General Public License, version	*/
/*	3, with the exemptions that 1) the header files installed by this 	 	*/
/*	package can be included in closed-source code and 2) the libraries		*/
/*	built by this package can be statically linked into a closed-source 	*/
/*	binary. See the file LICENSE for the details.							*/
/*	This software is provided "AS IS", without any warranty or guarantee.	*/
/*	By using this software you acknowledge that neither Bendor Research nor	*/
/*	any of its personnel or affiliates can be held liable for any damages,	*/
/*	including, but not limited to, loss of business, loss of money, loss of */
/*	life, loss or reputation, arising out of this software being faulty or	*/
/*	not performing as advertised, even if Bendor Research was aware of such	*/
/*	faults in the software. You use this software at your own risk, any and */
/*	all liabilities that arise out of your using this software are strictly	*/
/*	yours.																	*/
/****************************************************************************/

/**	@addtogroup libc */
/**	@{ */
/**		@defgroup string	String and memory manipulations */
/**		@defgroup stdio 	Standard input/output formatting functions */
/**		@defgroup stdlib	Standard library functions */
/**		@defgroup time		Time manipulation utilities */
/**		@defgroup ctype		Character classes */
/**		@defgroup wchar		Wide character conversions */
/**		@defgroup setjmp	Nonlocal jumps */
/**		@defgroup misc		Miscellaneous functions */
/**	@} */

/** @addtogroup libc

The C library contains many of the functions that are defined by the C99
standard as part of the standard C library.

Functions that do not make sense in a non-hosted, embedded environment have
been omitted. Functions that makes sense but depend on the implementation
of some underlying service are either omitted or provided in a form that
requires you to write an implementation-aware wrapper around them.
Some functions that are not re-entrant or assume the presence of certain
system services have also been omitted or are provided in a form that is
not strictly standard compliant but useful in an embedded system.

Several functions that are not specified by the standard but are useful,
logically belong to this group or simply complement the functions defined
by the standard have been added.

Since it is intended for embedded systems, it goes without saying that
all functions in the library are re-entrant, they operate only in registers,
on the stack or in memory explicitely provided by you.
*/

/** @addtogroup stdio

Core functions for formatted input and output.

The C standard defines a bunch of input/output functions. However, those
functions depend on the notion of files and byte streams, defined and
associated with physical devices by the underlying operating system.
Since this library is targeted to embedded systems, where the concept of
files and byte streams may or may not exist at all and device abstractions
vary from system to system, this library contains only the formatting core
of the input and output functions. These cores can be used to realise all
the standard designated printf() and scanf() family functions. You have to
write a little wrapper around the core, to provide the standard interface.
Furthermore, you have to supply the lowest level byte I/O functions that
will be called by the core functions. The details are explained in the
function descriptions.
<br><br>
To use these functions you have to include <tt><b>stdio_format.h</b></tt>.

*/

/** @addtogroup stdlib

This part of the library has been extended with functions that are
not part of the standard but that I believe are useful in a resource
constrained system, especially if you want to avoid the use of a
<tt>printf()</tt> and <tt>scanf()</tt> type function.
<br><br>
To use these functions you have to include <tt><b>stdlib.h</b></tt>.

@section strtoint	String to number conversions

	The standard defines functions that convert a string to an
	integer and functions that convert a string to a float-point
	number. In case of an overflow, these functions are to set \p errno
	to the relevant error code. Since in your system there might not
	be an equivalent of errno or you have some custom implementation,
	the standard functions do not support error detection at all.<br>
	To make up for that deficiency, all string to number functions
	are also available in a form where they take an additional
	argument, a pointer to a function returning \p void, that is
	called if the conversion overflows. In that function you can
	implement your custom \p errno setting or equivalent error
	signalling functionality.

@section inttostr	Integer to string conversion

	The standard does not define functions to convert integers to
	strings, probably because the functionality can be achieved by
	calling <tt>sprintf()</tt>. However, the formatted print core is
	huge compared to a simple conversion and if you need to convert
	integers to strings but otherwise do not need formatted print,
	then the code burden (and run-time overhead) of using sprintf()
	is excessive.<br>
	Therefore the library provides functions to convert 32 and 64 bit
	unsigned integers to strings. The generic function can convert
	numbers using any radix between 2 and 36 but specialised fast
	functions are also available for radix 10 and radices that are
	powers of 2. <br>
	None of the conversion functions use division and a conversion of
	a 32-bit number to a decimal string takes about as much time as a
	single 32-bit division on the ARM7TDMI core (it doesn't have a
	HW divider), conversion of a 64-bit number takes just a bit longer
	than twice as much.<br><br>
	<i>It is possible that the decimal conversion is actually novel, at
	least I could not find any reference to the conversion method used
	by the library on the 'Net. If it is indeed novel and by any chance
	patentable (everything seems to be patentable these days), then it
	is hereby declared public knowledge and prior art to any future
	patent claim.</i>

*/

/** @addtogroup string

This group contains functions that manipulate memory and C zero-terminated
strings.
<br><br>
To use these functions you have to include <tt><b>string.h</b></tt>.

@section strinline Inlined functions
A lot of these functions provide very simple functionality,
their "classic" implementation is only a few lines of C code.
Therefore, they are prospective candidates for inlining and the library
supplies inlined versions of the most basic functions.
The following functions have inlined versions:
- memcpy(), memrcpy(), memcmp(), memset(), memmove(), memchr(), memrchr()
- strlen(), strnlen(), strcpy(), strncpy(), strcat(), strncat(),
strcmp(), strncmp(), strchr(), strrchr()

To access the inlined versions, you have to define the symbol
@code
#define	BLC_STRING_INLINE
@endcode
before you include <tt>string.h</tt> in your code.
@section strfast Fast functions
Some selected functions are also provided in assembly form, where size is
traded for speed. These functions have a <tt>_fast</tt> suffix in their
name, therefore you can distinguish between the "classic" implementation
and the fast one. The prototype and behaviour of the fast function is the
same as the corresponding "classic" function, with the
following considerations:
- The fast functions work only on a little endian target.
- The string manipulation fast functions can read beyond the '\\0' that
marks the end of a string. In particular, these functions fetch a word at a
time and will stop when they fetched the word that contains the closing '\\0'.
That means that they may read beyond the end of the string by up to 3 bytes.
It is only for read, the functions never write after the closing 0.
The <tt>memXXX()</tt> family functions never read or write beyond the
specified length of the memory area.

You can use the fast functions regardless of whether you use the inlined or
not inlined "classic" versions; however, the fast versions are never inlined.

If you define the symbol
@code
#define	BLC_STRING_FAST
@endcode
before you include the <tt>string.h</tt> header, then macros will be used to
map the functions to the fast functions where available. You can still use
the explicite fast functions, but even the "normal" functions will actually
call the fast versions. If you define both <tt>BLC_STRING_FAST</tt> and
<tt>BLC_STRING_INLINE</tt> then functions that have fast version will be
mapped to the fast version and not inlined while functions that have inline
format but no fast version will be inlined.<br>
The following functions are provided in fast version:
- memcmp(), memset(), memcpy(), memrcpy(), memmove()
- strcpy(), strncpy(), strlen(), strnlen(), strcat()

@section strfasttab Code size and speed comparison
The following table gives you a rough idea of the speed and size
trade-off when using the <tt>memXXX_fast()</tt> functions. The data was
obtained on an LPC23xx running at 60MHz from its internal FLASH. The code
increase is just a rough measure, the slow version code size is rather
dependent on whether you compile for ARM or THUMB, the compiler version,
the flags and so on. Since the slow functions treat memory as bytes, data
alignment for those does not matter. On the other hand, alignment, in
particular the relative alignment of source and destination, has a
significant effect on the fast versions, therefore timing data for both
aligned and misaligned cases are given.
<b>@verbatim
Function    Code size     Data       Execution time [µs]
name        increase     [bytes]    slow    alig.   misal.
@endverbatim</b>
@verbatim
memset()       ~ 4            5     1.57    1.38    1.90
                             40     8.57    1.62    2.10
                            320    64.57    3.65    4.13
                           2560   512.57   19.66   20.14
@endverbatim
@verbatim
memcmp()       ~ 7            5     2.32    1.92    2.05
                             40    13.10    3.77    6.35
                            320    99.43   22.43   29.69
                           2560   790.10  171.77  216.35
@endverbatim
@verbatim
memcpy()       ~ 7            5     1.62    1.32    2.24
memrcpy()                    40     9.65    3.38    6.48
                            320    69.01   11.84   28.21
                           2560   539.05   71.65  189.95
@endverbatim
@verbatim
memmove()      ~ 15           5     1.84    1.42    2.39
                             40    10.08    3.97    6.61
                            320    69.67    9.13   16.67
                           2560   539.92   38.80   71.48
@endverbatim
<br>
The <tt>strXXX_fast()</tt> functions are only about 3-4 times as fast as their
normal counterparts and about 7 times larger. These functions are not
detailed in a table form.
*/

/**	@addtogroup ctype

These functions work on ASCII characters and can classify them as well as
change between upper and lower case letters.
<br><br>
To use these functions you have to include <tt><b>ctype.h</b></tt>.<br><br>
The character classification is based on a class table, so these functions
do a single table lookup. Such simple functions are good candidates for
inlining. Therefore, if you define the
@code
#define BLC_CTYPE_INLINE
@endcode
symbol before you include the <tt>ctype.h</tt> header, then the functions
will be inlined.

*/

/** @addtogroup setjmp

This function pair allows you to return from a deep function call chain
in one hit. This is useful when you have some sort of a parser where you
descend deeper and deeper as you go along. If everything is fine, then
you will return step by step. However, if you discover an error, then
you will have to propagate that error up to the top level. This means
that every function has to have code to do nothing else just pass the
error up. You can save all that trouble by calling setjmp() at the top
level and calling longjmp() if you detect the error. The call to longjmp()
will unwind the stack, restore the state of the top-level function to the
same state as when it called setjmp() and setjmp() will return to the
top level function again.
<br><br>
When setjmp() returns to the caller the first time it returns 0. If it
returns to the caller the second time (that is, because longjmp() was called)
it is guaranteed that the return value is not 0. Therefore, the caller of
setjmp can differentiate between the two kinds of returns.
<br><br>
The type of the object that contains the saved processor state is
<tt>jmp_buf</tt>, which is an opaque type, which you can use to
declare objects that can be passed to functions but can not be lvalues.
<br><br>
The state that was saved by setjmp() must be passed to longjmp() verbatim.
The state goes out of scope if the function containing setjmp returns, even
if it is stored in static storage. Calling longjmp() on such state may or
may not cause an immediate system crash but will most definitely cause very
hard to find bugs.
<br><br>
To use these functions you have to include <tt><b>setjmp.h</b></tt>.
*/

/** @addtogroup wchar

These functions convert between wide chars (16 or 32 bit) and their UTF-8
representation. Whether the wide character is 16 or 32 bit depends on you
specifying the <tt>-fshort-wchar</tt> switch to gcc or not.
<br><br>
UTF-8 can encode any value between 0x00000000 and 0x3FFFFFFF. The RFC3629
specifies that the valid range for a Unicode character is between 0x00000000
and 0x0010FFFF and that the range 0x0000D800 - 0x0000DFFF must not be used.
In addition, the RFC also specifies that UTF-8 sequences that are longer than
necessary should be treated as erroneous.<br>
You can configure the library to enforce RFC3629 conformance by defining the
preprocessor symbol <tt><b>BLC_RFC3629_CONFORMANCE</b></tt> <i>before</i> you
include the <tt>wchar.h</tt> header file.<br><br>
The functions  declared by the header are actually macros, which select the
underlying function depending on the size of the wide character type and
whether you specified RFC3629 conformance or not.
<br><br>
To use these functions you have to include <tt><b>wchar.h</b></tt>.
*/

/** @addtogroup time

These functions convert between calendar date and UNIX representation of time.
UNIX stores time as the number of seconds since 1970-01-01 00:00:00 GMT, known
as the 'Epoch'. Most modern UNIX-ish systems store the time as a signed 64-bit
quantity, allowing you to go back before the Big Bang and go forward to and
beyond the end of the Solar System. The reference has changed from Greenwich
Mean Time (GMT) to Universal Coordinated Time (UTC) and leap seconds were
introduced, so things are getting a bit complicated.
<br><br>
This library, however, stores the number of seconds in a 32-bit unsigned
integer. The unsigned nature means that you can only go back to the Epoch
and your clock will roll over in 2106, less than a century in the future.
In addition, the routines do not care about leap seconds (leap years are
respected, of course). Despite those limitations, for practical timekeeping
the format is sufficient; most embedded gizmos just keep track of the
current time using a watch crystal. If you really need to go back more than
40 years or forward by more than a century or you need atomic precision
timekeeping, alas, you will have to write your own specialised routines.
<br><br>
The routines in the library allow you to convert between the above mentioned
format and the Gregorian calendar format. The structure that stores the
calendar format (known as the broken-down time format) strongly mimics the
same structure defined by the POSIX standard. However, instead of defining
every field as an integer, the fields are only as wide as they have to be.
This results in a significant space saving in the structure size.
<br><br>
Timezone management is left to you. The routines can take the time zone into
account, in fact you must set the timezone field in the broken-down time
structure, but that field is just an offset. It's you who has to maintain
that offset according to your timezone and/or summer light saving time.
<br><br>
To use these functions you have to include <b><tt>time.h</tt></b>.

*/

/**	@addtogroup misc */
/**	@{ */
/**		@defgroup misc_bits	Bit manipulation functions */
/**		@defgroup misc_mult	Multiplication and division utilities */
/**		@defgroup misc_dll  Doubly linked list functions */
/**		@defgroup misc_avl	AVL tree function templates */
/**	@} */

/**	@addtogroup misc

This group contains functions that are not defined by the C standard but are
often useful in embedded system work.

*/

/** @addtogroup misc_bits

These functions provide some often needed bit manipulation capabilities.

Although the actual functionality for each of these functions can be realised
in a singe line of C code, the naive implementation involves looping.
The implementations in the library use more efficient sequential algorithms
and are written in assembly, thus they are rather fast.
<br><br>
To use these functions you have to include <tt><b>misc/bits.h</b></tt>.

*/

/** @addtogroup misc_mult

Functions to speed up multiplication and division in certain cases.

The ARM7TDMI core has instructions that multiply two 32 bit words and
and gain a 64 bit result. However, those instructions are not available in
THUMB mode. These functions provide access to those instructions efficiently.
If the code is compiled for ARM, these functions will be inlined and turned
into a few assembly instructions by gcc. When compiling for THUMB, these
functions will be faster than what you could achieve by type-casting the
multiplicands and let the compiler generate the multiplication for you.
<br><br>
The division routines can be used to avoid doing actual division when
the same divisor is used several times. Preparation for the fast division
takes about 4 times longer than a division, but then the fast division
itself will be about 10 times faster than normal division. If the divisor
is a constant or changes infrequently, then you can save a lot of runtime
using these routines.
<br><br>
To use these functions you have to include <tt><b>misc/multiply.h</b></tt>.

*/

/** @addtogroup misc_dll

Basic operations on doubly-linked lists.

Linked lists and doubly linked lists are pretty often used objects.
These functions provide the basic operations on doubly linked lists.
<br>
Two structures are defined, one represents the list and the other represents
a list member (a link in the chain). Both structures contain two pointers and
nothing else. The functions can be used to add and remove elements, cut and
append lists and traverse the elements of a list.
<br><br>
To use these functions you need to include <tt><b>misc/dlink.h</b></tt>.<br>
Since the functions are very simple, they are a good candidate for inlining.
If you define <tt><b>BLC_DLINK_INLINE</b></tt> before you include
<tt>misc/dlink.h</tt>, then the functions will be inlined.
<br><br>
Of course, you want to build a list of your own structures. One possibility
would be if the list members contained a pointer to your structure. However,
that approach separates the memory needed for the list pointers from the
object to which they belong (your structure). That can lead to all sorts of
complications. The other possibility is to put the link structure inside your
own data:
@code
#include <misc/dlink.h>

typedef struct {

	DLLINK	link;		// Doubly-linked list pointers, must be first!
	...					// Rest of your data
} MYDATA;
@endcode
Since the link is the first element of the structure, its address is the
same as that of the structure itself. Therefore, you can simply cast the
structure pointer to a DLLINK pointer when you pass it to the list handling
functions and cast it to your type when you receive it:
@code
MYDATA *data;
DLLIST some_list;

	// Remove the head of the list and put it to the tail

	data = (MYDATA *) DL_GetHead( &some_list );
	DL_AddTail( &some_list, (DLLINK *) data );
@endcode
While this works, there are cases when you can not guarantee that the link
is the first member, for example if you want your objects to be on two lists
in the same time:
@code
#include <misc/dlink.h>

typedef struct {

	DLLINK	link1;		// Doubly-linked list pointers for the first list
	DLLINK	link2;		// Doubly-linked list pointers for the second list
	...					// Rest of your data
} MYDATA;
@endcode
Deriving the address of a DLLINK object from the structure pointer is
trivial, of course:
@code
MYDATA *data;
DLLIST list1;
DLLIST list2;

	DL_AddTail( &list1, &data->link1 );
	DL_AddTail( &list2, &data->link2 );
@endcode
It's a bit trickier to get the address of the structure from the address
of the link. However, you can easily write a macro to do that for you:
@code
// Returns a pointer to a structure of type 'type' of which the
// member 'member' has the address of 'addr'.

#define BASE( type, member, addr ) 	\
	((type *)((char *)(addr) - offsetof( type, member )))


// If you use gcc, you can use the built-in offsetof:

#define offsetof( type, member ) __builtin_offsetof( type, member )


// Alternatively, you can define your own (although this solution works
// only for structures while gcc's builtin works with arrays as well):

#define offsetof( type, member ) (&((type *)0)->member)
@endcode
Using the BASE macro you can get your objects back:
@code
MYDATA *data;
DLLINK *temp;

	temp = DL_GetHead( &list2 );

	if ( link != NULL ) {

		data = BASE( MYDATA, link2, temp );
		...
@endcode

*/

/** @addtogroup misc_avl

This module contains a template to build an AVL-tree.

The AVL tree is a self-balancing binary search tree, named after
Adelson-Velskiy and Landis, the Russian mathematicians who invented
it in 1962. It allows you to keep data in a sorted manner. Finding,
inserting and deleting a node all take O( log<sub>2</sub>( N ) ) time
even in worst case, therefore the AVL tree is an efficient tool to
implement small "databases" in embedded systems.
<br><br>
This implementation is actually a template. It does not assume much
about your information and how you store it. In fact, it is not a
usable C implementation on its own, you must write small wrapper
functions that will be the actual API for the handling of the tree
and you need macros or small inline functions to access your chosen
data format. However, all the algorithmic working is in the library,
so you do not have to know how AVL trees work to use it.
<br><br>
Nodes are ordered by a key. The keys must be unique, the same key can
not be on the tree multiple times. The routines will refuse to insert
the same key twice.<br>
Apart from this key and your own data, your nodes need to store three
more pieces of information that the AVL tree uses.<br>The first is an
integer type that must be wide enough to store the height of the tree.<br>
The other two information fields in your node are references to two
other nodes (the subtrees under this node). Note the word 'reference'.
Normally these would be pointers. However, the library does not assume
that you have a tree that is built from node structures stored in memory.
The references <i>can</i> be pointers, but it is not a strict requirement.
The importance of this will be explained later.
<br><br>
To use this template you do the following:
- Declare your own API in your header file.
- Start the implementation C file.
- Include <i>your</i> header but not the <b><tt>misc/avl.h</tt></b> header.
- Define a couple of things and write a few very simple inline functions,
  explained very soon.
- Now you include <tt>misc/avl.h</tt>
- Write your API functions, using the AVL tree operation functions defined
  by the included header. These AVL functions, in turn, will refer to the
  things you defined before you included <tt>misc/avl.h</tt>.

This is what you have to define <i>before</i> you include <tt>misc/avl.h</tt>:
- Define which functions of the library you will use. It is assumed that the
  AVL_Search() and AVL_Insert() functions will be used, but for every other
  function in the template you have to define a macro if you want to use it.
  The macro to define to use a particular function is specified at the
  function's documentation.
- Define the type <tt><b>AVL_NODE</b></tt>.<br>
  This type is a reference to a node. If your nodes are structures, then
  this type is a pointer to your node structure. However, as you will see,
  it is not a strict requirement, the node type can be any type that you
  can use as an operand to the equivalence operator (i.e. the <tt>==</tt>).<br>
- Define the macro <tt><b>AVL_NULL</b></tt>.<br>
  This value represents the reference to a nonexistent node. If you use
  structures and pointers then it is <tt>NULL</tt> but if your
  <tt>AVL_NODE</tt> is some other type, then you have to find a suitable
  value of that type which can never be a valid reference to a node.<br>
- Define the type of your key, <tt><b>AVL_KEYT</b></tt>.<br>
  This type can be any type that can be passed to a function by value.
  Again, it is a reference type, which may or may not be the actual key
  type. <tt>AVL_KEYT</tt> objects are just passed around, only one function
  does really have to know what to do with a key and that function is written
  by you.<br>
- Define the maximum depth of your tree, <tt><b>AVL_PLEN</b></tt>.<br>
  The value of this macro depends on your number of nodes and later you
  will find a table that shows you what you should declare here depending
  on the maximum number of nodes on your tree.<br>
- Define a type, <tt><b>AVL_USER</b></tt>.<br>
  This must be a type that you can pass to a function. The functions in the
  template library do not use it for anything whatsoever, but they accept
  one parameter of that type and that parameter will subsequently be passed to
  your functions. The reason for that will be explained later.<br>
- Define macros or <tt>static</tt>, possibly <tt>inline</tt> functions that
  extract node information.<br>
  You have to define three functions, namely <tt><b>AVL_GET_L(), AVL_GET_R(),
  AVL_GET_H()</b></tt>. They receive a node reference and return the node's
  left subtree, right subtree and height, respectively.<br>
- Define macros or <tt>static</tt>, possibly <tt>inline</tt> functions that
  set node fields.<br>
  You have to define three functions, namely <tt><b>AVL_SET_L(), AVL_SET_R(),
  AVL_SET_H()</b></tt>. They receive a node reference and an other parameter.
  They should set the node's left tree reference, right tree reference and
  height, respectively, to the operand they receive.<br>
- Define a macro or a <tt>static</tt>, possibly <tt>inline</tt> function to
  compare keys.<br>
  This function is called <b><tt>AVL_CMP()</tt></b> and it receives a node
  reference and a key reference. It then returns an integer that is positive,
  negative or zero depending on whether the node's key is, respectively, less
  than, greater than or equal to the key.

The prototype of these functions is the following:
@code
static AVL_NODE AVL_GET_L( AVL_NODE node, AVL_USER user );
static AVL_NODE AVL_GET_R( AVL_NODE node, AVL_USER user );
static unsigned AVL_GET_H( AVL_NODE node, AVL_USER user );

static void AVL_SET_L( AVL_NODE node, AVL_NODE tree, AVL_USER user );
static void AVL_SET_R( AVL_NODE node, AVL_NODE tree, AVL_USER user );
static void AVL_SET_H( AVL_NODE node, unsigned height, AVL_USER user );

static int  AVL_CMP( AVL_NODE node, AVL_KEYT refk, AVL_USER user );
@endcode
If the functions are simple, you should specify them as inline, or,
if you prefer macros over inlined functions, you can use those
instead of functions.
<br><br>
After definig these, you include <tt>misc/avl.h</tt>. That file, in turn,
defines a type and a bunch of functions. The functions are the basic AVL
tree managing functions. You can then use them to implement your own API
functions with very little code. Most importantly, it is your responsibility
to allocate and prepare new nodes, to handle the information in the node and
to deallocate deleted nodes. Furthermore, if you run in a multitasking
environment, then the protection from simultaneous access is on your shoulders
too.
<br><br>
You also have to provide a workspace for the tree handling routines.
That workspace is a structure that has the type of <tt><b>AVL_PATH</b></tt>.
Among a couple of other fields it contains an array of <tt>AVL_NODE</tt>
references. The size of the array is the value you defined by the
<tt>AVL_PLEN</tt> macro. The following table shows you the minimum value
of <tt>AVL_PLEN</tt> for a given maximum value of nodes.<br>
The first column contains the maximum number of nodes on your tree, the
second column contains the minimum value that you should use when you
define <tt>AVL_PLEN</tt> and the third column is the minimum width,
in bits, of the height field in your node (see the examples).
<b>
@verbatim
      N    P   W                   N    P   W                   N    P   W
@endverbatim
</b>
@verbatim
      1    2   1               2,582   16   4           2,178,307   30   5
      3    3   2               4,179   17   5           3,524,576   31   5
      6    4   2               6,763   18   5           5,702,885   32   5
     11    5   3              10,944   19   5           9,227,463   33   6
     19    6   3              17,709   20   5          14,930,350   34   6
     32    7   3              28,655   21   5          24,157,815   35   6
     53    8   3              46,366   22   5          39,088,167   36   6
     87    9   4              75,023   23   5          63,245,984   37   6
    142   10   4             121,391   24   5         102,334,153   38   6
    231   11   4             196,416   25   5         165,580,139   39   6
    375   12   4             317,809   26   5         267,914,294   40   6
    608   13   4             514,227   27   5         433,494,435   41   6
    985   14   4             832,038   28   5         701,408,731   42   6
  1,595   15   4           1,346,267   29   5       1,134,903,168   43   6
@endverbatim
<br>
Now that you defined everything and the library also defined everything, you
can write your API functions. These will use the functions provided by the
<tt>misc/avl.h</tt> file. They are formally specified by the function
specification section, so that's not repeated here.
<br><br>
A little explanation is in order with regards to that mysticism about
references instead of pointers, bit-width of integers and the obscure
<tt>user</tt> parameter of every function. There are several issues
that warrant all that magic. Instead of giving you the verbiage about
them, you will find some example code below that shows you how to use
them. Hopefully these will make it clear why the cruft is there.
Note that although the examples seem quite long, most of it is explanatory
comments. The actual code you have to write is just a few tens of lines.

@par Basic AVL tree example
@include avl1.c
@par Memory starvation example
@include avl2.c
@par Associative array example
@include avl3.c
*/

