Linked List Iterator

Collaboration diagram for Linked List Iterator:

Data Structures
struct	_amxc_llist_it
	The linked list iterator structure. More...

Macros
#define	amxc_llist_it_get_data(it, type, member)    amxc_container_of(it, type, member)
	Gets the data pointer from a linked list iterator. More...

Typedefs
typedef struct _amxc_llist_it	amxc_llist_it_t
	The linked list iterator structure. More...
typedef int(*	amxc_llist_it_cmp_t) (amxc_llist_it_t *it1, amxc_llist_it_t *it2)
	Type definition of a linked list iterator compare callback function. More...

Functions
int	amxc_llist_it_init (amxc_llist_it_t *const it)
	Initializes a linked list iterator. More...
void	amxc_llist_it_clean (amxc_llist_it_t *const it, amxc_llist_it_delete_t func)
	Removes the iterator from the list and frees allocated memory. More...
void	amxc_llist_it_take (amxc_llist_it_t *const it)
	Removes the iterator from the list. More...
int	amxc_llist_it_insert_before (amxc_llist_it_t *const reference, amxc_llist_it_t *const it)
	Inserts an iterator before a reference interator in the list. More...
int	amxc_llist_it_insert_after (amxc_llist_it_t *const reference, amxc_llist_it_t *const it)
	Inserts an iterator after another reference interator in the list. More...
unsigned int	amxc_llist_it_index_of (const amxc_llist_it_t *const it)
	Gets the index of an iterator in the list. More...
int	amxc_llist_it_swap (amxc_llist_it_t *it1, amxc_llist_it_t *it2)
	Swaps two linked list iterators. More...
AMXC_INLINE amxc_llist_it_t *	amxc_llist_it_get_next (const amxc_llist_it_t *const reference)
	Gets the next iterator in the list. More...
AMXC_INLINE amxc_llist_it_t *	amxc_llist_it_get_previous (const amxc_llist_it_t *const reference)
	Gets the previous iterator in the list. More...
AMXC_INLINE bool	amxc_llist_it_is_in_list (const amxc_llist_it_t *const it)
	Checks that an iterator is in a list. More...

Detailed Description

Macro Definition Documentation

amxc_llist_it_get_data

#define amxc_llist_it_get_data	(		it,
			type,
			member
	)		amxc_container_of(it, type, member)

Gets the data pointer from a linked list iterator.

Definition at line 238 of file amxc_llist.h.

Typedef Documentation

amxc_llist_it_cmp_t

typedef int(* amxc_llist_it_cmp_t) (amxc_llist_it_t *it1, amxc_llist_it_t *it2)

Type definition of a linked list iterator compare callback function.

When sorting a linked list, the items in the list (iterators) must be compared. When calling amxc_llist_sort a compare function must be provided using this signature.

Parameters

it1	the first linked list iterator
it2	the second linked list 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 336 of file amxc_llist.h.

amxc_llist_it_t

typedef struct _amxc_llist_it amxc_llist_it_t

The linked list iterator structure.

Function Documentation

amxc_llist_it_clean()

void amxc_llist_it_clean	(	amxc_llist_it_t *const	it,
		amxc_llist_it_delete_t	func
	)

Removes the iterator from the list and frees allocated memory.

If the iterator is in a list, it is removed from the list, when a delete function is provided, it is called to free up the memory.

Note

This function is not freeing the memory taken by the iterator, it uses a callback function for this.

Parameters

it	a pointer to the linked list iterator structure
func	a pointer to a function that is called to free the linked list item

Definition at line 103 of file amxc_llist_it.c.

                                                                                 {
    amxc_llist_it_take(it);
    if((it != NULL) && (func != NULL)) {
        func(it);
    }
}

amxc_llist_it_get_next()

AMXC_INLINE amxc_llist_it_t* amxc_llist_it_get_next

(

const amxc_llist_it_t *const

reference

)

Gets the next iterator in the list.

This function does not remove the item from the linked list.

Parameters

reference

a pointer to the linked list structure used as reference

Returns

Returns the next iterator of the linked list, or NULL when there is not more item in the linked list.

Definition at line 824 of file amxc_llist.h.

                                                                                {
    return reference != NULL ? reference->next : NULL;
}

amxc_llist_it_get_previous()

AMXC_INLINE amxc_llist_it_t* amxc_llist_it_get_previous

(

const amxc_llist_it_t *const

reference

)

Gets the previous iterator in the list.

This function does not remove the item from the linked list.

Parameters

reference

a pointer to the linked list structure used as reference

Returns

Returns the previous iterator of the linked list, or NULL when there is no more items in the linked list.

Definition at line 842 of file amxc_llist.h.

                                                                                    {
    return reference != NULL ? reference->prev : NULL;
}

amxc_llist_it_index_of()

unsigned int amxc_llist_it_index_of

(

const amxc_llist_it_t *const

it

)

Gets the index of an iterator in the list.

Parameters

it	a pointer to the linked list iterator structure for which the index needs to be calculated

Returns

The index of the iterator or AMXC_LLIST_RANGE if the iterator is not in a list.

Definition at line 182 of file amxc_llist_it.c.

                                                                     {
    size_t index = 0;
    const amxc_llist_it_t* pos = NULL;
    if((it == NULL) || (it->llist == NULL)) {
        index = AMXC_LLIST_RANGE;
        goto exit;
    }
 
    pos = it;
    while(pos->prev) {
        index++;
        pos = pos->prev;
    }
 
exit:
    return index;
}

amxc_llist_it_init()

int amxc_llist_it_init

(

amxc_llist_it_t *const

it

)

Initializes a linked list iterator.

Initializes the linked list iterator structure. All pointers are reset to NULL.

Note

When calling this function on an already initialized linked list iterator, the linked list iterator is reset and the list the iterator was in is corrupted. Use amxc_llist_it_take to remove the iterator from the list or amxc_llist_it_clean to remove it from the list and clean up the iterator

Parameters

it	a pointer to the linked list iterator structure.

Returns

0 on success. -1 if a NULL pointer is given.

Definition at line 89 of file amxc_llist_it.c.

                                                  {
    int retval = -1;
    when_null(it, exit);
 
    it->next = NULL;
    it->prev = NULL;
    it->llist = NULL;
 
    retval = 0;
 
exit:
    return retval;
}

amxc_llist_it_insert_after()

int amxc_llist_it_insert_after	(	amxc_llist_it_t *const	reference,
		amxc_llist_it_t *const	it
	)

Inserts an iterator after another reference interator in the list.

If the iterator(it) is already in the list, it is first removed from the list before it is inserted at the correct position.

Parameters

reference	a pointer to the linked list iterator structure that is used as reference
it	a pointer to the linked list iterator structure that needs to be inserted

Returns

-1 if the reference iterator is not in a list. 0 if the iterator is inserted

Definition at line 157 of file amxc_llist_it.c.

                                                          {
    int retval = -1;
    when_null(reference, exit);
    when_null(it, exit);
    when_null(reference->llist, exit);
 
    amxc_llist_it_take(it);
 
    it->next = reference->next;
    it->prev = reference;
    it->llist = reference->llist;
    reference->next = it;
 
    if(it->next != NULL) {
        it->next->prev = it;
    } else {
        it->llist->tail = it;
    }
 
    retval = 0;
exit:
    return retval;
}

amxc_llist_it_insert_before()

int amxc_llist_it_insert_before	(	amxc_llist_it_t *const	reference,
		amxc_llist_it_t *const	it
	)

Inserts an iterator before a reference interator in the list.

If the iterator is already in a list, it is first removed from the list.

Parameters

reference	a pointer to the linked list iterator structure that is used as reference
it	a pointer to the linked list iterator structure that needs to be inserted

Returns

-1 if the reference iterator is not in a list. 0 if the iterator is inserted

Definition at line 132 of file amxc_llist_it.c.

                                                           {
    int retval = -1;
    when_null(reference, exit);
    when_null(it, exit);
    when_null(reference->llist, exit);
 
    amxc_llist_it_take(it);
 
    it->next = reference;
    it->prev = reference->prev;
    it->llist = reference->llist;
    reference->prev = it;
 
    if(it->prev != NULL) {
        it->prev->next = it;
    } else {
        it->llist->head = it;
    }
 
    retval = 0;
exit:
    return retval;
}

amxc_llist_it_is_in_list()

AMXC_INLINE bool amxc_llist_it_is_in_list

(

const amxc_llist_it_t *const

it

)

Checks that an iterator is in a list.

Parameters

it	a pointer to the linked list structure.

Returns

true when the iterator is in the list, or false if it is not in a list

Definition at line 857 of file amxc_llist.h.

                                                               {
    return (it != NULL && it->llist != NULL) ? true : false;
}

amxc_llist_it_swap()

int amxc_llist_it_swap	(	amxc_llist_it_t *	it1,
		amxc_llist_it_t *	it2
	)

Swaps two linked list iterators.

The iterators being swapped can be in the same linked list or in different linked lists.

Parameters

it1	a pointer to the linked list iterator
it2	a pointer to the linked list iterator

Returns

0 when swapping the iterators was successful, when failed a non zero value is returned.

Definition at line 200 of file amxc_llist_it.c.

                                             {
    int retval = -1;
    amxc_llist_it_t* swapperVector[4] = { NULL, NULL, NULL, NULL };
 
    when_null(it1, exit);
    when_null(it2, exit);
 
    if(it1 == it2) {
        retval = 0;
        goto exit;
    }
 
    if(it1->llist != it2->llist) {
        amxc_llist_t* temp = it1->llist;
        it1->llist = it2->llist;
        it2->llist = temp;
    }
 
    if(it2->next == it1) {
        amxc_llist_it_t* temp = it1;
        it1 = it2;
        it2 = temp;
    }
 
    swapperVector[0] = it1->prev;
    swapperVector[1] = it2->prev;
    swapperVector[2] = it1->next;
    swapperVector[3] = it2->next;
 
    if(amxc_llist_it_are_adjacent(it1, it2)) {
        it1->prev = swapperVector[2];
        it2->prev = swapperVector[0];
        it1->next = swapperVector[3];
        it2->next = swapperVector[1];
    } else {
        it1->prev = swapperVector[1];
        it2->prev = swapperVector[0];
        it1->next = swapperVector[3];
        it2->next = swapperVector[2];
    }
 
    amxc_llist_it_update(it1);
    amxc_llist_it_update(it2);
 
    retval = 0;
 
exit:
    return retval;
}

amxc_llist_it_take()

void amxc_llist_it_take

(

amxc_llist_it_t *const

it

)

Removes the iterator from the list.

Parameters

it	a pointer to the linked list iterator structure

Definition at line 110 of file amxc_llist_it.c.

                                                   {
    when_null(it, exit);
    when_null(it->llist, exit);
 
    if(it->prev != NULL) {
        it->prev->next = it->next;
    } else {
        it->llist->head = it->next;
    }
    if(it->next != NULL) {
        it->next->prev = it->prev;
    } else {
        it->llist->tail = it->prev;
    }
 
    it->next = NULL;
    it->prev = NULL;
    it->llist = NULL;
exit:
    return;
}