Array iterators

Collaboration diagram for Array iterators:

Data Structures
struct	_amxc_array_it
	The array iterator structure. More...

Typedefs
typedef struct _amxc_array_it	amxc_array_it_t
	The array iterator structure. More...
typedef int(*	amxc_array_it_cmp_t) (amxc_array_it_t *it1, amxc_array_it_t *it2)
	Type definition of an array iterator compare callback function. More...

Functions
amxc_array_it_t *	amxc_array_it_get_next (const amxc_array_it_t *const reference)
	Gets the next used item in the array, starting from the provided array iterator. More...
amxc_array_it_t *	amxc_array_it_get_next_free (const amxc_array_it_t *const reference)
	Gets the next free item in the array, starting from the provided array iterator. More...
amxc_array_it_t *	amxc_array_it_get_previous (const amxc_array_it_t *const reference)
	Gets the previous used item in the array, starting from the provided array iterator. More...
amxc_array_it_t *	amxc_array_it_get_previous_free (const amxc_array_it_t *const reference)
	Gets the previous free item in the array, starting from the provided array iterator. More...
unsigned int	amxc_array_it_index (const amxc_array_it_t *const it)
	Gets the index of the iterator in the array. More...
AMXC_INLINE void *	amxc_array_it_get_data (const amxc_array_it_t *const it)
	Gets the data pointer of array iterator. More...
int	amxc_array_it_set_data (amxc_array_it_t *const it, void *data)
	Sets the data pointer of an array iterator. More...
void *	amxc_array_it_take_data (amxc_array_it_t *const it)
	Gets and removes a data pointer from the iterator. More...
int	amxc_array_it_swap (amxc_array_it_t *const it1, amxc_array_it_t *const it2)
	Swaps the content of the two array iterators. More...

Detailed Description

Typedef Documentation

amxc_array_it_cmp_t

typedef int(* amxc_array_it_cmp_t) (amxc_array_it_t *it1, amxc_array_it_t *it2)

Type definition of an array iterator compare callback function.

When sorting an array, the items in the array (iterators) must be compared. When calling amxc_array_sort a compare function must be provided using this signature.

Parameters

it1	the first array iterator
it2	the second array iterator

Returns

The callback function must return

• 0 when the values are equal
• < 0 when it1 is smaller then it2
• > 0 when it1 is bigger then it2

Definition at line 213 of file amxc_array.h.

amxc_array_it_t

typedef struct _amxc_array_it amxc_array_it_t

The array iterator structure.

Function Documentation

amxc_array_it_get_data()

AMXC_INLINE void* amxc_array_it_get_data

(

const amxc_array_it_t *const

it

)

Gets the data pointer of array iterator.

Parameters

it	pointer to the item iterator

Returns

returns the data pointer of iterator or NULL if no data pointer was stored in that iterator.

Definition at line 729 of file amxc_array.h.

                                                              {
    return (it != NULL) ? it->data : NULL;
}

amxc_array_it_get_next()

amxc_array_it_t* amxc_array_it_get_next

(

const amxc_array_it_t *const

reference

)

Gets the next used item in the array, starting from the provided array iterator.

This function iterates forwards over all items starting from the reference iterator and searches the next used item.

Parameters

reference

array iterator used as starting point.

Returns

returns the iterator of the next used item in the array starting from the reference iterator, or NULL if there are no more used items (End of array reached).

Definition at line 66 of file amxc_array_it.c.

                                                                                {
    amxc_array_it_t* it = NULL;
    amxc_array_t* array = NULL;
    size_t pos = 0;
    when_null(reference, exit);
 
    array = reference->array;
    pos = (reference - array->buffer);
    pos++;
    while(pos < array->items && !array->buffer[pos].data) {
        pos++;
    }
 
    if(pos < array->items) {
        it = &array->buffer[pos];
    }
 
exit:
    return it;
}

amxc_array_it_get_next_free()

amxc_array_it_t* amxc_array_it_get_next_free

(

const amxc_array_it_t *const

reference

)

Gets the next free item in the array, starting from the provided array iterator.

This function iterates forwards over all items starting from the reference iterator and searches the next free item.

Parameters

reference

array iterator used as starting point.

Returns

returns the iterator of the next free item in the array starting from the reference iterator, or NULL if there are no more free items (End of array reached).

Definition at line 87 of file amxc_array_it.c.

                                                                                     {
    amxc_array_it_t* it = NULL;
    amxc_array_t* array = NULL;
    size_t pos = 0;
    when_null(reference, exit);
 
    array = reference->array;
    pos = (reference - array->buffer);
    pos++;
    while(pos < array->items && array->buffer[pos].data != NULL) {
        pos++;
    }
 
    if(pos < array->items) {
        it = &array->buffer[pos];
    }
 
exit:
    return it;
}

amxc_array_it_get_previous()

amxc_array_it_t* amxc_array_it_get_previous

(

const amxc_array_it_t *const

reference

)

Gets the previous used item in the array, starting from the provided array iterator.

This function iterates backwards over all items starting from the reference iterator and searches the previous used item.

Parameters

reference

array iterator used as starting point.

Returns

returns the iterator of the previous used item in the array starting from the reference iterator, or NULL if there are no more used items (Start of array reached).

Definition at line 108 of file amxc_array_it.c.

                                                                                    {
    amxc_array_it_t* it = NULL;
    amxc_array_t* array = NULL;
    size_t pos = 0;
    when_null(reference, exit);
 
    array = reference->array;
    pos = (reference - array->buffer);
    while(pos > 0 && !array->buffer[pos - 1].data) {
        pos--;
    }
 
    if(pos > 0) {
        it = &array->buffer[pos - 1];
    }
 
exit:
    return it;
}

amxc_array_it_get_previous_free()

amxc_array_it_t* amxc_array_it_get_previous_free

(

const amxc_array_it_t *const

reference

)

Gets the previous free item in the array, starting from the provided array iterator.

This function iterates backwards over all items starting from the reference iterator and searches the previous free item.

Parameters

reference

array iterator used as starting point.

Returns

returns the iterator of the previous free item in the array starting from the reference iterator, or NULL if there are no more free items (Start of array reached).

Definition at line 128 of file amxc_array_it.c.

                                                                                         {
    amxc_array_it_t* it = NULL;
    amxc_array_t* array = NULL;
    size_t pos = 0;
    when_null(reference, exit);
 
    array = reference->array;
    pos = (reference - array->buffer);
    while(pos > 0 && array->buffer[pos - 1].data != NULL) {
        pos--;
    }
 
    if((pos > 0) && !array->buffer[pos - 1].data) {
        it = &array->buffer[pos - 1];
    }
 
exit:
    return it;
}

amxc_array_it_index()

unsigned int amxc_array_it_index

(

const amxc_array_it_t *const

it

)

Gets the index of the iterator in the array.

Parameters

it	pointer to the array iterator.

Returns

returns the index of the iterator.

Definition at line 148 of file amxc_array_it.c.

                                                                  {
    size_t index = 0;
    when_null(it, exit);
 
    index = it - it->array->buffer;
 
exit:
    return index;
}

amxc_array_it_set_data()

int amxc_array_it_set_data	(	amxc_array_it_t *const	it,
		void *	data
	)

Sets the data pointer of an array iterator.

Note

This function sets the pointer in the array. It is important that the pointer is valid as long as it is used in the array. Before freeing the memory block, remove the pointer from the array.

Parameters

it	pointer to the item iterator
data	pointer to the data

Returns

0 when the data is set, -1 otherwise.

Definition at line 158 of file amxc_array_it.c.

                                                                  {
    int retval = -1;
    unsigned int index = 0;
    amxc_array_t* array = NULL;
 
    when_null(it, exit);
    when_null(data, exit);
 
    index = amxc_array_it_index(it);
    array = it->array;
    it->data = data;
    if((index < array->first_used) ||
       ((array->first_used == 0) && (array->buffer[0].data == NULL))) {
        array->first_used = index;
    }
    if(index > array->last_used) {
        array->last_used = index;
    }
 
    retval = 0;
 
exit:
    return retval;
}

amxc_array_it_swap()

int amxc_array_it_swap	(	amxc_array_it_t *const	it1,
		amxc_array_it_t *const	it2
	)

Swaps the content of the two array iterators.

The array iterators do not have to belong to the same array.

Parameters

it1	pointer to the item iterator 1
it2	pointer to the item iterator 2

Returns

0 when the iterators are swapped. TODO -1 if swapping fails.

Definition at line 218 of file amxc_array_it.c.

                                                   {
    int retval = -1;
    void* data = NULL;
 
    when_null(it1, exit);
    when_null(it2, exit);
 
    data = it1->data;
    it1->data = it2->data;
    it2->data = data;
 
exit:
    return retval;
}

amxc_array_it_take_data()

void* amxc_array_it_take_data

(

amxc_array_it_t *const

it

)

Gets and removes a data pointer from the iterator.

This functions resets the data pointer of the iterator back to NULL.

Parameters

it	pointer to the item iterator

Returns

The data pointer of the iterator.

Definition at line 183 of file amxc_array_it.c.

                                                   {
    void* data = NULL;
    unsigned int index = 0;
    amxc_array_t* array = NULL;
 
    when_null(it, exit);
    when_null(it->data, exit);
 
    index = amxc_array_it_index(it);
    array = it->array;
 
    data = it->data;
    it->data = NULL;
 
    if(index == array->first_used) {
        it = amxc_array_it_get_next(it);
        if(it == NULL) {
            array->first_used = 0;
        } else {
            array->first_used = amxc_array_it_index(it);
        }
    }
    if(index == array->last_used) {
        it = amxc_array_it_get_previous(it);
        if(it == NULL) {
            array->last_used = 0;
        } else {
            array->last_used = amxc_array_it_index(it);
        }
    }
 
exit:
    return data;
}