/*
  This file is a "supermacro", intended to be included multiple times
  by related client code.

  Inputs:

  #define LIST_T list_type
  #define VALUE_T value_type
  #define VALUE_T_IS_PTR 1 // IF value_type is ptr-qualified
  #define LIST_DECLARE   // decls will be emitted.
  #define LIST_IMPLEMENT // impls will be emitted.

  VALUE_T_IS_PTR removes some routines, but is needed for handling
  (T**) lists propertly.

  list_type must be a struct with at least the following members:

  struct list_type {
  VALUE_T list; // or (VALUE_T*) if VALUE_T_IS_PTR
  cwal_size_t used; // number of used entries in the list
  cwal_size_t capacity; // number of items allocated in the list
  };

  Additional members are optional, and unused by this code.
  
  This file provides routines for (de)allocating, growing,
  visiting, and cleaning up list contents.

  The generated functions are named LIST_T_funcname(),
  e.g. list_type_reserve().
*/

#if !defined(VALUE_T_IS_PTR)
#  define VALUE_T_IS_PTR 0
#endif
#define SYM2(X,Y) X ## Y
#define SYM(X,Y) SYM2(X,Y)
#define STR2(T) # T
#define STR(T) STR2(T)

#if 0 && defined(LIST_IMPLEMENT)
#include <string.h> /* memset() */
#include <assert.h>
#endif

#ifdef LIST_DECLARE
/**
   Possibly reallocates self->list, changing its size. This function
   ensures that self->list has at least n entries. If n is 0 then
   the list is deallocated (but the self object is not), BUT THIS DOES NOT
   DO ANY TYPE-SPECIFIC CLEANUP of the items. If n is less than or equal
   to self->capacity then there are no side effects. If n is greater
   than self->capacity, self->list is reallocated and self->capacity
   is adjusted to be at least n (it might be bigger - this function may
   pre-allocate a larger value).

   Passing an n of 0 when self->capacity is 0 is a no-op.

   Newly-allocated items will be initialized with NUL bytes.
   
   Returns the total number of items allocated for self->list.  On
   success, the value will be equal to or greater than n (in the
   special case of n==0, 0 is returned). Thus a return value smaller
   than n is an error. Note that if n is 0 or self is NULL then 0 is
   returned.

   The return value should be used like this:

   @code
   cwal_size_t const n = number of bytes to allocate;
   if( n > my_list_t_reserve( myList, n ) ) { ... error ... }
   // Or the other way around:
   if( my_list_t_reserve( myList, n ) < n ) { ... error ... }
   @endcode
*/
cwal_size_t SYM(LIST_T,_reserve)( cwal_engine * e, LIST_T * self, cwal_size_t n );

/**
   Appends a bitwise copy of cp to self->list, expanding the list as
   necessary and adjusting self->used.

   Ownership of cp is unchanged by this call. cp may not be NULL.

   Returns 0 on success, CWAL_RC_MISUSE if any argument is NULL,
   or CWAL_RC_OOM on allocation error.
*/
int SYM(LIST_T,_append)( cwal_engine * e, LIST_T * self, VALUE_T cp );

/** @typedef typedef int (*LIST_TYPE_visitor_f)(void * p, void * visitorState )
   
   Generic visitor interface for cwal_list lists.  Used by
   LIST_TYPE_visit(). p is the pointer held by that list entry and
   visitorState is the 4th argument passed to cwal_list_visit().

   Implementations must return 0 on success. Any other value causes
   looping to stop and that value to be returned, but interpration of
   the value is up to the caller (it might or might not be an error,
   depending on the context). Note that client code may use custom
   values, and is not restricted to cwal_rc values.
*/

#if VALUE_T_IS_PTR
typedef int (*SYM(LIST_T,_visitor_f))(VALUE_T obj, void * visitorState );
#else
typedef int (*SYM(LIST_T,_visitor_f))(VALUE_T * obj, void * visitorState );
#endif

/**
   For each item in self->list, visitor(item,visitorState) is called.
   The item is owned by self. The visitor function MUST NOT free the
   item, but may manipulate its contents if application rules do not
   specify otherwise.

   If order is 0 or greater then the list is traversed from start to
   finish, else it is traverse from end to begin.

   Returns 0 on success, non-0 on error.

   If visitor() returns non-0 then looping stops and that code is
   returned.
*/
int SYM(LIST_T,_visit)( LIST_T * self, char order,
                        SYM(LIST_T,_visitor_f) visitor, void * visitorState );
#if VALUE_T_IS_PTR
/**
   Works similarly to the visit operation without the _p suffix except
   that the pointer the visitor function gets is a (**) pointing back
   to the entry within this list. That means that callers can assign
   the entry in the list to another value during the traversal process
   (e.g. set it to 0). If shiftIfNulled is true then if the callback
   sets the list's value to 0 then it is removed from the list and
   self->used is adjusted (self->capacity is not changed).
*/
int SYM(LIST_T,_visit_p)( LIST_T * self, char order, char shiftIfNulled,
                          SYM(LIST_T,_visitor_f) visitor, void * visitorState );
#endif

#endif
/* LIST_DECLARE */


#ifdef LIST_IMPLEMENT

cwal_size_t SYM(LIST_T,_reserve)( cwal_engine * e, LIST_T * self, cwal_size_t n )
{
    if( !self ) return 0;
    else if(0 == n)
    {
        if(0 == self->capacity) return 0;
        cwal_free(e, self->list);
        self->list = NULL;
        self->capacity = self->used = 0;
        return 0;
    }
    else if( self->capacity >= n )
    {
        return self->capacity;
    }
    else
    {
        size_t const sz = sizeof(VALUE_T) * n;
        VALUE_T * m = (VALUE_T*)cwal_realloc( e, self->list, sz );
        if( ! m ) return self->capacity;
        /* Zero out the new elements... */
        memset( m + self->capacity, 0, (sizeof(VALUE_T)*(n-self->capacity)));
        self->capacity = n;
        self->list = m;
        return n;
    }
}

int SYM(LIST_T,_append)( cwal_engine * e, LIST_T * self, VALUE_T cp )
{
    if( !e || !self || !cp ) return CWAL_RC_MISUSE;
    else if( self->capacity > SYM(LIST_T,_reserve)(e, self, self->used+1) )
    {
        return CWAL_RC_OOM;
    }
    else
    {
        self->list[self->used++] = cp;
#if VALUE_T_IS_PTR
        if(self->used< self->capacity-1) self->list[self->used]=0;
#endif
        return 0;
    }
}

int SYM(LIST_T,_visit)( LIST_T * self, char order,
                        SYM(LIST_T,_visitor_f) visitor, void * visitorState )
{
    int rc = CWAL_RC_OK;
    if( self && self->used && visitor )
    {
        int i = 0;
        int pos = (order<0) ? self->used-1 : 0;
        int step = (order<0) ? -1 : 1;
        for( rc = 0; (i < self->used) && (0 == rc); ++i, pos+=step )
        {
#if VALUE_T_IS_PTR
            VALUE_T obj = self->list[pos];
#else
            VALUE_T * obj = &self->list[pos];
#endif
            if(obj) rc = visitor( obj, visitorState );
#if VALUE_T_IS_PTR
            /* cwal-specific hack b/c obj can be removed during traversal... */
            if( obj != self->list[pos] ){
                --i;
                if(order>=0) pos -= step;
            }
#endif

        }
    }
    return rc;
}

#if VALUE_T_IS_PTR
int SYM(LIST_T,_visit_p)( LIST_T * self, char order,
                          char shiftIfNulled,
                          SYM(LIST_T,_visitor_f) visitor, void * visitorState )
{
    int rc = CWAL_RC_OK;
    if( self && self->used && visitor )
    {
        int i = 0;
        int pos = (order<0) ? self->used-1 : 0;
        int step = (order<0) ? -1 : 1;
        for( rc = 0; (i < (int)self->used) && (0 == rc); ++i, pos+=step )
        {
            VALUE_T obj = self->list[pos];
            if(obj) {
                assert((order<0) && "TEST THAT THIS WORKS WITH IN-ORDER!");
                rc = visitor( &self->list[pos], visitorState );
                if( shiftIfNulled && !self->list[pos]){
                    int x = pos;
                    int const to = self->used-pos;
                    /*MARKER("i=%d pos=%d x=%d to=%d\n",i, pos, x, to);*/
                    assert( to < (int) self->capacity );
                    for( ; x < to; ++x ) self->list[x] = self->list[x+1];
                    if( x < (int)self->capacity ) self->list[x] = 0;
                    --i;
                    --self->used;
                    if(order>=0) pos -= step;
                }
            }
        }
    }
    return rc;
}
#endif


#if !VALUE_T_IS_PTR
/**
   Reduces self->used by 1. Returns 0 on success.
   Errors include:

   (!self) or (0 == self->used)
*/
int SYM(LIST_T,_pop_back)( cwal_engine * e, LIST_T * self, void (*cleaner)(VALUE_T * obj) )
{
    if( !self ) return CWAL_RC_MISUSE;
    else if( ! self->used ) return cson_rc.RangeError;
    else
    {
        cwal_size_t const ndx = --self->used;
        VALUE_T * val = &self->list[ndx];
        if(val && cleaner) cleaner(val);
        return 0;
    }
}
#endif

#endif
/* LIST_IMPLEMENT */

#undef LIST_IMPLEMENT
#undef LIST_DECLARE
#undef SYM
#undef SYM2
#undef LIST_T
#undef VALUE_T
#undef VALUE_T_IS_PTR
#undef STR
#undef STR2