/* librock/mstruct.h  "Building-Block" memory structures.
   - - - - - - - - - - - - Copyright Notice - - - - - - - - - - - -
     Copyright 1996,1997,1998,1999 Forrest J. Cavalier III

   See http://www.mibsoftware.com/librock/ for documentation and
   original copies of this software.

   This software shall be distributed with the implementation
   source code according to the license terms of the source code.

License text in <librock/license/librock.txt> librock_LIDESC_HC=12440211096131f5976d36be0cddca4cd9152e45
*/
#ifndef librock_INC_MSTRUCT_H
#define librock_INC_MSTRUCT_H

#include <librock/target/local.h>

/*#include <librock/target/types.c>*/  /* librock_PTR based on OS, etc. */
/*#include <string.h>*/
/*#include <assert.h>*/

/* There are three general purpose memory structures
   provided by librock.  There are C++ wrapper classes
   for the C language versions.

   VSB - implements a variable sized block of memory.
         A struct VSB_s points to a block of memory which
         can move so that it can be resized.  Functions
         are provided which can insert and delete data
         in the block of memory, which can be as large
         as the maximum value of an int.

         The VSB functions "overallocate" memory (take
         more than is needed to satisfy the request) to
         accomodate some growth without having to move
         the buffer.  For this reason, the size of the
         block and the size of the allocation are also
         members of the struct VSB_s.

       Typical uses of Vsb's: working buffers for
         string editing, "building" variable length
         memory structures, holding variable length
         objects, implementing variable length arrays
         or memory blocks where all memory must be
         contigous.

         Adding a NUL terminator to the string is easily
         using the NULTerminate() call.  (But also see
         the librock/astring.h functions for handling
         allocated NUL terminated strings.)

       C++ wrapper:  CVsb

       C++ derived classes:
         CVsbLongList a contiguous block of long values
         CVsbShortList a contiguous block short values
         CVsbPtrList a contiguous block of void * values

   FSIL - Fixed size indexed list.  All items in the
         list are a fixed size. A pointer to an item
         is obtained by using an integer index.  Items
         can be inserted or deleted in the list.  (To
         replace an item in the list, get a pointer,
         and modify the item in place.)

         A FSIL is implemented in separate blocks of
         allocated memory, each holding a number of
         items.  This allows adding items without
         copying the entire list.  Sequential items
         may not be adjacent in memory.

       Typical uses: base for FIFO and LIFO stacks
         and queues, and lists.  Efficient implementation
         of arrays with variable number of elements.

       C++ wrapper:  CFsil

       C++ derived classes:
         CInPlaceFsil - use when an item once defined
             should never move in memory.  Disables the
             insert and delete methods.  Appending is
             permitted.
         CFsilLongList - each item is a long value
         CFsilLIFO - a last in first out stack
         CLongLIFO - a last in first out stack of long
                     values


  VSIL - Variable size indexed list.  All items in the
         list are a variable size.  A pointer and a
         size of an item is obtained using an integer
         index.  Items can be inserted, deleted, or
         replaced in the list. (Modifying an item in
         place is only possible if the size will remain
         the same.)

         A VSIL_s is implemented in separate blocks of
         allocated memory, each holding a number of
         items.  This allows adding items without
         copying the entire list.  For convenience,
         a '\0' separates each item.  Sequential items
         may not be adjacent in memory.

       C++ wrapper:  CVsil
*/

#include <librock/vsb.h>
#ifndef librock_NOIMPL_fsil_h
#include <librock/fsil.h>
#endif
/*
#include <librock/vsil.h>
*/
#ifndef librock_NOIMPL_ialloco_h
#include <librock/ialloco.h>
#endif

#ifndef librock_NOIMPL_prcl_h
#include <librock/prcl.h>
#endif

#ifdef __cplusplus
#ifdef librock_PTR

class librock_Autoclean
{
        void **m_ppv;
        void (*m_fn)(void *);
public:
        librock_Autoclean(void librock_PTR **ppv,void (*fn)(void *)) {
                m_ppv = ppv;
                m_fn = fn;
        };
        librock_Autoclean(librock_CONST char librock_PTR **ppv,void (*fn)(void *)) {
                m_ppv = (void **) ppv;
                m_fn = fn;
        };
        librock_Autoclean(char librock_PTR **ppv,void (*fn)(void *)) {
                m_ppv = (void **) ppv;
                m_fn = fn;
        };
        ~librock_Autoclean() {
                if (*m_ppv && m_fn) {
                        (*m_fn)(*m_ppv);
                }
        }
private:
        librock_Autoclean() {   /* No default constructor */
        };

};
#endif

void librock_cleanp(void *ppv,void (*fn)(void *));
void librock_cleanpp(void **ppv,void (*fn)(void *));



#include <librock/target/local2.h>
#endif

#endif /* #ifndef _INC_librock_MSTRUCT_H */

/*
$Log: mstruct.h,v $
Revision 1.4  2002/02/10 03:19:08  forrest@mibsoftware.com rights=#1
Standardized chg log

Revision 1.3  2002/01/29 20:21:25  forrest@mibsoftware.com rights=#1
   Moved librock_EXPERIMENTAL bracketing of #include prcl.h to prcl.h

Revision 1.2  2002/01/29 04:40:03  forrest@mibsoftware.com rights=#1
   Prep for publish.  API clean up, TAB, space at eol removal

Revision 1.1  2001/01/06 19:36:17  forrest@mibsoftware.com rights=#1
   Initial import to CVS

rights#1 Copyright (c) Forrest J Cavalier III d-b-a Mib Software
rights#1 License text in <librock/license/librock.txt> librock_LIDESC_HC=12440211096131f5976d36be0cddca4cd9152e45
*/