[ Reference Manual | Alphabetic Index ]

# library(list_collection)

Collection of lists library [more]

## Predicates

> append_element(+LCOL, ++Index, +Elem)
>   Append an Elem to the internal list identified by Index.
> append_list(+LCOL, ++Index, +List)
>   Append a List to the internal list identified by Index.
> create(++Type, -LCOL)
>   Creates a list collection
> get_indexes(+LCOL, -Indexes)
>   Retrieves the list of indexes
> get_list(+LCOL, ++Index, -List)
>   Retrieves the list of elements identified by Index
> prefix_element(+LCOL, ++Index, +Elem)
>   Prefixes the internal list identified by Index with an Elem.
> prefix_list(+LCOL, ++Index, +List)
>   Prefixes the internal list identified by Index with a List.
> reinit(+LCOL, ++Index)
>   Creates a new list identified by Index
> terminate_all_lists(+LCOL, -Indexes)
>   Terminates all internal lists in the collection, and gets the list of indexes
> terminate_and_get_list(+LCOL, ++Index, -List)
>   Retrieves the List of elements identified by Index

## Description

        A library for creation and management of list collections (LCOL).
        Internally the library uses either the a hashtable or arrays to store lists and their tails.
        The advantage of a hash LCOL is that its size does not have to be known in advance and that
        non number indexes can be used to address lists in the collection. The drawback of a hash LCOL
        is that access to collection elements is slower than for array LCOL. Elements of array LCOL
        can be addressed only by positive integers which internally are array indexes. See create/2
        for more details.

        The motivation for creating this library was to be able to easily build input lists for global
        constraints from collections of input structures (see example). For this purpose an array(3) LCOL
        was usually sufficient, and only a limited set of predicates needed (create/2 , append_element/3,
        terminate_all_lists/2, get_list/3).

        But the idea was extended, additional predicates were added for prefixing the lists, and
        reinitialisation of lists. The support for hash LCOL has been added. Hash LCOL may be useful for
        some filtering, grouping predicates in cases when the number of lists may vary or indexing by
        atoms/ground terms is more readable/convenient.

## Examples

    llcol_example:-
        lib(ic),
        lib(ic_edge_finder),

        ActivityList=[
            act(4,7 ,2,machine_1),
            act(3,4 ,1,machine_2 ),
            act(2,4 ,2,removed),
            act(7,10,1,machine_1),
            act(6,15,3,machine_3)
            % ...
        ],

        %create a collection of activity lists for corresponding machines
        list_collection:create(hash,LCOL_Machines),

        %sort the activities for machines
        (foreach(Activity,ActivityList),
         param(LCOL_Machines) do
            Activity=act(_Start,_End,_Resource,Machine),
            (Machine \= removed ->
                %add an activity to the list for the particular machine
                list_collection:append_element(LCOL_Machines,Machine,Activity)
            ;true)
        ),

        %close the lists get the machine names
        list_collection:terminate_all_lists(LCOL_Machines,Machines_Indexes),

        %for each machine
        (foreach(Machines_Index,Machines_Indexes),
         param(LCOL_Machines) do
            %Note that get_list/3 can be used even if the lists are not terminated but in such a case the operation
            %is more time consuming, because all the list elements are copied to new closed list and then returned.
            %Instead of closing all the lists at once it is also possible to use terminate_and_get_list/3 to ensure
            %that the list is closed.

            %get the activity list for the machine
            list_collection:get_list(LCOL_Machines,Machines_Index,MActivityList),

            %create a collection for start,duration and resource variable lists
            list_collection:create(array(3),LCOL_Start_Dur_Res),

            (foreach(MActivity,MActivityList),
             param(LCOL_Start_Dur_Res) do

                MActivity=act(Start,End,Resource,_Machine),
                ic:(Duration #= End - Start),
                list_collection:append_element(LCOL_Start_Dur_Res, 1, Start),
                list_collection:append_element(LCOL_Start_Dur_Res, 2, Duration),
                list_collection:append_element(LCOL_Start_Dur_Res, 3, Resource)
            ),

            %terminate the start,duration,resource lists
            list_collection:terminate_all_lists(LCOL_Start_Dur_Res,_Indexes),

            %get the lists for a cumulative constraint
            list_collection:get_list(LCOL_Start_Dur_Res, 1, StartList),
            list_collection:get_list(LCOL_Start_Dur_Res, 2, DurationList),
            list_collection:get_list(LCOL_Start_Dur_Res, 3, ResourceList),

            %post the constraint
            ic_edge_finder:cumulative(StartList, DurationList, ResourceList, 3)
        ).

## About

- Author: Lukasz Domagala
- Copyright © Silesian University of Technology
- Date: $Date: 2009/07/16 09:11:23 $

Generated from list_collection.eci on 2020-02-26 22:26