kibi-swipl-linux-x64-gnu 1.0.0

package/lib/swipl/library/hashtable.pl

@@ -0,0 +1,365 @@
+/*  Part of SWI-Prolog
+
+    Author:        Jan Wielemaker
+    E-mail:        J.Wielemaker@vu.nl
+    WWW:           http://www.swi-prolog.org
+    Copyright (c)  2020, VU University Amsterdam
+                         CWI, Amsterdam
+    All rights reserved.
+
+    Redistribution and use in source and binary forms, with or without
+    modification, are permitted provided that the following conditions
+    are met:
+
+    1. Redistributions of source code must retain the above copyright
+       notice, this list of conditions and the following disclaimer.
+
+    2. Redistributions in binary form must reproduce the above copyright
+       notice, this list of conditions and the following disclaimer in
+       the documentation and/or other materials provided with the
+       distribution.
+
+    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+    FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+    COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+    INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+    BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+    LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+    CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+    LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+    ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+    POSSIBILITY OF SUCH DAMAGE.
+*/
+
+:- module(hashtable,
+          [ ht_new/1,                   % --HT
+            ht_is_hashtable/1,          % @HT
+            ht_size/2,                  % +HT, -Size
+
+            ht_put/3,                   % !HT, +Key, +Value
+            ht_update/4,                % +HT, +Key, ?Old, +New
+            ht_put_new/3,               % !HT, +Key, +Value
+            ht_put/5,                   % !HT, +Key, +Value, +IfNew, -Old
+            ht_del/3,                   % !HT, +Key, -Value
+
+            ht_get/3,                   % +HT, +Key, -Value
+            ht_gen/3,                   % +HT, ?Key, ?Value
+            ht_pairs/2,                 % ?HT, ?Pairs
+            ht_keys/2                   % +HT, -Keys
+          ]).
+:- autoload(library(error), [must_be/2]).
+
+/** <module> Hash tables
+
+Hash tables are one of the   many key-value representations available to
+SWI-Prolog.
+
+This module implements a hash table   as a _mutable_ and _backtrackable_
+data structure. The hash table is implemented  as a _closed hash table_,
+where the _buckets_ array  is  implemented   using  an  unbounded  arity
+compound term. Elements in this array are manipulated using setarg/3.
+
+Hash tables allow for any Prolog data   types  as keys or values, except
+that the key cannot be a  variable.   Applications  that require a plain
+variable as key can do so by  wrapping   all  keys  in a compound, e.g.,
+k(Var).
+*/
+
+/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+Data structure
+
+    ht(Load, Size, Table)
+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */
+
+%!  ht_new(--HT)
+%
+%   Create a new hash table.
+
+ht_new(ht(0,0,[](_))).
+
+%!  ht_is_hashtable(@HT) is semidet.
+%
+%   True when HT is a hash table.
+
+ht_is_hashtable(HT) :-
+    nonvar(HT),
+    HT = ht(Load, Size, Buckets),
+    integer(Load),
+    integer(Size),
+    compound_name_arity(Buckets, [], Arity),
+    Arity =:= Size*2+1.
+
+%!  ht_size(+HT, -Count) is det.
+%
+%   True when Size is the number of key-value pairs in HT.
+
+ht_size(ht(Count, _Size, _Buckets), Count).
+
+%!  ht_put(!HT, +Key, +Value) is det.
+%
+%   Add a Key-Value to HT. The binding is undone on backtracking.
+
+ht_put(HT, Key, Value) :-
+    must_be(nonvar, Key),
+    ht_put(HT, Key, Value, _, _, _).
+
+%!  ht_put_new(!HT, +Key, +Value) is semidet.
+%
+%   As ht_put/3, but fails if Key is   already in HT instead of updating
+%   the associated value.
+
+ht_put_new(HT, Key, Value) :-
+    must_be(nonvar, Key),
+    ht_put(HT, Key, Value, _, _, true).
+
+%!  ht_update(+HT, +Key, ?Old, +New) is semidet.
+%
+%   True when HT holds Key-Old before and  Key-New after this call. Note
+%   that it is possible to update  to   a  variable  and the instantiate
+%   this. For example, a word-count update could be implemented as:
+%
+%   ```
+%   update_word_count(HT, Word) :-
+%       (   ht_update(HT, Word, Old, New)
+%       ->  New is Old+1
+%       ;   ht_put(HT, Word, 1)
+%       ).
+%   ```
+
+ht_update(HT, Key, Old, New) :-
+    must_be(nonvar, Key),
+    ht_put(HT, Key, New, _, Old, false).
+
+%!  ht_put(!HT, +Key, +Value, +IfNew, -Old) is det.
+%
+%   Add Key-Value to HT. Old is unified   with  the old value associated
+%   with Key or, if Key  is  new,  with   IfNew.  This  can  be  used to
+%   bootstrap managing a list of values, e.g.
+%
+%       ht_put_list(HT, Key, Value) :-
+%           ht_put(HT, Key, [Value|Tail], [], Tail).
+
+ht_put(HT, Key, Value, IfNew, Old) :-
+    must_be(nonvar, Key),
+    ht_put(HT, Key, Value, IfNew, Old, _).
+
+ht_put(HT, Key, Value, IfNew, Old, IsNew) :-
+    HT = ht(Load, Size, Buckets),
+    (   Load >= Size//2
+    ->  ht_resize(HT),
+        ht_put(HT, Key, Value, IfNew, Old, IsNew)
+    ;   variant_hash(Key, I0),
+        I is I0 mod Size,
+        put_(Buckets, I, Size, Key, Old, IfNew, Value, IsNew),
+        (   IsNew == true
+        ->  Load2 is Load+1,
+            setarg(1, HT, Load2)
+        ;   true
+        )
+    ).
+
+put_(Buckets, I, Size, Key, Old, IfNew, Value, IsNew) :-
+    ht_kv(Buckets, I, K, V),
+    (   var(K)
+    ->  IsNew = true,
+        Old = IfNew,
+        K = Key,
+        V = Value
+    ;   K == Key
+    ->  IsNew = false,
+        Old = V,
+        ht_put_v(Buckets, I, Value)
+    ;   I2 is (I+1) mod Size,
+        put_(Buckets, I2, Size, Key, Old, IfNew, Value, IsNew)
+    ).
+
+ht_resize(HT) :-
+    HT = ht(_Load, Size, Buckets),
+    NewSize is max(4, Size*2),
+    NewArity is NewSize*2+1,
+    compound_name_arity(NewBuckets, [], NewArity),
+    copy_members(0, Size, Buckets, NewSize, NewBuckets),
+    setarg(2, HT, NewSize),
+    setarg(3, HT, NewBuckets).
+
+copy_members(I, OSize, OBuckets, NSize, NBuckets) :-
+    I < OSize,
+    !,
+    ht_kv(OBuckets, I, K, V),
+    (   nonvar(K)
+    ->  variant_hash(K, I0),
+        NI is I0 mod NSize,
+        copy_(NBuckets, NI, NSize, K, V)
+    ;   true
+    ),
+    I2 is I+1,
+    copy_members(I2, OSize, OBuckets, NSize, NBuckets).
+copy_members(_, _, _, _, _).
+
+copy_(Buckets, I, Size, Key, Value) :-
+    ht_kv(Buckets, I, K, V),
+    (   var(K)
+    ->  K = Key,
+        V = Value
+    ;   I2 is (I+1) mod Size,
+        copy_(Buckets, I2, Size, Key, Value)
+    ).
+
+
+%!  ht_del(!HT, +Key, -Value) is semidet.
+%
+%   Delete Key-Value from HT. Fails if  Key   does  not  appear in HT or
+%   Value does not unify with the old associated value.
+
+ht_del(HT, Key, Value) :-
+    must_be(nonvar, Key),
+    HT = ht(Load, Size, Buckets),
+    Load > 0,
+    variant_hash(Key, I0),
+    I is I0 mod Size,
+    del_(Buckets, I, Size, Key, Value),
+    Load2 is Load - 1,
+    setarg(1, HT, Load2).
+
+del_(Buckets, I, Size, Key, Value) :-
+    ht_kv(Buckets, I, K, V),
+    (   var(K)
+    ->  fail
+    ;   K == Key
+    ->  V = Value,
+        ht_put_kv(Buckets, I, _, _),
+        del_shift(Buckets, I, I, Size)
+    ;   I2 is (I+1) mod Size,
+        del_(Buckets, I2, Size, Key, Value)
+    ).
+
+del_shift(Buckets, I0, J, Size) :-
+    I is (I0+1) mod Size,
+    ht_kv(Buckets, I, K, V),
+    (   var(K)
+    ->  true
+    ;   variant_hash(K, Hash),
+        R is Hash mod Size,
+        (   (   I >= R, R > J
+            ;   R > J, J > I
+            ;   J > I, I >= R
+            )
+        ->  del_shift(Buckets, I, J, Size)
+        ;   ht_put_kv(Buckets, J, K, V),
+            ht_put_kv(Buckets, I, _, _),
+            del_shift(Buckets, I, I, Size)
+        )
+    ).
+
+
+%!  ht_get(+HT, +Key, -Value) is semidet.
+%
+%   True when Key is in HT and associated with Value.
+
+ht_get(ht(Load, Size, Buckets), Key, Value) :-
+    Load > 0,
+    must_be(nonvar, Key),
+    variant_hash(Key, I0),
+    I is I0 mod Size,
+    get_(Buckets, I, Size, Key, Value).
+
+get_(Buckets, I, Size, Key, Value) :-
+    ht_kv(Buckets, I, K, V),
+    (   Key == K
+    ->  Value = V
+    ;   nonvar(K)
+    ->  I2 is (I+1) mod Size,
+        get_(Buckets, I2, Size, Key, Value)
+    ).
+
+ht_k(Buckets, I, K) :-
+    IK is I*2+1,
+    arg(IK, Buckets, K).
+
+ht_kv(Buckets, I, K, V) :-
+    IK is I*2+1,
+    IV is IK+1,
+    arg(IK, Buckets, K),
+    arg(IV, Buckets, V).
+
+ht_put_kv(Buckets, I, K, V) :-
+    IK is I*2+1,
+    IV is IK+1,
+    setarg(IK, Buckets, K),
+    setarg(IV, Buckets, V).
+
+ht_put_v(Buckets, I, V) :-
+    IV is I*2+2,
+    setarg(IV, Buckets, V).
+
+%!  ht_gen(+HT, ?Key, ?Value) is nondet.
+%
+%   True when Key-Value is in HT.   Pairs are enumerated on backtracking
+%   using the hash table order.
+
+ht_gen(HT, Key, Value) :-
+    HT = ht(_, Size, Buckets),
+    End is Size - 1,
+    between(0, End, I),
+    ht_kv(Buckets, I, K, V),
+    nonvar(K),
+    K = Key,
+    V = Value.
+
+%!  ht_pairs(?HT, ?Pairs) is det.
+%
+%   True when Pairs and HT represent the  same association. When used in
+%   mode (+,-), Pairs is an ordered set.
+
+ht_pairs(HT, Pairs) :-
+    ht_is_hashtable(HT),
+    !,
+    HT = ht(_Load, Size, Buckets),
+    pairs_(0, Size, Buckets, Pairs0),
+    sort(Pairs0, Pairs).
+ht_pairs(HT, Pairs) :-
+    must_be(list(pair), Pairs),
+    ht_new(HT),
+    ht_fill(Pairs, HT).
+
+pairs_(I, Size, Buckets, Pairs) :-
+    (   I < Size
+    ->  ht_kv(Buckets, I, K, V),
+        (   nonvar(K)
+        ->  Pairs = [K-V|T],
+            I2 is I+1,
+            pairs_(I2, Size, Buckets, T)
+        ;   I2 is I+1,
+            pairs_(I2, Size, Buckets, Pairs)
+        )
+    ;   Pairs = []
+    ).
+
+ht_fill([], _).
+ht_fill([K-V|T], HT) :-
+    ht_put(HT, K, V),
+    ht_fill(T, HT).
+
+%!  ht_keys(+HT, -Keys) is det.
+%
+%   True when Keys is an ordered set of all keys in HT.
+
+ht_keys(HT, Keys) :-
+    HT = ht(_Load, Size, Buckets),
+    keys_(0, Size, Buckets, Keys0),
+    sort(Keys0, Keys).
+
+keys_(I, Size, Buckets, Keys) :-
+    (   I < Size
+    ->  ht_k(Buckets, I, K),
+        (   nonvar(K)
+        ->  Keys = [K|T],
+            I2 is I+1,
+            keys_(I2, Size, Buckets, T)
+        ;   I2 is I+1,
+            keys_(I2, Size, Buckets, Keys)
+        )
+    ;   Keys = []
+    ).

package/lib/swipl/library/heaps.pl

@@ -0,0 +1,252 @@
+/*  Part of SWI-Prolog
+
+    Author:        Lars Buitinck
+    E-mail:        larsmans@gmail.com
+    WWW:           http://www.swi-prolog.org
+    Copyright (c)  2006-2015, Lars Buitinck
+    All rights reserved.
+
+    Redistribution and use in source and binary forms, with or without
+    modification, are permitted provided that the following conditions
+    are met:
+
+    1. Redistributions of source code must retain the above copyright
+       notice, this list of conditions and the following disclaimer.
+
+    2. Redistributions in binary form must reproduce the above copyright
+       notice, this list of conditions and the following disclaimer in
+       the documentation and/or other materials provided with the
+       distribution.
+
+    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+    FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+    COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+    INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+    BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+    LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+    CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+    LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+    ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+    POSSIBILITY OF SUCH DAMAGE.
+*/
+
+:- module(heaps,
+          [ add_to_heap/4,              % +Heap0, +Key, ?Value, -Heap
+            delete_from_heap/4,         % +Heap0, -Key, +Value, -Heap
+            empty_heap/1,               % +Heap
+            get_from_heap/4,            % ?Heap0, ?Key, ?Value, -Heap
+            heap_size/2,                % +Heap, -Size:int
+            heap_to_list/2,             % +Heap, -List:list
+            is_heap/1,                  % +Term
+            list_to_heap/2,             % +List:list, -Heap
+            merge_heaps/3,              % +Heap0, +Heap1, -Heap
+            min_of_heap/3,              % +Heap, ?Key, ?Value
+            min_of_heap/5,              % +Heap, ?Key1, ?Value1,
+                                        %        ?Key2, ?Value2
+            singleton_heap/3            % ?Heap, ?Key, ?Value
+          ]).
+
+/** <module> heaps/priority queues
+ *
+ * Heaps are data structures that return the entries inserted into them in an
+ * ordered fashion, based on a priority. This makes them the data structure of
+ * choice for implementing priority queues, a central element of algorithms such
+ * as best-first or A* search and Kruskal's minimum-spanning-tree algorithm.
+ *
+ * This module implements min-heaps, meaning that key-value items are retrieved in
+ * ascending order of key. In other words, the key determines the priority.  It
+ * was designed to be compatible with the SICStus Prolog library module of the
+ * same name. merge_heaps/3 and singleton_heap/3 are SWI-specific extension. The
+ * portray_heap/1 predicate is not implemented.
+ *
+ * Although the values can be arbitrary Prolog terms, the keys determine the
+ * priority, so keys must be ordered by @=</2. This means that variables can be
+ * used as keys, but binding them in between heap operations may change the
+ * ordering. It also means that rational terms (cyclic trees), for which standard
+ * order is not well-defined, cannot be used as keys.
+ *
+ * The current version implements pairing heaps. These support insertion and
+ * merging both in constant time, deletion of the minimum in logarithmic amortized
+ * time (though delete-min, i.e., get_from_heap/3, takes linear time in the worst
+ * case).
+ *
+ * @author Lars Buitinck
+ */
+
+/*
+ * Heaps are represented as heap(H,Size) terms, where H is a pairing heap and
+ * Size is an integer. A pairing heap is either nil or a term
+ * t(X,PrioX,Sub) where Sub is a list of pairing heaps t(Y,PrioY,Sub) s.t.
+ * PrioX @< PrioY. See predicate is_heap/2, below.
+ */
+
+%!  add_to_heap(+Heap0, +Key, ?Value, -Heap) is semidet.
+%
+%   Adds Value with priority Key  to   Heap0,  constructing a new
+%   heap in Heap.
+
+add_to_heap(heap(Q0,M),P,X,heap(Q1,N)) :-
+    meld(Q0,t(X,P,[]),Q1),
+    N is M+1.
+
+%!  delete_from_heap(+Heap0, -Key, +Value, -Heap) is semidet.
+%
+%   Deletes Value from Heap0, leaving its priority in Key and the
+%   resulting data structure in Heap.   Fails if Value is not found in
+%   Heap0.
+%
+%   @bug This predicate is extremely inefficient and exists only for
+%        SICStus compatibility.
+
+delete_from_heap(Q0,P,X,Q) :-
+    get_from_heap(Q0,P,X,Q),
+    !.
+delete_from_heap(Q0,Px,X,Q) :-
+    get_from_heap(Q0,Py,Y,Q1),
+    delete_from_heap(Q1,Px,X,Q2),
+    add_to_heap(Q2,Py,Y,Q).
+
+%!  empty_heap(?Heap) is semidet.
+%
+%   True if Heap is an empty heap. Complexity: constant.
+
+empty_heap(heap(nil,0)).
+
+%!  singleton_heap(?Heap, ?Key, ?Value) is semidet.
+%
+%   True if Heap is a heap with the single element Key-Value.
+%
+%   Complexity: constant.
+
+singleton_heap(heap(t(X,P,[]), 1), P, X).
+
+%!  get_from_heap(?Heap0, ?Key, ?Value, -Heap) is semidet.
+%
+%   Retrieves the minimum-priority  pair   Key-Value  from Heap0.
+%   Heap is Heap0 with that pair removed.   Complexity:  logarithmic
+%   (amortized), linear in the worst case.
+
+get_from_heap(heap(t(X,P,Sub),M), P, X, heap(Q,N)) :-
+    pairing(Sub,Q),
+    N is M-1.
+
+%!  heap_size(+Heap, -Size:int) is det.
+%
+%   Determines the number of elements in Heap. Complexity: constant.
+
+heap_size(heap(_,N),N).
+
+%!  heap_to_list(+Heap, -List:list) is det.
+%
+%   Constructs a list List  of   Key-Value  terms, ordered by
+%   (ascending) priority. Complexity: O(N log N).
+
+heap_to_list(Q,L) :-
+    to_list(Q,L).
+to_list(heap(nil,0),[]) :- !.
+to_list(Q0,[P-X|Xs]) :-
+    get_from_heap(Q0,P,X,Q),
+    heap_to_list(Q,Xs).
+
+%!  is_heap(+X) is semidet.
+%
+%   Returns true if X is a heap.  Validates the consistency of the
+%   entire heap. Complexity: linear.
+
+is_heap(V) :-
+    var(V), !, fail.
+is_heap(heap(Q,N)) :-
+    integer(N),
+    nonvar(Q),
+    (   Q == nil
+    ->  N == 0
+    ;   N > 0,
+        Q = t(_,MinP,Sub),
+        are_pairing_heaps(Sub, MinP)
+    ).
+
+% True iff 1st arg is a pairing heap with min key @=< 2nd arg,
+% where min key of nil is logically @> any term.
+is_pairing_heap(V, _) :-
+    var(V),
+    !,
+    fail.
+is_pairing_heap(nil, _).
+is_pairing_heap(t(_,P,Sub), MinP) :-
+    MinP @=< P,
+    are_pairing_heaps(Sub, P).
+
+% True iff 1st arg is a list of pairing heaps, each with min key @=< 2nd arg.
+are_pairing_heaps(V, _) :-
+    var(V),
+    !,
+    fail.
+are_pairing_heaps([], _).
+are_pairing_heaps([Q|Qs], MinP) :-
+    is_pairing_heap(Q, MinP),
+    are_pairing_heaps(Qs, MinP).
+
+%!  list_to_heap(+List:list, -Heap) is det.
+%
+%   If List is a list of  Key-Value  terms, constructs a heap
+%   out of List. Complexity: linear.
+
+list_to_heap(Xs,Q) :-
+    empty_heap(Empty),
+    list_to_heap(Xs,Empty,Q).
+
+list_to_heap([],Q,Q).
+list_to_heap([P-X|Xs],Q0,Q) :-
+    add_to_heap(Q0,P,X,Q1),
+    list_to_heap(Xs,Q1,Q).
+
+%!  min_of_heap(+Heap, ?Key, ?Value) is semidet.
+%
+%   Unifies Value with  the  minimum-priority   element  of  Heap  and
+%   Key with its priority value. Complexity: constant.
+
+min_of_heap(heap(t(X,P,_),_), P, X).
+
+%!  min_of_heap(+Heap, ?Key1, ?Value1, ?Key2, ?Value2) is semidet.
+%
+%   Gets the two minimum-priority elements from Heap. Complexity: logarithmic
+%   (amortized).
+%
+%   @bug This predicate is extremely inefficient and exists for compatibility
+%        with earlier implementations of this library and SICStus
+%        compatibility.  It performs a linear amount of work in the worst case
+%        that a following get_from_heap has to re-do.
+
+min_of_heap(Q,Px,X,Py,Y) :-
+    get_from_heap(Q,Px,X,Q0),
+    min_of_heap(Q0,Py,Y).
+
+%!  merge_heaps(+Heap0, +Heap1, -Heap) is det.
+%
+%   Merge the two heaps Heap0 and Heap1 in Heap. Complexity: constant.
+
+merge_heaps(heap(L,K),heap(R,M),heap(Q,N)) :-
+    meld(L,R,Q),
+    N is K+M.
+
+
+% Merge two pairing heaps according to the pairing heap definition.
+meld(nil,Q,Q) :- !.
+meld(Q,nil,Q) :- !.
+meld(L,R,Q) :-
+    L = t(X,Px,SubL),
+    R = t(Y,Py,SubR),
+    (   Px @< Py
+    ->  Q = t(X,Px,[R|SubL])
+    ;   Q = t(Y,Py,[L|SubR])
+    ).
+
+% "Pair up" (recursively meld) a list of pairing heaps.
+pairing([], nil).
+pairing([Q], Q) :- !.
+pairing([Q0,Q1|Qs], Q) :-
+    meld(Q0, Q1, Q2),
+    pairing(Qs, Q3),
+    meld(Q2, Q3, Q).