[ library(lists_of_structures) | Reference Manual | Alphabetic Index ]

# lists_structs(?Lists, ?Structs)

Mapping between a structure of lists and a list of structures

Lists
  Structure with list arguments, or variable
Structs
  List of structures, or variable

## Description

Maps a single structure with functor F/N whose arguments are all lists of length M into a single list of length M of F/N structures, and vice versa. The arguments of the K'th structure on the right hand side correspond to the K'th list elements on the left hand side.

The main purpose of this predicate is to build a list of structures from several lists of arguments. The simplest example is building a Key-Value pair list from corresponding lists of Keys and Values.

The reverse direction is used to extract multiple argument lists from a list of structures. The simplest example is getting the Keys and Values from a Key-Value pair list. However, if only a single argument list is wanted, it is more appropriate to use args/3.

### Modes and Determinism

- lists_structs(+, -) is det
- lists_structs(-, +) is det

### Exceptions

(4) instantiation fault
  Arguments are insufficiently instantiated
(5) type error
  Some argument or its components are of the wrong type
(6) out of range
  Some structure does not have a Key'th argument

## Examples

        ?- lists_structs(f([a,b,c],[1,2,3],[x,y,z]), Structs).
        Structs = [f(a,1,x), f(b,2,y), f(c,3,z)]
        Yes (0.00s cpu)

        ?- lists_structs(Lists, [f(a,1,x), f(b,2,y), f(c,3,z)]).
        Lists = f([a,b,c], [1,2,3], [x,y,z])
        Yes (0.00s cpu)

        ?- Keys=[1,2,3], Vals=[a,b,c], lists_structs(Keys-Vals, Pairs).
        Keys = [1, 2, 3]
        Vals = [a, b, c]
        Pairs = [1-a, 2-b, 3-c]
        Yes (0.00s cpu)

        ?- lists_structs(Lists, [1-a, 2-b, 3-c]).
        Lists = [1,2,3] - [a,b,c]
        Yes (0.00s cpu)

## See Also

terms_functor / 4, args / 3