rishi/scryer-prolog
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge pull request #1656 from aarroyoc/docs-ordsets

Browse Source 
Compatible Doclog docs for library(ordsets)
This commit is contained in:
Mark Thom
2022-12-10 18:08:45 +01:00
committed by GitHub
parent d5db0c641c e0464d5447
commit 0d404ad374
1 changed files with 87 additions and 100 deletions
Download Patch File Download Diff File Expand all files Collapse all files

187
src/lib/ordsets.pl
View File

@@ -54,20 +54,19 @@
:- use_module(library(lists)). :- use_module(library(lists)).
/** <module> Ordered set manipulation /** Ordered set manipulation
Ordered sets are lists with unique elements sorted to the standard order Ordered sets are lists with unique elements sorted to the standard order
of terms (see sort/2). Exploiting ordering, many of the set operations of terms (see sort/2). Exploiting ordering, many of the set operations
can be expressed in order N rather than N^2 when dealing with unordered can be expressed in order N rather than N^2 when dealing with unordered
sets that may contain duplicates. The library(ordsets) is available in a sets that may contain duplicates. The library(ordsets) is available in a
number of Prolog implementations. Our predicates are designed to be number of Prolog implementations. Our predicates are designed to be
compatible with common practice in the Prolog community. The compatible with common practice in the Prolog community.
implementation is incomplete and relies partly on library(oset), an
older ordered set library distributed with SWI-Prolog. New applications
are advised to use library(ordsets).
Some of these predicates match directly to corresponding list Some of these predicates match directly to corresponding list
operations. It is advised to use the versions from this library to make operations. It is advised to use the versions from this library to make
clear you are operating on ordered sets. An exception is member/2. See clear you are operating on ordered sets. An exception is member/2. See
ord_memberchk/2. ord\_memberchk/2.
The ordsets library is based on the standard order of terms. This The ordsets library is based on the standard order of terms. This
implies it can handle all Prolog terms, including variables. Note implies it can handle all Prolog terms, including variables. Note
however, that the ordering is not stable if a term inside the set is however, that the ordering is not stable if a term inside the set is
@@ -80,13 +79,13 @@ fresh variable. In other cases one should cease using it as an ordset
because the order it relies on may have been changed. because the order it relies on may have been changed.
*/ */
%! is_ordset(@Term) is semidet. %% is_ordset(@Term) is semidet.
% %
% True if Term is an ordered set. All predicates in this library % True if Term is an ordered set. All predicates in this library
% expect ordered sets as input arguments. Failing to fullfil this % expect ordered sets as input arguments. Failing to fullfil this
% assumption results in undefined behaviour. Typically, ordered % assumption results in undefined behaviour. Typically, ordered
% sets are created by predicates from this library, sort/2 or % sets are created by predicates from this library, sort/2 or
% setof/3. % setof/3.
is_ordset(Term) :- is_ordset(Term) :-
'$skip_max_list'(_, _, Term, Tail), Tail == [], %% is_list(Term), '$skip_max_list'(_, _, Term, Tail), Tail == [], %% is_list(Term),
@@ -102,37 +101,35 @@ is_ordset3([H2|T], H) :-
is_ordset3(T, H2). is_ordset3(T, H2).
%! ord_empty(?List) is semidet. %% ord_empty(?List) is semidet.
% %
% True when List is the empty ordered set. Simply unifies list % True when List is the empty ordered set. Simply unifies list
% with the empty list. Not part of Quintus. % with the empty list. Not part of Quintus.
ord_empty([]). ord_empty([]).
%! ord_seteq(+Set1, +Set2) is semidet. %% ord_seteq(+Set1, +Set2) is semidet.
% %
% True if Set1 and Set2 have the same elements. As both are % True if Set1 and Set2 have the same elements. As both are
% canonical sorted lists, this is the same as ==/2. % canonical sorted lists, this is the same as ==/2.
%
% @compat sicstus
ord_seteq(Set1, Set2) :- ord_seteq(Set1, Set2) :-
Set1 == Set2. Set1 == Set2.
%! list_to_ord_set(+List, -OrdSet) is det. %% list_to_ord_set(+List, -OrdSet) is det.
% %
% Transform a list into an ordered set. This is the same as % Transform a list into an ordered set. This is the same as
% sorting the list. % sorting the list.
list_to_ord_set(List, Set) :- list_to_ord_set(List, Set) :-
sort(List, Set). sort(List, Set).
%! ord_intersect(+Set1, +Set2) is semidet. %% ord_intersect(+Set1, +Set2) is semidet.
% %
% True if both ordered sets have a non-empty intersection. % True if both ordered sets have a non-empty intersection.
ord_intersect([H1|T1], L2) :- ord_intersect([H1|T1], L2) :-
ord_intersect_(L2, H1, T1). ord_intersect_(L2, H1, T1).
@@ -148,31 +145,29 @@ ord_intersect__(>, H1, T1, _H2, T2) :-
ord_intersect_(T2, H1, T1). ord_intersect_(T2, H1, T1).
%! ord_disjoint(+Set1, +Set2) is semidet. %% ord_disjoint(+Set1, +Set2) is semidet.
% %
% True if Set1 and Set2 have no common elements. This is the % True if Set1 and Set2 have no common elements. This is the
% negation of ord_intersect/2. % negation of ord\_intersect/2.
ord_disjoint(Set1, Set2) :- ord_disjoint(Set1, Set2) :-
\+ ord_intersect(Set1, Set2). \+ ord_intersect(Set1, Set2).
%! ord_intersect(+Set1, +Set2, -Intersection) %% ord_intersect(+Set1, +Set2, -Intersection)
% %
% Intersection holds the common elements of Set1 and Set2. % Intersection holds the common elements of Set1 and Set2.
% %
% @deprecated Use ord_intersection/3 % This predicate is **deprecated**. Use ord\_intersection/3
ord_intersect(Set1, Set2, Intersection) :- ord_intersect(Set1, Set2, Intersection) :-
oset_int(Set1, Set2, Intersection). oset_int(Set1, Set2, Intersection).
%! ord_intersection(+PowerSet, -Intersection) %% ord_intersection(+PowerSet, -Intersection)
% %
% Intersection of a powerset. True when Intersection is an ordered % Intersection of a powerset. True when Intersection is an ordered
% set holding all elements common to all sets in PowerSet. % set holding all elements common to all sets in PowerSet.
%
% @compat sicstus
ord_intersection(PowerSet, Intersection) :- ord_intersection(PowerSet, Intersection) :-
key_by_length(PowerSet, Pairs), key_by_length(PowerSet, Pairs),
@@ -190,10 +185,10 @@ l_int([_-H|T], S0, S) :-
l_int(T, S1, S). l_int(T, S1, S).
%! ord_intersection(+Set1, +Set2, -Intersection) is det. %% ord_intersection(+Set1, +Set2, -Intersection) is det.
% %
% Intersection holds the common elements of Set1 and Set2. Uses % Intersection holds the common elements of Set1 and Set2. Uses
% ord_disjoint/2 if Intersection is bound to `[]` on entry. % ord\_disjoint/2 if Intersection is bound to `[]` on entry.
ord_intersection(Set1, Set2, Intersection) :- ord_intersection(Set1, Set2, Intersection) :-
( Intersection == [] ( Intersection == []
@@ -202,13 +197,11 @@ ord_intersection(Set1, Set2, Intersection) :-
). ).
%! ord_intersection(+Set1, +Set2, ?Intersection, ?Difference) is det. %% ord_intersection(+Set1, +Set2, ?Intersection, ?Difference) is det.
% %
% Intersection and difference between two ordered sets. % Intersection and difference between two ordered sets.
% Intersection is the intersection between Set1 and Set2, while % Intersection is the intersection between Set1 and Set2, while
% Difference is defined by ord_subtract(Set2, Set1, Difference). % Difference is defined by ord\_subtract(Set2, Set1, Difference).
%
% @see ord_intersection/3 and ord_subtract/3.
ord_intersection([], L, [], L) :- !. ord_intersection([], L, [], L) :- !.
ord_intersection([_|_], [], [], []) :- !. ord_intersection([_|_], [], [], []) :- !.
@@ -224,35 +217,35 @@ ord_intersection2(>, H1, T1, H2, T2, Intersection, [H2|HDiff]) :-
ord_intersection([H1|T1], T2, Intersection, HDiff). ord_intersection([H1|T1], T2, Intersection, HDiff).
%! ord_add_element(+Set1, +Element, ?Set2) is det. %% ord_add_element(+Set1, +Element, ?Set2) is det.
% %
% Insert an element into the set. This is the same as % Insert an element into the set. This is the same as
% ord_union(Set1, [Element], Set2). % ord\_union(Set1, [Element], Set2).
ord_add_element(Set1, Element, Set2) :- ord_add_element(Set1, Element, Set2) :-
oset_addel(Set1, Element, Set2). oset_addel(Set1, Element, Set2).
%! ord_del_element(+Set, +Element, -NewSet) is det. %% ord_del_element(+Set, +Element, -NewSet) is det.
% %
% Delete an element from an ordered set. This is the same as % Delete an element from an ordered set. This is the same as
% ord_subtract(Set, [Element], NewSet). % ord\_subtract(Set, [Element], NewSet).
ord_del_element(Set, Element, NewSet) :- ord_del_element(Set, Element, NewSet) :-
oset_delel(Set, Element, NewSet). oset_delel(Set, Element, NewSet).
%! ord_selectchk(+Item, ?Set1, ?Set2) is semidet. %% ord_selectchk(+Item, ?Set1, ?Set2) is semidet.
% %
% Selectchk/3, specialised for ordered sets. Is true when % Selectchk/3, specialised for ordered sets. Is true when
% select(Item, Set1, Set2) and Set1, Set2 are both sorted lists % select(Item, Set1, Set2) and Set1, Set2 are both sorted lists
% without duplicates. This implementation is only expected to work % without duplicates. This implementation is only expected to work
% for Item ground and either Set1 or Set2 ground. The "chk" suffix % for Item ground and either Set1 or Set2 ground. The "chk" suffix
% is meant to remind you of memberchk/2, which also expects its % is meant to remind you of memberchk/2, which also expects its
% first argument to be ground. ord_selectchk(X, S, T) => % first argument to be ground. ord\_selectchk(X, S, T) =>
% ord_memberchk(X, S) & \+ ord_memberchk(X, T). % ord\_memberchk(X, S) & \\+ ord\_memberchk(X, T).
% %
% @author Richard O'Keefe % Author: Richard O'Keefe
ord_selectchk(Item, [X|Set1], [X|Set2]) :- ord_selectchk(Item, [X|Set1], [X|Set2]) :-
X @< Item, X @< Item,
@@ -266,19 +259,19 @@ ord_selectchk(Item, [Item|Set1], Set1) :-
). ).
%! ord_memberchk(+Element, +OrdSet) is semidet. %% ord_memberchk(+Element, +OrdSet) is semidet.
% %
% True if Element is a member of OrdSet, compared using ==. Note % True if Element is a member of OrdSet, compared using ==. Note
% that _enumerating_ elements of an ordered set can be done using % that _enumerating_ elements of an ordered set can be done using
% member/2. % member/2.
% %
% Some Prolog implementations also provide ord_member/2, with the % Some Prolog implementations also provide ord\_member/2, with the
% same semantics as ord_memberchk/2. We believe that having a % same semantics as ord\_memberchk/2. We believe that having a
% semidet ord_member/2 is unacceptably inconsistent with the *_chk % semidet ord\_member/2 is unacceptably inconsistent with the \*\_chk
% convention. Portable code should use ord_memberchk/2 or % convention. Portable code should use ord\_memberchk/2 or
% member/2. % member/2.
% %
% @author Richard O'Keefe % Author: Richard O'Keefe
ord_memberchk(Item, [X1,X2,X3,X4|Xs]) :- ord_memberchk(Item, [X1,X2,X3,X4|Xs]) :-
!, !,
@@ -303,9 +296,9 @@ ord_memberchk(Item, [X1]) :-
Item == X1. Item == X1.
%! ord_subset(+Sub, +Super) is semidet. %% ord_subset(+Sub, +Super) is semidet.
% %
% Is true if all elements of Sub are in Super % Is true if all elements of Sub are in Super
ord_subset([], _). ord_subset([], _).
ord_subset([H1|T1], [H2|T2]) :- ord_subset([H1|T1], [H2|T2]) :-
@@ -319,22 +312,20 @@ ord_subset_(=, _, T1, T2) :-
ord_subset(T1, T2). ord_subset(T1, T2).
%! ord_subtract(+InOSet, +NotInOSet, -Diff) is det. %% ord_subtract(+InOSet, +NotInOSet, -Diff) is det.
% %
% Diff is the set holding all elements of InOSet that are not in % Diff is the set holding all elements of InOSet that are not in
% NotInOSet. % NotInOSet.
ord_subtract(InOSet, NotInOSet, Diff) :- ord_subtract(InOSet, NotInOSet, Diff) :-
oset_diff(InOSet, NotInOSet, Diff). oset_diff(InOSet, NotInOSet, Diff).
%! ord_union(+SetOfSets, -Union) is det. %% ord_union(+SetOfSets, -Union) is det.
% %
% True if Union is the union of all elements in the superset % True if Union is the union of all elements in the superset
% SetOfSets. Each member of SetOfSets must be an ordered set, the % SetOfSets. Each member of SetOfSets must be an ordered set, the
% sets need not be ordered in any way. % sets need not be ordered in any way.
%
% @author Copied from YAP, probably originally by Richard O'Keefe.
ord_union([], []). ord_union([], []).
ord_union([Set|Sets], Union) :- ord_union([Set|Sets], Union) :-
@@ -355,18 +346,18 @@ ord_union_all(N, Sets0, Union, Sets) :-
). ).
%! ord_union(+Set1, +Set2, ?Union) is det. %% ord_union(+Set1, +Set2, ?Union) is det.
% %
% Union is the union of Set1 and Set2 % Union is the union of Set1 and Set2
ord_union(Set1, Set2, Union) :- ord_union(Set1, Set2, Union) :-
oset_union(Set1, Set2, Union). oset_union(Set1, Set2, Union).
%! ord_union(+Set1, +Set2, -Union, -New) is det. %% ord_union(+Set1, +Set2, -Union, -New) is det.
% %
% True iff ord_union(Set1, Set2, Union) and % True iff ord\_union(Set1, Set2, Union) and
% ord_subtract(Set2, Set1, New). % ord\_subtract(Set2, Set1, New).
ord_union([], Set2, Set2, Set2). ord_union([], Set2, Set2, Set2).
ord_union([H|T], Set2, Union, New) :- ord_union([H|T], Set2, Union, New) :-
@@ -390,26 +381,22 @@ ord_union_2([H|T], H2, T2, Union, New) :-
ord_union(Order, H, T, H2, T2, Union, New). ord_union(Order, H, T, H2, T2, Union, New).
%! ord_symdiff(+Set1, +Set2, ?Difference) is det. %% ord_symdiff(+Set1, +Set2, ?Difference) is det.
% %
% Is true when Difference is the symmetric difference of Set1 and % Is true when Difference is the symmetric difference of Set1 and
% Set2. I.e., Difference contains all elements that are not in the % Set2. I.e., Difference contains all elements that are not in the
% intersection of Set1 and Set2. The semantics is the same as the % intersection of Set1 and Set2. The semantics is the same as the
% sequence below (but the actual implementation requires only a % sequence below (but the actual implementation requires only a
% single scan). % single scan).
% %
% == % ord_union(Set1, Set2, Union),
% ord_union(Set1, Set2, Union), % ord_intersection(Set1, Set2, Intersection),
% ord_intersection(Set1, Set2, Intersection), % ord_subtract(Union, Intersection, Difference).
% ord_subtract(Union, Intersection, Difference).
% ==
% %
% For example: % For example:
% %
% ==
% ?- ord_symdiff([1,2], [2,3], X). % ?- ord_symdiff([1,2], [2,3], X).
% X = [1,3]. % X = [1,3].
% ==
ord_symdiff([], Set2, Set2). ord_symdiff([], Set2, Set2).
ord_symdiff([H1|T1], Set2, Difference) :- ord_symdiff([H1|T1], Set2, Difference) :-
@@ -457,7 +444,7 @@ ord_symdiff(>, H1, T1, H2, Set2, [H2|Difference]) :-
*/ */
/** <module> Ordered set manipulation /* Ordered set manipulation
This library defines set operations on sets represented as ordered This library defines set operations on sets represented as ordered
lists. lists.