/*****************************************************************************/
/*
                                  StrDsc.h
*/
/*****************************************************************************/

#ifndef STRDSC_H_LOADED
#define STRDSC_H_LOADED 1

/* application related header files */
#include "wasd.h"

/*******************/
/* data structures */
/*******************/

#pragma member_alignment __save
#pragma member_alignment

typedef struct StrDscStruct STR_DSC;

struct StrDscStruct
{
   /* pointer-to-self */
   STR_DSC*  itself;
   /* bit vector */
   unsigned long  flags;
   /* size of storage (maximum capacity) */
   unsigned long  size;
   /* current length of used storage */
   unsigned long  length;
   /* reallocate (plus) these bytes rather than link to new descriptor */
   unsigned long  realloc;
   /* pointer to storage */
   char  *pointer;
   /* request pointer (for memory allocation) */
   REQUEST_STRUCT  *rqptr;
   /* allow these (STR_DSC) descriptors to be linked together */
   struct StrDscStruct  *flink,
                        *blink;
};

#pragma member_alignment __restore

/*************/
/* constants */
/*************/

/* descriptor itself has been allocated */
#define STR_DSC_FLAG_DYNAMIC     0x00000001
/* storage pointer is to allocated memory */
#define STR_DSC_FLAG_STORAGE     0x00000002
/* storage pointer is to storage external to the descriptor */
#define STR_DSC_FLAG_EXTERNAL    0x00000004
/* descriptor is a 'collection' (list) of discrete buffers */
#define STR_DSC_FLAG_COLLECTION  0x00000008
/* descriptor storage has been frozen (allocate another) */
#define STR_DSC_FLAG_FROZEN      0x00000100
/* descriptor storage has been 'noted' in some way */
#define STR_DSC_FLAG_NOTED       0x00000200
/* bits to indicate flags are actually flags (perhaps :-) */
#define STR_DSC_FLAG_FLAG        0x0aa00000

/**********/
/* macros */
/**********/

/* check if this structure makes sense */
#define STR_DSC_SANITY(ptr) \
(((ptr)->itself == ((STR_DSC*)~(unsigned long)ptr)) && \
  (((ptr)->flags & STR_DSC_FLAG_FLAG) == STR_DSC_FLAG_FLAG) && \
 !((ptr)->flags & ~(STR_DSC_FLAG_FLAG | \
                    STR_DSC_FLAG_DYNAMIC | \
                    STR_DSC_FLAG_STORAGE | \
                    STR_DSC_FLAG_EXTERNAL | \
                    STR_DSC_FLAG_COLLECTION | \
                    STR_DSC_FLAG_FROZEN | \
                    STR_DSC_FLAG_NOTED)) && \
 !(((ptr)->flags & STR_DSC_FLAG_STORAGE) && \
   ((ptr)->flags & STR_DSC_FLAG_EXTERNAL)))

/* for descriptors allocated on automatic storage (function stack) */
#define STR_DSC_AUTO(name) STR_DSC name = { 0, 0, 0, 0, 0, 0, 0, 0, 0 }

#define STR_DSC_FLAGS(ptr) ((ptr)->flags)
#define STR_DSC_LEN(ptr) ((ptr)->length)
#define STR_DSC_NEXT(ptr) ((ptr)->flink)
#define STR_DSC_SIZE(ptr) ((ptr)->size)
#define STR_DSC_PREV(ptr) ((ptr)->blink)
#define STR_DSC_PTR(ptr) ((ptr)->pointer)
#define STR_DSC_RQPTR(ptr) ((ptr)->rqptr)

#define STR_DSC_ZERO(ptr) { memset(ptr,0,sizeof(STR_DSC)); }

/* grow the allocated memory by this amount when required */
#define STR_DSC_REALLOC(ptr,grow) (ptr)->realloc = grow;
#define STR_DSC_GROW(ptr,grow) (ptr)->realloc = grow;

/* set/test if the descriptor is frozen */
#define STR_DSC_IS_FROZEN(ptr) ((ptr)->flags & STR_DSC_FLAG_FROZEN)
#define STR_DSC_SET_FROZEN(ptr) (ptr)->flags |= STR_DSC_FLAG_FROZEN;

/* if the descriptor is using storage external to itself */
#define STR_DSC_IS_EXTERNAL(ptr) ((ptr)->flags & STR_DSC_FLAG_EXTERNAL)

/* if the descriptor is 'noted' in some way */
#define STR_DSC_IS_NOTED(ptr) ((ptr)->flags & STR_DSC_FLAG_NOTED)
#define STR_DSC_SET_NOTED(ptr) (ptr)->flags |= STR_DSC_FLAG_NOTED;
#define STR_DSC_RESET_NOTED(ptr) (ptr)->flags &= ~STR_DSC_FLAG_NOTED;

#define STR_DSC_DEFAULT_SIZE 256

/* wrapper on a simple for(;;) loop */
#define STR_DSC_ITERATE(ptr,dsc) for(ptr=dsc;ptr;ptr=ptr->flink)

/***********************/
/* function prototypes */
/***********************/

STR_DSC* StrDscBegin (REQUEST_STRUCT*, STR_DSC*, int);
STR_DSC* StrDscBuffer (STR_DSC*);
STR_DSC* StrDscBuild (STR_DSC*, STR_DSC*, char*);
STR_DSC* StrDscBuildHtmlEscape (STR_DSC*, STR_DSC*, char*);
StrDscChunk (STR_DSC*, int);
STR_DSC* StrDscChunkNew (REQUEST_STRUCT*, int);
STR_DSC* StrDscColIfNotBegin (REQUEST_STRUCT*, STR_DSC*, int);
StrDscDebug (STR_DSC*, char*);
StrDscEnd (STR_DSC*, char*, int);
STR_DSC* StrDscDup (STR_DSC*, STR_DSC*);
STR_DSC* StrDscExternal (REQUEST_STRUCT*, STR_DSC*, char*, int);
STR_DSC* StrDscFreeze (STR_DSC*);
STR_DSC* StrDscIfNotBegin (REQUEST_STRUCT*, STR_DSC*, int);
int StrDscLength (STR_DSC*);
STR_DSC* StrDscNewLine (STR_DSC*);
StrDscNoContent (STR_DSC*);
int StrDscRealloc (REQUEST_STRUCT*, STR_DSC*, int, char*, int);
BOOL StrDscSame (STR_DSC*, STR_DSC*, BOOL);
StrDscSwap (STR_DSC*, STR_DSC*);
StrDscStorageSwap (STR_DSC*, STR_DSC*);
STR_DSC* StrDscTail (STR_DSC*);
STR_DSC* StrDscTailFrozen (STR_DSC*);
STR_DSC* StrDscText (REQUEST_STRUCT*, STR_DSC*, char*, int);
STR_DSC* StrDscThis (REQUEST_STRUCT*, STR_DSC*, char*, int);
StrDscWatchNotHeap (char*, int);
void StrDscZero (STR_DSC*);

#endif /* STRDSC_H_LOADED */

/*****************************************************************************/