The LIST object

The list functions and structure is used for grouping data into one stream. To initialize a new t_list structure (list object) or to dispose an old one, use the following functions:


list_init ()
     Description:
       Inits a new t_list structure.

     Syntax:
       p_list  list_init ( p_list o, void (*func_free)(void *), l_big tag );

     Parameters:
       o           Pointer to the new t_list structure.
       func_free   Function to be used when releasing data.
       tag         Identification number of data (default is 0).

     Returns:
       The new t_list structure.




dispose_list ()
     Description:
       Disposes a list structure and can free context of each
       "t_item.rec" pinter in the list

     Syntax:
       void  dispose_list ( p_list *o, l_bool freeitem );

     Parameters:
       o           List to dispose.
       freeitem    If set, context for each t_item.rec is freed.

     Returns:
       -




The t_item structure

List items are defined in t_item structure.

Variables:

     Name:         void  *rec

     Description:  Place to store the data.



     Name:         l_big   tag

     Description:  Identification of the data.



     Name:         p_item  prev

     Description:  Previous item in the group of items.



     Name:         p_item  next

     Description:  Next item in the group of items.



     Name:         l_char  reserved[12]

     Description:  Reserved for future versions.



Functions:

func_free ()
     Description:
       Releases the data in "rec".

     Syntax:
       void  (*func_free) ( void* )

     Parameters:
       -

     Returns:
       -





The t_list structure

Variables:

     Name:         p_item  last;

     Description:  Points to the last item in the data group. First 
                   item is defined as last->next.



     Name:         l_big  tag;

     Description:  Default identification number of data, that's placed 
                   in address t_item.rec.



Functions:

func_free ()
     Description:
       The function to use for releasing data. The default function
       to use is "free(void);". If an item in "t_item.func_free" is 
       set to ZERO, this default function "func_free()" is called 
       in releasing of data in "t_data.rec".

     Syntax:
       void  (*func_free) ( void* );

     Parameters:
       -

     Returns:
       -



done ()
     Description:
       Removes items from list, but doesn't free the data in the items.

     Syntax:
       l_bool  (*done)( p_list o );

     Parameters:
       o           List to remove items from.

     Returns:
       True if list was successfully destroyed. False otherwise.



first_rec ()
     Description:
       Gets the first data in the list. Same as "last->next->rec",
       but tests the existance of all pointers.

     Syntax:
       void  *(*first_rec) ( p_list o );

     Parameters:
       o           The list to get data from.

     Returns:
       Pointer to the first data.



first ()
     Description:
       Gets the first item in a list.

     Syntax:
       p_item (*first) ( p_list o );

     Parameters:
       o           The list to get the item from.

     Returns:
       The item.



at_item ()
     Description:
       Get item number ... from the list.

     Syntax:
       p_item (*at_item)( p_list o, l_long index );

     Parameters:
       o           List to get item from.
       index       The items number in the list.

     Returns:
       The item.



at ()
     Description:
       Get data number ... from the list.

     Syntax:
       void  *(*at)( p_list o, l_long index );

     Parameters:
       o           List to get data from.
       index       The datas number in the list.

     Returns:
       The data.



index_of ()
     Description:
       Gets the position of where the data is placed in the list.

     Syntax:
       l_long (*index_of)( p_list o, void *rec );

     Parameters:
       o           The list containing the data.
       rec         Data to be found.

     Returns:
       The  position of the data in the list.



index_of_item ()
     Description:
       Gets the position of an item in a list.

     Syntax:
       l_long (*index_of_item)( p_list o, p_item item );

     Parameters:
       o           The list containing the data.
       item        The item to be found.

     Returns:
       The  position of the item in the list.



get_max_item ()
     Description:
       Gets the number of items in a list.

     Syntax:
       l_long  (*get_max_item)(p_list o); 

     Parameters:
       o           The list to count in.

     Returns:
       Number of items.



copy_ctx ()
     Description:
       Copies the context of a list to the end of another list.

     Syntax:
       void  (*copy_ctx) ( p_list dst, p_list src );

     Parameters:
       dst         List to copy items to.
       stc         List to copy from.

     Returns:
       -



find_rec ()
     Description:
       Finds the item containing the specified data.

     Syntax:
       p_item (*find_rec)( p_list o, void *rec );

     Parameters:
       o           The list to look in.
       rec         Data to find.

     Returns:
       The item.



insert_ex ()
     Description:
       Inserts new data to an item that will be inserted into the list.

     Syntax:
       l_long (*insert_ex)( p_list o, void *rec, void (*f_free)(void *),
                            l_big tag );

     Parameters:
       o           List to insert to.
       rec         The data to insert.
       f_free      "rec" will be deallocated by this function. if "rec"
                   is NULL, it will use the lists default "func_free"
                   function.
       tag         Identification of the item data.

     Returns:
       The index of the new item.



insert ()
     Description:
       Inserts new data to an item that will be inserted into the list.
       Same as insert_ex () but with "f_free" and "tag" set to zero.

     Syntax:
       l_long  (*insert)(p_list o, void *rec);

     Parameters:
       o           List to insert to.
       rec         The data to insert.

     Returns:
       The index of the new item.



remove_index ()
     Description:
       Removes item number "index" from a list.

     Syntax:
       void  (*remove_index)(p_list o, l_long index );

     Parameters:
       o           The list to remove from.
       index       Index of the item to remove.

     Returns:
       -



remove_item ()
     Description:
       Removes an item from a list, but doesn't free data
       from item->rec.

     Syntax:
       void   (*remove_item)(p_list o,  p_item item );

     Parameters:
       o           The list to remove from.
       item        Structure containing the item to remove.

     Returns:
       -



free_index
     Description:
       Removes item number "index" from a list and frees the data
       from the "t_item.rec" pointer and the memory of the item.

     Syntax:
       void  (*free_index)(p_list o, l_long index );

     Parameters:
       o           The list to remove from.
       index       Index of the item to remove.

     Returns:
       -



free_item ()
     Description:
       Removes an item from a list and frees the data from the
       "t_item.rec" pointer and the memory of the item.

     Syntax:
       void  (*free_item)(p_list o, p_item item );

     Parameters:
       o           The list to remove from.
       item        Structure containing the item to remove.

     Returns:
       -



free_all ()
     Description:
       Removes all the items from a list. Also frees data from each
       item and the memory allocated for them by the insert_ex function.
     Syntax:
       void  (*free_all)(p_list o );

     Parameters:
       o           The list to remove from.

     Returns:
       -



for_each_item ()
     Description:
       Calls a function callback for each items data in the list.
       If the function returns zero, process will be broken.

     Syntax:
       l_bool (*for_each_item) ( p_list o, void *ob, l_int (*callback)(),
                                 l_dword *ind );

     Parameters:
       o           The list of items to run the function for.
       ob          Name of list (argument to the function).
       callback    The callback function.
       ind         Argument to the callback function.

     Returns:
       True if process was broken. False otherwise.



for_each_item_to_item ()
     Description:
       Calls a function callback for each items data in the list
       until item number "index". If the function returns zero, 
       process will be broken.

     Syntax:
       l_bool (*for_each_item_to_item) ( p_list o, void *ob, void *item,
                                         l_int (*callback)(), l_dword *ind );

     Parameters:
       o           The list of items to run the function for.
       ob          Name of list (argument to the function).
       item        Process is stopped when the item with this
                   index is encountered.
       callback    The callback function.
       ind         Argument to the callback function.

     Returns:
       True if process was broken. False otherwise.
       


collect_by_name_from ()
     Description:
       Collects data by name. List must contains group of text data or
       structures where text ocurres in the first position. If tag of 
       "item->tag" is DAT_TEXT it means that "item->rec" is a string, 
       otherwise it uses a structure, where first 4 bytes are pointers
       to string. 

     Syntax:
       l_bool (*collect_by_name_from)(p_list o, p_item from, 
                                      l_int rec_delta);

     Parameters:
       o           List to collect the data in.
       from        Pointer to where in the list to collect the data from.
                   If "from" is NULL then collect from last item.
       delta       

     Returns:
       True if data was successfully collected. False otherwise.





Example:


           p_list p = list_init(malloc(sizeof(t_list)), &free, 0);

           p->insert(p, (void*)strdup("Hello world !"));
           p->insert(p, (void*)strdup("SEAL is free desktop environmnet"));
           p->insert(p, (void*)strdup("Hello Mr. Stencl !"));

           collect_by_name(p, 0);

     /* Now the list "p" contains 3 items, 
        and in the each of them are strings. */


           p->free_index(p, 0);

     /* This function removes the 0th item, that contains the
        ("Hello world !") data and this data is free by function 
        "free(void*)", that is declared in "list_init" function.  */



     /* Below are two ways of destroying the list. Use one of them. 
        The first way:  */

           p->free_all(p);
           p->done(p);
           free(p);

   
     /* ...and the second way: */

           dispose_list(p, true);