vector.h

/* ============================================================================
 * Freetype GL - A C OpenGL Freetype engine
 * Platform:    Any
 * WWW:         http://code.google.com/p/freetype-gl/
 * ----------------------------------------------------------------------------
 * Copyright 2011,2012 Nicolas P. Rougier. All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 *  1. Redistributions of source code must retain the above copyright notice,
 *     this list of conditions and the following disclaimer.
 *
 *  2. Redistributions in binary form must reproduce the above copyright
 *     notice, this list of conditions and the following disclaimer in the
 *     documentation and/or other materials provided with the distribution.
 *
 * THIS SOFTWARE IS PROVIDED BY NICOLAS P. ROUGIER ''AS IS'' AND ANY EXPRESS OR
 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
 * EVENT SHALL NICOLAS P. ROUGIER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
 * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 * The views and conclusions contained in the software and documentation are
 * those of the authors and should not be interpreted as representing official
 * policies, either expressed or implied, of Nicolas P. Rougier.
 * ============================================================================
 */
#ifndef __VECTOR_H__
#define __VECTOR_H__

#include <stdlib.h>

#ifdef __cplusplus
extern "C" {
#endif

#include <stddef.h>

/**
 * @file   vector.h
 * @author Nicolas Rougier (Nicolas.Rougier@inria.fr)
 *
 * @defgroup vector Vector
 *
 * The vector structure and accompanying functions loosely mimic the STL C++
 * vector class. It is used by @ref texture-atlas (for storing nodes), @ref
 * texture-font (for storing glyphs) and @ref font-manager (for storing fonts).
 * More information at http://www.cppreference.com/wiki/container/vector/start
 *
 * <b>Example Usage</b>:
 * @code
 * #include "vector.h"
 *
 * int main( int arrgc, char *argv[] )
 * {
 *   int i,j = 1;
 *   vector_t * vector = vector_new( sizeof(int) );
 *   vector_push_back( &i );
 * 
 *   j = * (int *) vector_get( vector, 0 );
 *   vector_delete( vector);
 *
 *   return 0;
 * }
 * @endcode
 *
 * @{
 */

/**
 *  Generic vector structure.
 *
 * @memberof vector
 */
typedef struct vector_t
 {
     /** Pointer to dynamically allocated items. */
     void * items;

     /** Number of items that can be held in currently allocated storage. */
     size_t capacity;

     /** Number of items. */
     size_t size;

     /** Size (in bytes) of a single item. */
     size_t item_size;
} vector_t;


/**
 * Creates a new empty vector.
 *
 * @param   item_size    item size in bytes
 * @return               a new empty vector
 *
 */
  vector_t *
  vector_new( size_t item_size );


/**
 *  Deletes a vector.
 *
 *  @param self a vector structure
 *
 */
  void
  vector_delete( vector_t *self );


/**
 *  Returns a pointer to the item located at specified index.
 *
 *  @param  self  a vector structure
 *  @param  index the index of the item to be returned
 *  @return       pointer on the specified item
 */
  const void *
  vector_get( const vector_t *self,
              size_t index );


/**
 *  Returns a pointer to the first item.
 *
 *  @param  self  a vector structure
 *  @return       pointer on the first item
 */
  const void *
  vector_front( const vector_t *self );


/**
 *  Returns a pointer to the last item
 *
 *  @param  self  a vector structure
 *  @return pointer on the last item
 */
  const void *
  vector_back( const vector_t *self );


/**
 *  Check if an item is contained within the vector.
 *
 *  @param  self  a vector structure
 *  @param  item  item to be searched in the vector
 *  @param  cmp   a pointer a comparison function
 *  @return       1 if item is contained within the vector, 0 otherwise
 */
  int
  vector_contains( const vector_t *self,
                   const void *item,
                   int (*cmp)(const void *, const void *) );


/**
 *  Checks whether the vector is empty.
 *
 *  @param  self  a vector structure
 *  @return       1 if the vector is empty, 0 otherwise
 */
  int
  vector_empty( const vector_t *self );


/**
 *  Returns the number of items
 *
 *  @param  self  a vector structure
 *  @return       number of items
 */
  size_t
  vector_size( const vector_t *self );


/**
 *  Reserve storage such that it can hold at last size items.
 *
 *  @param  self  a vector structure
 *  @param  size  the new storage capacity
 */
  void
  vector_reserve( vector_t *self,
                  const size_t size );


/**
 *  Returns current storage capacity
 *
 *  @param  self  a vector structure
 *  @return       storage capacity
 */
  size_t
  vector_capacity( const vector_t *self );


/**
 *  Decrease capacity to fit actual size.
 *
 *  @param  self  a vector structure
 */
  void
  vector_shrink( vector_t *self );


/**
 *  Removes all items.
 *
 *  @param  self  a vector structure
 */
  void
  vector_clear( vector_t *self );


/**
 *  Replace an item.
 *
 *  @param  self  a vector structure
 *  @param  index the index of the item to be replaced
 *  @param  item  the new item
 */
  void
  vector_set( vector_t *self,
              const size_t index,
              const void *item );


/**
 *  Erase an item.
 *
 *  @param  self  a vector structure
 *  @param  index the index of the item to be erased
 */
  void
  vector_erase( vector_t *self,
                const size_t index );


/**
 *  Erase a range of items.
 *
 *  @param  self  a vector structure
 *  @param  first the index of the first item to be erased
 *  @param  last  the index of the last item to be erased
 */
  void
  vector_erase_range( vector_t *self,
                      const size_t first,
                      const size_t last );


/**
 *  Appends given item to the end of the vector.
 *
 *  @param  self a vector structure
 *  @param  item the item to be inserted
 */
  void
  vector_push_back( vector_t *self,
                    const void *item );


/**
 *  Removes the last item of the vector.
 *
 *  @param  self a vector structure
 */
  void
  vector_pop_back( vector_t *self );


/**
 *  Resizes the vector to contain size items
 *
 *  If the current size is less than size, additional items are appended and
 *  initialized with value. If the current size is greater than size, the
 *  vector is reduced to its first size elements.
 *
 *  @param  self a vector structure
 *  @param  size the new size
 */
  void
  vector_resize( vector_t *self,
                 const size_t size );


/**
 *  Insert a single item at specified index.
 *
 *  @param  self  a vector structure
 *  @param  index location before which to insert item
 *  @param  item  the item to be inserted
 */
  void
  vector_insert( vector_t *self,
                 const size_t index,
                 const void *item );


/**
 *  Insert raw data at specified index.
 *
 *  @param  self  a vector structure
 *  @param  index location before which to insert item
 *  @param  data  a pointer to the items to be inserted
 *  @param  count the number of items to be inserted
 */
  void
  vector_insert_data( vector_t *self,
                      const size_t index,
                      const void * data,
                      const size_t count );


/**
 *  Append raw data to the end of the vector.
 *
 *  @param  self  a vector structure
 *  @param  data  a pointer to the items to be inserted
 *  @param  count the number of items to be inserted
 */
  void
  vector_push_back_data( vector_t *self,
                         const void * data, 
                         const size_t count );


/**
 *  Sort vector items according to cmp function.
 *
 *  @param  self  a vector structure
 *  @param  cmp   a pointer a comparison function
 */
  void
  vector_sort( vector_t *self,
               int (*cmp)(const void *, const void *) );


/** @} */

#ifdef __cplusplus
}
#endif

#endif /* __VECTOR_H__ */