Simple but frequently used functions that are not part of C language
   standard library. Unless specifically noted, functions in this section
   are provided to ensure portability of applications that use Nemo Library,
   and are not used internally by functions in other Library sections.

Synopsis:
   #include <nemo.h>
   int nemo_WorkMemInit(nemoWorkMem nwm, size_t size);
Description:
   Initialize an instance of workspace to be used for multiple small-block,
   short-term  memory records. The purpose of such workspace is to provide
   dynamic memory management to applications that require a (very) large number
   of small, transient-use memory blocks. This type of memory use often occurs
   in spatial algebra algorithms over objects defined as 0, 1 and 2 dimensional
   sets of verices. If the system heap (used via malloc()/free() C functions)
   was used in such manner, the gradual and entropic heap fragmentation would
   often be considered unacceptable. This workspace should be considered
   primarily a task-specific, application-private stack. More than one
   workspace can exist at any time.
   ·
   While the facility provided by this family of functions protects the
   application from performance and instability consequences of naive heap
   use, the functions are just as fragile as are the malloc/free functions:
   an out-of-sequence operation, or an operation using an invalid memory
   address can lead to the same consequences as the same error in C library
   heap management functions.
   ·
   The workspace may be used either as the "back-end" facility for various
   common dynamic memory management schemes (stack, queue - see below) or
   it might be used directly by the application.
   ·
   On sizes: while it is assumed total size of the workspace instance can be
   greater than what can be represented by native integer, the size of any
   sub-allocation will never be more than can be so represented.
Arguments:
   nwm:
      Pointer to a memory block of nemoWorkMem type, workspac memory
      instance to be initializd. The memory can be allocated either dynamically
      (i.e., run-time) or statically (compile-time) by the invoker. In either
      case, the block address must be aligned on the most restrictive C object
      boundary. If allocated dynamically, it is the responsibility of the
      invoker to properly free the memory once it is no longer used. Note
      that a small amount of memory at the base of the workspace is used for
      "housekeeping" and therefore not available for subsequent allocations.
   size:
      An integer of size_t type, size in bytes of the memory to be used
      as described above.
Return Value:
   integer, status/error indicator.
   = 1 if the memory address was not aligned.
   = 2 if the memory size was below a minimum value.
   = 0, otherwise.
See Also:
   nemo_WorkMemGet()
   nemo_WorkMemCheck()
   nemo_WorkMemRevert()
   nemo_WorkMemAvailable()
   nemo_WorkMemUsedMax()

Synopsis:
   #include <nemo.h>
   void *nemo_WorkMemGet(size_t size, const nemoWorkMem nwm);
Description:
   Allocate workspace block.
Arguments:
   size:
      Integer, size (in bytes) of the block requested.
   nvm:
      Memory pointer of nemoWorkMem type, workspace instance.
Return Value:
   Pointer to memory block returned, NULL if nwm did not have enough free
   space to satisfy the request.
See Also:
   nemo_WorkMemInit()
   nemo_WorkMemCheck()
   nemo_WorkMemRevert()
   nemo_WorkMemAvailable()
   nemo_WorkMemUsedMax()
   nemo_StackInit()
   nemo_QueueInit()

Synopsis:
   #include <nemo.h>
   void *nemo_WorkMemCheck(size_t size, const nemoWorkMem nwm);
Description:
   Check the availability of a workspace memory block, without "registering"
   the block as being used. Such block may be used if the invoker has full
   confidence no other request for the memory will be made while the block is
   in use. This relieves the invoker from the obligation to release the block
   after it has been used.
Arguments:
   size:
      Integer, size (in bytes) of the block requested. The request for
      0 bytes is the method to obtain the address to which a subsequent call
      to nemo_WorkMemRevert() will be made.
   nvm:
      Memory pointer of nemoWorkMem type, workspace instance.
Return Value:
   Pointer to memory block returned, NULL if nwm did not have enough free
   space to satisfy the request.
See Also:
   nemo_WorkMemInit()
   nemo_WorkMemGet()
   nemo_WorkMemRevert()
   nemo_WorkMemAvailable()
   nemo_WorkMemUsedMax()

Synopsis:
   #include <nemo.h>
   void nemo_WorkMemRevert(void *next, nemoWorkMem nwm);
Description:
   Revert the state of the workspace memory to a previously recorded one.
Arguments:
   next:
      Pointer to free space obtained in a previous call to
      nemo_WorkMemCheck().
   nvm:
      Memory pointer of nemoWorkMem type, workspace instance.
See Also:
   nemo_WorkMemInit()
   nemo_WorkMemGet()
   nemo_WorkMemCheck()
   nemo_WorkMemAvailable()
   nemo_WorkMemUsedMax()

Synopsis:
   #include <nemo.h>
   size_t nemo_WorkMemAvailable(const nemoWorkMem nwm);
Description:
   Report the current size of memory available in the workspace instance.
Argument:
   nvm:
      Memory pointer of nemoWorkMem type, workspace instance.
Return Value:
   Integer of size_t type, size of free space in bytes.
See Also:
   nemo_WorkMemInit()
   nemo_WorkMemGet()
   nemo_WorkMemCheck()
   nemo_WorkMemRevert()
   nemo_WorkMemUsedMax()

Synopsis:
   #include <nemo.h>
   size_t nemo_WorkMemUsedMax(const nemoWorkMem nwm);
Description:
   Different volume, mix, size and complexity of memory objects processed
   by spatial algebra algorithms will require different amounts of workspace
   memory. The total amount of required memory is hard to predict a-priory;
   this function provides the application the ability to sample the use in
   order to develop an approximate required size prediction.
Argument:
   nvm:
      Memory pointer of nemoWorkMem type, workspace instance.
Return Value:
   Integer of size_t type, maximum size of workspace used at any given time,
   over the lifetime of the workspace instance.
See Also:
   nemo_WorkMemInit()
   nemo_WorkMemGet()
   nemo_WorkMemCheck()
   nemo_WorkMemRevert()
   nemo_WorkMemAvailable()

Synopsis:
   #include <nemo.h>
   void nemo_StackInit(nemoStack ns);
Description:
   Initialize stack anchor. Stack is an array of nodes (i.e., objects of
   nemoStackNode type), where each node includes a link to the one before
   it. The array can therefore be traversed very efficiently in the order
   opposite to the order by which nodes were added to it. Stack anchor is
   a small data structure (of nemoStack type, opaque to the invoker) that
   controls one stack instance. It must be initialized before the first call
   to nemo_Push() (I.e., "add a node to the stack").
Arguments:
   ns:
      An object of nemoStack type, stack instance to be initialized.
See Also:
   nemo_Push()
   nemo_Pop()
   nemo_PeekTop()
   nemo_PeekBottom()
   nemo_StackInvert()
   nemo_StackVerify()
   nemo_StackSize()

Synopsis:
   #include <nemo.h>
   int nemo_Push(nemoStack ns,
                 unsigned char *data,
                 int n,
                 nemoWorkMem nwm);
Description:
   Push a node on the stack. The function will allocate the space for the
   stack node (nemoStackNode) assuming the content and size of data is
   as provided by the invoker.
Arguments:
   ns:
      Object (array) of nemoStack type, stack instance.
   data:
      An array of unsigned chars (bytes), values given, data to be included
      in the stack node.
   n: Integer, size (in bytes) of the above.
   nwm:
      Workspace instance from which the node space should be allocated.
Return Value:
   integer, error indicator: 9 if no space left for the node, 0 otherwise.
See Also:
   nemo_StackInit()
   nemo_Pop()
   nemo_PeekTop()
   nemo_PeekBottom()
   nemo_StackInvert()
   nemo_StackVerify()
   nemo_StackSize()
   nemo_WorkMemInit()

Synopsis:
   #include <nemo.h>
   nemoStackNode *nemo_Pop(nemoStack ns);
Description:
   Pop (remove) a top node of the stack. While the node will be removed from
   the stack, no attempt will be made to reclaim the workspace it occupied.
Argument:
   ns:
      Object (array) of nemoStack type, stack instance.
Return Value:
   Pointer of nemoStackNode * type, node removed from the stack, NULL
   if the stack was empty.
See Also:
   nemo_StackInit()
   nemo_Push()
   nemo_PeekTop()
   nemo_PeekBottom()
   nemo_StackInvert()
   nemo_StackVerify()
   nemo_StackSize()

Synopsis:
   #include <nemo.h>
   nemoStackNode *nemo_PeekTop(const nemoStack ns);
Description:
   Inspect ("peek") the top node of the stack, without removing it.
Argument:
   ns:
      Object (array) of nemoStack type, stack instance.
Return Value:
   Pointer of nemoStackNode * type, top node of the stack, NULL
   if the stack was empty.
See Also:
   nemo_StackInit()
   nemo_Push()
   nemo_Pop()
   nemo_PeekBottom()
   nemo_StackInvert()
   nemo_StackVerify()
   nemo_StackSize()

Synopsis:
   #include <nemo.h>
   nemoStackNode *nemo_PeekBottom(const nemoStack ns);
Description:
   Inspect ("peek") the bottom node of the stack, without removing it.
Argument:
   ns:
      Object (array) of nemoStack type, stack instance.
Return Value:
   Pointer of nemoStackNode * type, bottom node of the stack, NULL
   if the stack was empty.
See Also:
   nemo_StackInit()
   nemo_Push()
   nemo_Pop()
   nemo_PeekTop()
   nemo_StackInvert()
   nemo_StackVerify()
   nemo_StackSize()

Synopsis:
   #include <nemo.h>
   void nemo_StackInvert(const nemoStack ns);
Description:
   Invert the order of nodes in a stack. Note that only the previous node
   pointers will be changed in the nodes; the user data portion of the
   node will remain undisturbed.
Argument:
   ns:
      Object (array) of nemoStack type, given and updated stack instance.
See Also:
   nemo_StackInit()
   nemo_Push()
   nemo_Pop()
   nemo_PeekTop()
   nemo_PeekBottom()
   nemo_StackVerify()
   nemo_StackSize()

Synopsis:
   #include <nemo.h>
   int nemo_StackVerify(const nemoStack ns);
Description:
   Traverse the stack and verify its integrity.
Argument:
   ns:
      Object (array) of nemoStack type, stack instance.
Return Value:
   Integer, error indicator:
   -1: empty stack,
    1: Inconsistent stack anchor data,
    2: Inconsistent node count,
    0: Otherwise.
See Also:
   nemo_StackInit()
   nemo_Push()
   nemo_Pop()
   nemo_PeekTop()
   nemo_PeekBottom()
   nemo_StackInvert()
   nemo_StackSize()

Synopsis:
   #include <nemo.h>
   size_t nemo_StackSize(const nemoStack ns);
Description:
   Report the number of nodes on the stack.
Argument:
   ns:
      Object (array) of nemoStack type, stack instance.
Return Value:
   Integer of size_t type, number of nodes on the stack.
See Also:
   nemo_StackInit()
   nemo_Push()
   nemo_Pop()
   nemo_PeekTop()
   nemo_StackInvert()
   nemo_StackVerify()
   nemo_PeekBottom()

Synopsis:
   #include <nemo.h>
   void nemo_QueueInit(nemoQueue ns);
Description:
   Initialize queue anchor. Queue is an array of nodes (i.e., objects of
   nemoQueueNode type, where each node includes a link to the next one.
   The array can therefore be traversed very efficiently in the same order
   as the one by which the nodes were added to it. Queue anchor is a small
   data structure (of nemoQueue type, opaque to the invoker) that controls
   one queue instance. It must be initialized before the first call to
   nemo_EnQueue() (i.e., "add a node to the queue").
Arguments:
   ns:
      An object of nemoQueue type, queue instance to be initialized.
See Also:
   nemo_EnQueue()
   nemo_DeQueue()
   nemo_QueuePeekFirst()
   nemo_QueuePeekLast()
   nemo_QueueVerify()
   nemo_QueueSize()

Synopsis:
   #include <nemo.h>
   int nemo_EnQueue(nemoQueue ns,
                 unsigned char *data,
                 int n,
                 nemoWorkMem nwm);
Description:
   Add a node to the end of the queue. The function will allocate the space
   for the queue node (nemoQueueNode) assuming the content and size of data
   is as provided by the invoker.
Arguments:
   ns:
      Object (array) of nemoQueue type, queue instance.
   data:
      An array of unsigned chars (bytes), values given, data to be included
      in the stack node.
   n: Integer, size (in bytes) of the above.
   nwm:
      Workspace instance from which the node space should be allocated.
Return Value:
   integer, error indicator: 9 if no space left for the node, 0 otherwise.
See Also:
   nemo_QueueInit()
   nemo_DeQueue()
   nemo_QueuePeekFirst()
   nemo_QueuePeekLast()
   nemo_QueueVerify()
   nemo_QueueSize()
   nemo_WorkMemInit()

Synopsis:
   #include <nemo.h>
   nemoQueueNode *nemo_DeQueue(nemoQueue nq);
Description:
   Remove first inserted node from the queue. While the node will be removed
   from the queue, no attempt will be made to reclaim the workspace it occupied.
Argument:
   nq:
      Object (array) of nemoQueue type, queus instance.
Return Value:
   Pointer of nemoQueueNode * type, node removed from the queue, NULL
   if the queue was empty.
See Also:
   nemo_QueueInit()
   nemo_EnQueue()
   nemo_QueuePeekFirst()
   nemo_QueuePeekLast()
   nemo_QueueVerify()
   nemo_QueueSize()

Synopsis:
   #include <nemo.h>
   nemoQueueNode *nemo_QueuePeekFirst(const nemoQueue nq);
Description:
   Inspect ("peek") the first node of the queue, without removing it.
Argument:
   ns:
      Object (array) of nemoQueue type, queue instance.
Return Value:
   Pointer of nemoQueueNode * type, first node of the queue, NULL
   if the queue was empty.
See Also:
   nemo_QueueInit()
   nemo_EnQueue()
   nemo_DeQueue()
   nemo_QueuePeekLast()
   nemo_QueueVerify()
   nemo_QueueSize()

Synopsis:
   #include <nemo.h>
   nemoQueueNode *nemo_QueuePeekLast(const nemoQueue nq);
Description:
   Inspect ("peek") the last node of the queue, without removing it.
Argument:
   ns:
      Object (array) of nemoStack type, stack instance.
Return Value:
   Pointer of nemoQueueNode * type, last node of the queue, NULL
   if the queue was empty.
See Also:
   nemo_QueueInit()
   nemo_EnQueue()
   nemo_DeQueue()
   nemo_QueuePeekFirst()
   nemo_QueueVerify()
   nemo_QueueSize()

Synopsis:
   #include <nemo.h>
   int nemo_QueueVerify(const nemoQueue nq);
Description:
   Traverse the queue and verify its integrity.
Argument:
   ns:
      Object (array) of nemoQueue type, queue instance.
Return Value:
   Integer, error indicator:
   -1: empty queue,
    1: Inconsistent queue anchor data,
    2: Inconsistent node count,
    0: Otherwise.
See Also:
   nemo_QueueInit()
   nemo_EnQueue()
   nemo_DeQueue()
   nemo_QueuePeekFirst()
   nemo_QueuePeekLast()
   nemo_QueueSize()

Synopsis:
   #include <nemo.h>
   size_t nemo_QueueSize(const nemoQueue nq);
Description:
   Report the number of nodes in the queue.
Argument:
   ns:
      Object (array) of nemoQueue type, queue instance.
Return Value:
   Integer of size_t type, number of nodes in the queue.
See Also:
   nemo_QueueInit()
   nemo_EnQueue()
   nemo_DeQueue()
   nemo_QueuePeekFirst()
   nemo_QueuePeekLast()
   nemo_QueueVerify()