The Link-list service routine can be divided into 7 main category. There are Initialisation, Insertion of object, Deletion of object, Movement of node, Information retrieval, Searching activities and Displaying of object.

1. Initialisation

Before a link-list can be implemented, it need to be declared and initialised.

1.1 Declaration of link-list

Prototype : Rlist *<list_name>
Example : Rlist *del_list;

1.2 Initialisation of link-list

Prototype: Rlist * rl_new ( void ( *ptrTofn ) ( void *obj ), ... )
Example: del_list = rl_new ( del_print, del_match_ids, 0 );

In the above example, del_print is the function that print out the content of the del_object. The function, del_match_ids, is use for comparsion purposes when an enquiry is done on the list. The parameter for the rl_new need to terminate with '0'.

2. Insertion of object

An object can be inserted into the existing list of object. There are 4 ways to insert the object into the list.

2.1 Put the object at the end of the list.

Prototype: void rl_put ( Rlist *rl, void *obj )
Example: rl_put ( del_list, del_obj );

2.2 Put the object at the front of the list

Prototype: void rl_putfront ( Rlist *rl, void *obj )
Example: rl_putfront ( del_list, del_obj )

2.3 Put the object before the current position

Prototype: void rl_put_before ( Rlist *rl, void *obj )
Example: rl_put_before ( del_list, del_obj )

2.4 Put the object after the current postion

Prototype: void rl_put_after ( Rlist *rl, void *obj )
Example: rl_put_after ( del_list, del_obj )

3. Deletion of object

An object in the list can be removed, or all the object in the list can be deleted. The entire Rlist structure can also be deleted.

3.1 Removing a node from the list

Prototype: void rl_remove ( Rlist *rl )
Example: rl_remove ( del_list );

The current node will be deleted.

3.2 Emptying the entire list

Prototype: void rl_dump ( Rlist *rl )
Example: rl_dump ( del_list );

All the node in the list will be deleted, only the dummy header node is left.

3.3 Destroying the entire list

Prototype: void rl_delete ( Rlist *rl )
Example: rl_delete ( del_list );

All the node in the list will be deleted first and follow by the Rlist pointer.

4. Movement of Nodes

Every time when a node is accessed, the current pointer will postion itself to that particular node. The current pointer can be shifted with the following commands.

4.1 Set current pointer to the beginning of list

Prototype: void rl_reset ( Rlist *rl )
Example: rl_reset ( del_list );

4.2 Set current pointer to the next node

Prototype: void rl_next ( Rlist *rl )
Example: rl_next ( del_list );

4.3 Set current pointer to the previous node

Prototype: void rl_prev ( Rlist *rl )
Example: rl_prev ( del_list );

5. Information Retrieval

Object in the list can be retrieved. It can be retrieved from the front or from the rear.

5.1 Dequeue the object

Prototype: void *rl_get ( Rlist *rl )
Example: del_obj = rl_get ( del_list );

The first object in the list will be removed and store in the variable del_obj.

Note: this is a destructive retrieval. The object being retrieved will no longer be in the list.

5.2 Retrieve the first object

Prototype: void *rl_front ( Rlist *rl )
Example: del_obj = rl_front ( del_list );

The first object in the list wll be copy to the variable del_obj. At the same time, the first object will still be in the list, it will not be removed.

5.3 Retrieve the last object

Prototype: void *rl_rear ( Rlist *rl )
Example: del_obj = rl_rear ( del_list );

The last object in the list will be copy to the variable del_obj. This last object will still be in the list.

5.4 Retrieve the current object

Prototype: void *rl_retrieve ( Rlist *rl )
Example: del_obj = rl_retrieve ( del_list );

The object pointer by the current pointer will be copy to the variable del_obj. This is to retrieve out the current object.

5.5 Retrieve the next object

Prototype: void *rl_retrieve_next ( Rlist *rl )
Example: del_obj = rl_retrieve_next ( del_list );

The object next to the current pointer will be retrieved. After retrieving the object, the current pointer will shift to the object being retrieved.

5.6 Retrieve the previous object

Prototype: void *rl_retrieve_prev ( Rlist *rl )
Example: del_obj = rl_retrieve_prev ( del_list );

The object previous to the current pointer will be retrieved. After retrieving the object, the current pointer will shift to the object being retrieved.

5.7 Size of the list

Prototype: int rl_size ( Rlist *rl )
Example: size = rl_size ( del_list );

This function will return the number of object (nodes) in the list.

5.8 Check if list is empty

Prototype: int rl_empty ( Rlist *rl )
Example: empty = rl_empty ( del_list );

This function will return 0 if there are more than 1 object in the list, return 1 if there is no object in the list.

5.9 Check if list is full

Prototype: int rl_full ( Rlist *rl )
Example: full = rl_full ( del_list );

This funciton will return 1 if the list is full, return 0 if the list is not full.

5.10 Check is the current pointer at the front of the list

Prototype: int rl_isHead ( Rlist *rl )
Example: head = rl_isHead ( del_list );

This function will return 1 if the current pointer points to the front of the list.

5.11 Check is the current pointer at the rear of the list

Prototype: int rl_isTail ( Rlist *rl )
Example: tail = rl_isTail ( del_list );

This function will return 1 if the current pointer points to the rear of the list.

6. Searching Activities

Enquiry can be done through the list to look for a particular object. To use the following function, the comparsion function need to be pass in as a parameter when initialising the list. A list of comparsion functions ca be passed in when initialising the list. The first comparsion function will have index known as index 0 and subsequent function will have index increase by 1.

6.1 Query of object exists

Prototype: int rl_find ( Rlist *rl, void *key, int idx )
Example: find = rl_find ( del_list, "00386386", 0 );

In the above example, it will search through the del_list. The key word to look for is "00386386" and it will use the first comparsion function passed in during the initialisation of del_list.

6.2 Query forward

Prototype: int rl_findnext ( Rlist *rl, void *key, int idx )
Example: find = rl_findnext ( del_list, "00386386", 0 );

It will look for the forward next occurrence of the object with the key "00386386".

6.3 Query backward

Prototype: int rl_findprev ( Rlist *rl, void *key, int idx )
Example: find = rl_findprev ( del_list, "00386386", 0 );

It will look for the previous occurrence of the object with the key "00386386".

7. Displaying of object

The content of the object can be displayed. The field to be displayed is specified in the print function that passed in as a parameter when initialising the list.

7.1 Display the current object

Prototype: void rl_show_curr ( Rlist *rl )
Example: rl_show_curr ( del_list );

7.2 Display the front object

Prototype: void rl_show_front ( Rlist *rl )
Example: rl_show_front ( del_list );

7.3 Display the rear object

Prototype: void rl_show_rear ( Rlist *rl )
Example: rl_show_rear ( del_list );

7.4 Display all the object in the FIFO order

Prototype: void rl_display_fifo ( Rlist *rl )
Example: rl_display_fifo ( del_list );