/simpletypesystem/trunk

#ifndef _H_RING_BUFFER_

#define _H_RING_BUFFER_

#include "defs.h"

#include "Func.h"

S_BEGIN_DECLS

/**

 * @file

 * @defgroup SRingBuffer SRingBuffer

 * @addtogroup SRingBuffer

 * @{

 * An SRingBuffer is a special data structure that is circular in nature.

 * It only holds bytes and as such is useful when dealing with strings and

 * other eight-bit data.

 *

 * If you are looking for a circular array, this is not

 * such a structure.

 *

 * @section Theory

 * The theory behind a circular structure is simple: Never have to deal with

 * empty slots in an array, only permit indirect, non-indexed access.

 *

 <pre>

    [b|b|b|b|b|b|b|b|b|b| | | | ]

     ^                 ^

     start             end

     front             back

    [ | | | | | |b|b|b|b| | | | ]

                 ^     ^

             start     end

             front     back

    [b|b| | | | | | | |b|b|b|b|b]

       ^               ^

     end             start

     back            front

 </pre>

 */

/**

 * The SRingBuffer is an opaque data structure that represent an array that

 * is circular in nature.

 */

typedef struct SRingBuffer SRingBuffer;

/**

 * Create a new SRingBuffer objects.

 *

 * @param len The number of items to 

 */

SRingBuffer *

s_ring_buffer_new (size_t len);

/**

 * Free an SRingBuffer.

 *

 * @param self The SRingBuffer to free.

 */

void

s_ring_buffer_free (SRingBuffer * self);

/**

 * determine 

 */

sboolean

s_ring_buffer_is_empty (SRingBuffer * self);

/**

 * Add data to the front of the ringbuffer.

 * 

 */

void

s_ring_buffer_push (SRingBuffer * self,

                    sbyte data);

/**

 * add an item to the back of the ringbuffer.

 */

void

s_ring_buffer_push_back (SRingBuffer * self,

                         sbyte data);

/**

 * Pop an item from the front of the array.

 */

sbyte

s_ring_buffer_pop (SRingBuffer * self);

/**

 * Pop the back of the array.

 */

sbyte

s_ring_buffer_pop_back (SRingBuffer * self);

/**

 * Reallocate an SRingBuffer to a now size for the internal array.

 *

 * @param self The SRingBuffer to reallocate.

 * @param len The new length.

 */

void

s_ring_buffer_realloc (SRingBuffer * self,

                       size_t len);

/**

 * Get the current length of the ring buffer.

 */

size_t

s_ring_buffer_len (SRingBuffer * self);

/**

 * Get the total size of the internal array.

 */

size_t

s_ring_buffer_size (SRingBuffer * self);

/**

 * Iterate over the bytes in the SRingBuffer.

 *

 * This is the only valid way to iterate over the bytes in an SRingBuffer.

 *

 * @param self The SRingBuffer to iterate over.

 * @param func Pointer to a function that is run on each byte.

 * @param user_data Data that is provided to the function when doing the

 *                  iteration.

 *

 * @note

 * This does not use pop or push operations, and is thus the only way to keep

 * the data and still be able to iterate over it.

 *

 * The signature of the function provided should be as follows

 @code{C}

void

my_for_each_func (SRingBuffer * buffer,

                  sbyte item,

                  spointer user_data) {

  // code here

}

 @endcode

 *

 * To prevent warnings cast the function using the @c FOREACHFUNC() macro.

 */

void

s_ring_buffer_for_each (SRingBuffer * self,

                        ForEachFunc func,

                        spointer user_data);

/**

 * @}

 */

S_END_DECLS

#endif /* _H_RING_BUFFER_ */