PAKCS
Exported names: Imported modules:

Module Control.SetFunctions

This module contains an implementation of set functions. The general idea of set functions is described in:

S. Antoy, M. Hanus: Set Functions for Functional Logic Programming Proc. 11th International Conference on Principles and Practice of Declarative Programming (PPDP'09), pp. 73-82, ACM Press, 2009

Intuition: If f is an n-ary function, then (setn f) is a set-valued function that collects all non-determinism caused by f (but not the non-determinism caused by evaluating arguments!) in a set. Thus, (setn f a1 ... an) returns the set of all values of (f b1 ... bn) where b1,...,bn are values of the arguments a1,...,an (i.e., the arguments are evaluated "outside" this capsule so that the non-determinism caused by evaluating these arguments is not captured in this capsule but yields several results for (setn...). Similarly, logical variables occuring in a1,...,an are not bound inside this capsule (in PAKCS they cause a suspension until they are bound).

The set of values returned by a set function is represented by an abstract type Values on which several operations are defined in this module. Actually, it is a multiset of values, i.e., duplicates are not removed.

The handling of failures and nested occurrences of set functions is not specified in the previous paper. Thus, a detailed description of the semantics of set functions as implemented in this library can be found in the paper

J. Christiansen, M. Hanus, F. Reck, D. Seidel: A Semantics for Weakly Encapsulated Search in Functional Logic Programs Proc. 15th International Conference on Principles and Practice of Declarative Programming (PPDP'13), pp. 49-60, ACM Press, 2013

Restrictions of the PAKCS implementation of set functions:

  1. The set is a multiset, i.e., it might contain multiple values.
  2. The multiset of values is completely evaluated when demanded. Thus, if it is infinite, its evaluation will not terminate even if only some elements (e.g., for a containment test) are demanded. However, for the emptiness test, at most one value will be computed
  3. The arguments of a set function are strictly evaluated before the set functions itself will be evaluated.

Author: Michael Hanus, Fabian Reck

Version: December 2018

Summary of exported operations:

set0 :: a -> Values a   
Combinator to transform a 0-ary function into a corresponding set function.
set1 :: (a -> b) -> a -> Values b   
Combinator to transform a unary function into a corresponding set function.
set2 :: (a -> b -> c) -> a -> b -> Values c   
Combinator to transform a binary function into a corresponding set function.
set3 :: (a -> b -> c -> d) -> a -> b -> c -> Values d   
Combinator to transform a function of arity 3 into a corresponding set function.
set4 :: (a -> b -> c -> d -> e) -> a -> b -> c -> d -> Values e   
Combinator to transform a function of arity 4 into a corresponding set function.
set5 :: (a -> b -> c -> d -> e -> f) -> a -> b -> c -> d -> e -> Values f   
Combinator to transform a function of arity 5 into a corresponding set function.
set6 :: (a -> b -> c -> d -> e -> f -> g) -> a -> b -> c -> d -> e -> f -> Values g   
Combinator to transform a function of arity 6 into a corresponding set function.
set7 :: (a -> b -> c -> d -> e -> f -> g -> h) -> a -> b -> c -> d -> e -> f -> g -> Values h   
Combinator to transform a function of arity 7 into a corresponding set function.
isEmpty :: Values a -> Bool   
Is a multiset of values empty?
notEmpty :: Values a -> Bool   
Is a multiset of values not empty?
valueOf :: Eq a => a -> Values a -> Bool   
Is some value an element of a multiset of values?
choose :: Eq a => Values a -> (a,Values a)   
Chooses (non-deterministically) some value in a multiset of values and returns the chosen value and the remaining multiset of values.
chooseValue :: Eq a => Values a -> a   
Chooses (non-deterministically) some value in a multiset of values and returns the chosen value.
select :: Values a -> (a,Values a)   
Selects (indeterministically) some value in a multiset of values and returns the selected value and the remaining multiset of values.
selectValue :: Values a -> a   
Selects (indeterministically) some value in a multiset of values and returns the selected value.
mapValues :: (a -> b) -> Values a -> Values b   
Maps a function to all elements of a multiset of values.
foldValues :: (a -> a -> a) -> a -> Values a -> a   
Accumulates all elements of a multiset of values by applying a binary operation.
filterValues :: (a -> Bool) -> Values a -> Values a   
Keeps all elements of a multiset of values that satisfy a predicate.
minValue :: Ord a => Values a -> a   
Returns the minimum of a non-empty multiset of values according to the given comparison function on the elements.
minValueBy :: (a -> a -> Ordering) -> Values a -> a   
Returns the minimum of a non-empty multiset of values according to the given comparison function on the elements.
maxValue :: Ord a => Values a -> a   
Returns the maximum of a non-empty multiset of values according to the given comparison function on the elements.
maxValueBy :: (a -> a -> Ordering) -> Values a -> a   
Returns the maximum of a non-empty multiset of values according to the given comparison function on the elements.
values2list :: Values a -> IO [a]   
Puts all elements of a multiset of values in a list.
printValues :: Show a => Values a -> IO ()   
Prints all elements of a multiset of values.
sortValues :: Ord a => Values a -> [a]   
Transforms a multiset of values into a list sorted by the standard term ordering.
sortValuesBy :: (a -> a -> Bool) -> Values a -> [a]   
Transforms a multiset of values into a list sorted by a given ordering on the values.

Exported datatypes:

Values

Abstract type representing multisets of values.

Constructors:

Exported operations:

set0 :: a -> Values a   

Combinator to transform a 0-ary function into a corresponding set function.

set1 :: (a -> b) -> a -> Values b   

Combinator to transform a unary function into a corresponding set function.

set2 :: (a -> b -> c) -> a -> b -> Values c   

Combinator to transform a binary function into a corresponding set function.

set3 :: (a -> b -> c -> d) -> a -> b -> c -> Values d   

Combinator to transform a function of arity 3 into a corresponding set function.

set4 :: (a -> b -> c -> d -> e) -> a -> b -> c -> d -> Values e   

Combinator to transform a function of arity 4 into a corresponding set function.

set5 :: (a -> b -> c -> d -> e -> f) -> a -> b -> c -> d -> e -> Values f   

Combinator to transform a function of arity 5 into a corresponding set function.

set6 :: (a -> b -> c -> d -> e -> f -> g) -> a -> b -> c -> d -> e -> f -> Values g   

Combinator to transform a function of arity 6 into a corresponding set function.

set7 :: (a -> b -> c -> d -> e -> f -> g -> h) -> a -> b -> c -> d -> e -> f -> g -> Values h   

Combinator to transform a function of arity 7 into a corresponding set function.

isEmpty :: Values a -> Bool   

Is a multiset of values empty?

notEmpty :: Values a -> Bool   

Is a multiset of values not empty?

valueOf :: Eq a => a -> Values a -> Bool   

Is some value an element of a multiset of values?

choose :: Eq a => Values a -> (a,Values a)   

Chooses (non-deterministically) some value in a multiset of values and returns the chosen value and the remaining multiset of values. Thus, if we consider the operation chooseValue by 

chooseValue x = fst (choose x)

then (set1 chooseValue) is the identity on value sets, i.e., (set1 chooseValue s) contains the same elements as the value set s.

chooseValue :: Eq a => Values a -> a   

Chooses (non-deterministically) some value in a multiset of values and returns the chosen value. Thus, (set1 chooseValue) is the identity on value sets, i.e., (set1 chooseValue s) contains the same elements as the value set s.

select :: Values a -> (a,Values a)   

Selects (indeterministically) some value in a multiset of values and returns the selected value and the remaining multiset of values. Thus, select has always at most one value. It fails if the value set is empty.

NOTE: The usage of this operation is only safe (i.e., does not destroy completeness) if all values in the argument set are identical.

Further infos:
  • partially defined

selectValue :: Values a -> a   

Selects (indeterministically) some value in a multiset of values and returns the selected value. Thus, selectValue has always at most one value. It fails if the value set is empty.

NOTE: The usage of this operation is only safe (i.e., does not destroy completeness) if all values in the argument set are identical.

Further infos:
  • partially defined
  • solution complete, i.e., able to compute all solutions

mapValues :: (a -> b) -> Values a -> Values b   

Maps a function to all elements of a multiset of values.

foldValues :: (a -> a -> a) -> a -> Values a -> a   

Accumulates all elements of a multiset of values by applying a binary operation. This is similarly to fold on lists, but the binary operation must be commutative so that the result is independent of the order of applying this operation to all elements in the multiset.

filterValues :: (a -> Bool) -> Values a -> Values a   

Keeps all elements of a multiset of values that satisfy a predicate.

minValue :: Ord a => Values a -> a   

Returns the minimum of a non-empty multiset of values according to the given comparison function on the elements.

minValueBy :: (a -> a -> Ordering) -> Values a -> a   

Returns the minimum of a non-empty multiset of values according to the given comparison function on the elements.

maxValue :: Ord a => Values a -> a   

Returns the maximum of a non-empty multiset of values according to the given comparison function on the elements.

maxValueBy :: (a -> a -> Ordering) -> Values a -> a   

Returns the maximum of a non-empty multiset of values according to the given comparison function on the elements.

values2list :: Values a -> IO [a]   

Puts all elements of a multiset of values in a list. Since the order of the elements in the list might depend on the time of the computation, this operation is an I/O action.

printValues :: Show a => Values a -> IO ()   

Prints all elements of a multiset of values.

sortValues :: Ord a => Values a -> [a]   

Transforms a multiset of values into a list sorted by the standard term ordering. As a consequence, the multiset of values is completely evaluated.

sortValuesBy :: (a -> a -> Bool) -> Values a -> [a]   

Transforms a multiset of values into a list sorted by a given ordering on the values. As a consequence, the multiset of values is completely evaluated. In order to ensure that the result of this operation is independent of the evaluation order, the given ordering must be a total order.