libEtPan! API
Prev |  | Next

# Chapter 2. Tools and datatypes

libEtPan! include a collection of datatypes such as lists, arrays, hash tables and tools such as buffered I/O.

# Array

    #include <libetpan/libetpan.h>

    typedef struct carray_s carray;

carray is an array of pointers that will resize automatically in case a new element is added.

The carray is implemented with an array (void **) that can be resized. An array has a size: this is the number of elements that can be added before the table is resized. It also has a count of elements: this is the elements that exist in the array.

## carray_new and carray_free

    carray * carray_new(unsigned int initsize);

    void carray_free(carray * array);

carray_new() creates a new array with an initial size. The array is not resized until the number of element reach the initial size. It returns NULL in case of failure.

carray_free() releases memory used by the given array.

Example 2-1. carray creation

    #include <libetpan/libetpan.h>
    #include <stdlib.h>

    #define SIZE 50

    int main(void)
    {
      carray * a;

      a = carray_new(SIZE);
      if (a == NULL)
        exit(EXIT_FAILURE);

      /* do things here */

      carray_free(a);

      exit(EXIT_SUCESS);
    }

## carray_set_size

    int carray_set_size(carray * array, uint32_t new_size);

carray_set_size() sets the size of the array. It returns 0 in case of success, -1 in case of failure.

Example 2-2. preallocating carray

    #include <libetpan/libetpan.h>
    #include <stdlib.h>

    #define SIZE 50
    #define NEWSIZE 200

    int main(void)
    {
      carray * a;
      unsigned int i;
      char p[500];

      a = carray_new(SIZE);
      if (a == NULL)
        goto err;

      r = carray_set_size(NEWSIZE);
      if (r < 0)
        goto free;

      for(i = 0 ; i < NEWSIZE ; i ++)
        carray_set(a, i, &p[i]);

      /* do things here */

      carray_free(a);

      exit(EXIT_SUCESS);

     free:
      carray_free(a);
     err:
      exit(EXIT_FAILURE);
    }

## carray_count, carray_add, carray_get and carray_set

    int carray_count(carray);

    int carray_add(carray * array, void * data, unsigned int * index);

    void * carray_get(carray * array, unsigned int indx);

    void carray_set(carray * array, unsigned int indx, void * value);

carray_count() returns the number of elements in the carray. Complexity is O(1).

carray_add()adds an element at the end of the array. The index of the element is returns in (* index) if index is not NULL. It returns 0 in case of success, -1 in case of failure. Complexity is O(1).

carray_get() returns the elements contained at the given cell of the table. Complexity is O(1).

carray_set() replace the element at the given index of table table with the given value. Complexity is O(1).

Example 2-3. carray access

    #include <libetpan/libetpan.h>
    #include <string.h>

    #define SIZE 50

    int main(void)
    {
      carray * a;
      int r;

      a = carray_new(SIZE);
      if (a == NULL)
        goto err;

      r = carray_add(a, "foo-bar-1", NULL);
      if (r < 0)
        goto free;

      carray_add(a, "foo-bar-2", NULL);
      if (r < 0)
        goto free;

      carray_add(a, "foo-bar-3", NULL);
      if (r < 0)
        goto free;

      for(i = 0 ; i < carray_count(a) ; i ++) {
        char * str;

        str = carray_get(a, i);
        if (strcmp("foo-bar-2", str) == 0)
          carray_set(a, i, "foo-bar-2-replacement");

        printf("%s\n", str);
      }

      carray_free(a);

      exit(EXIT_SUCESS);

     free:
      carray_free(a);
     err:
      exit(EXIT_FAILURE);
    }

## carray_delete

    int carray_delete(carray * array, uint32_t indx);

    int carray_delete_slow(carray * array, uint32_t indx);

    int carray_delete_fast(carray * array, uint32_t indx);

carray_delete() removes an element of the table. Order will not be garanteed. The returned result can be ignored. Complexity is O(1).

carray_delete_slow() removes an element of the table. Order will be garanteed. The returned result can be ignored. Complexity is O(n).

carray_delete_fast() the element will just be replaced with NULL. Order will be kept but the number of elements will remains the same. The returned result can be ignored. Complexity is O(1).

Example 2-4. deletion in carray

    #include <libetpan/libetpan.h>

    #define SIZE 50

    carray * build_array(void)
    {
      carray * a;

      a = carray_new(SIZE);
      if (a == NULL)
        goto err;

      r = carray_add(a, "foo-bar-1", NULL);
      if (r < 0)
        goto free;

      carray_add(a, "foo-bar-2", NULL);
      if (r < 0)
        goto free;

      carray_add(a, "foo-bar-3", NULL);
      if (r < 0)
        goto free;

      return a;

     free:
      carray_free(a);
     err:
      exit(EXIT_FAILURE);
    }

    void delete(carray * a)
    {
      /* deleting foo-bar-1 */
      carray_delete(a, 0);
      /* resulting size is 2, order of elements is undefined */
    }

    void delete_slow(carray * a)
    {
      /* deleting foo-bar-1 */
      carray_delete_slow(a, 0);
      /* resulting size is 2, order of elements is the same */
    }

    void delete_fast(carray * a)
    {
      /* deleting foo-bar-1 */
      carray_delete_slow(a, 0);
      /*
         resulting size is 3,
         order of elements is { NULL, foo-bar-2, foo-bar-3 }
      */
    }

## carray_data

    void ** carray_data(carray);

carray_datareturns the table used for implementation : (void **).

Prev | Home | Next
Introduction |  | List