The C Utility Toolkit

array.h

Go to the documentation of this file.

/*
** This file is part of the C Utility Toolkit (CUTK)
** Copyright (C) 2002-2005 Chris Osgood
** http://www.cutk.org
**
** This library is free software; you can redistribute it and/or
** modify it under the terms of the GNU Lesser General Public
** License as published by the Free Software Foundation; either
** version 2.1 of the License, or (at your option) any later version.
**
** This library is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
** Lesser General Public License for more details.
**
** You should have received a copy of the GNU Lesser General Public
** License along with this library; if not, write to the Free Software
** Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
**
** Please report all bugs and problems to "bugs at cutk.org".
*/

/*
** A fast dynamic C array implementation similar to STL vectors.  The main
** goals were to create a dynamic array system that feels much like normal C
** arrays and offers extremely high performance.
**
** The API is meant to be POSIX-like.  That is, lowercase function names and no
** underscores.
**
** Function reference:
**   aryalloc(type)          -- Allocates a new array of "type" elements.
**   aryallocsize(type, size)-- Allocates a new array of "type" elements with
**                              "size" initial elements.
**   aryappend(&array, &elem)-- Adds and copies new element to the end of the
**                              array.
**   arycat(&dest, &src)     -- Concatenates two arrays.
**   aryclear(&array)        -- Erases all elements in the array.  This does not
**                              free any memory. Use reserve() to free memory.
**   arycpy(&dest, &src)     -- Copies an array from src to dest.
**   arydup(&array)          -- Duplicates an array.
**   aryerase(&array, index) -- Removes element at "index."
**   aryfasterase(&array, index) -- Removes element at "index." by replacing it
**                                  with the last item in the array.
**   aryfree(&array)         -- Free an array.
**   aryinsert(&array, elem) -- Inserts a new element at position "index."
**   aryreserve(&array, max) -- Allocates memory for "max" elements but does not
**                              change the size of the array unless smaller.
**   aryresize(&array, size) -- Resizes the array to have "size" elements.
**   arysize(&array)         -- Number of elements in array.
**
** Note that all functions take a pointer to the array pointer as the first
** argument.  Keep in mind that the array pointer may change as memory is
** allocated or deallocated.  Otherwise it behaves similar to a normal array.
**
** Example usage (array of int's):
**
**   int *my_array;
**   my_array = aryalloc(int);
**   aryresize(&my_array, 1000);
**   my_array[0] = 1234;
**   my_array[999] = 1234;
**   array_size = arysize(&my_array);
**    ...
**   aryfree(&my_array);
**
** $Id: array.h 7 2005-01-02 01:02:22Z chris $
*/

#ifndef _ARRAY_H
#define _ARRAY_H

/* stdlib is needed for the size_t type */
#include <stdlib.h>

#ifdef __cplusplus
extern "C" {
#endif

/* Main array type (not used externally but arysize/max macros use it) */
typedef struct array_type
{
   size_t size;   /* Number of elements in array       */
   size_t max;    /* Allocated memory (max # elements) */
   size_t esize;  /* Element size; sizeof(ElementType) */
   char ary[];    /* Raw array data                    */
} array_type;

/* Note: aryalloc_ (with underscore) is an internal function, use aryalloc()
**       instead */
void* aryalloc_(size_t esize);
void* aryallocsize_(size_t esize, size_t size);

/* Macros for low overhead API calls */
#define arysize(x)         ((*((array_type**)(void*)(x))-1)->size)
#define arymax(x)          ((*((array_type**)(void*)(x))-1)->max)
#define aryalloc(x)        aryalloc_(sizeof(x))
#define aryallocsize(x,y)  aryallocsize_(sizeof(x),y)
#define aryclear(x)        (((*((array_type**)(void*)(x))-1)->size)=0)

void  aryfree(void* array);
 int  aryreserve(void* array, size_t max);
 int  aryresize(void* array, size_t size);
 int  aryappend(void* array, const void* element);
 int  aryinsert(void* array, size_t index);
 int  aryerase(void* array, size_t index);
 int  aryfasterase(void* array, size_t index);
void* arydup(const void* array);
 int  arycpy(void* dest, const void* src);
 int  arycat(void* dest, const void* src);

#ifdef __cplusplus
}
#endif

#endif /* _ARRAY_H */

---