Add documentation
This commit is contained in:
Vítor Santos Costa
@@ -1,9 +1,12 @@
|
||||
% This file has been included as an YAP library by Vitor Santos Costa, 1999
|
||||
|
||||
% File : HEAPS.PL
|
||||
% Author : R.A.O'Keefe
|
||||
% Updated: 29 November 1983
|
||||
% Purpose: Implement heaps in Prolog.
|
||||
/**
|
||||
* @file heaps.yap
|
||||
* @author R.A.O'Keefe, included as an YAP library by Vitor Santos Costa, 1999.
|
||||
* @date 29 November 1983
|
||||
*
|
||||
* @brief Implement heaps in Prolog.
|
||||
*
|
||||
*
|
||||
*/
|
||||
|
||||
:- module(heaps,[
|
||||
add_to_heap/4, % Heap x Key x Datum -> Heap
|
||||
@@ -17,7 +20,7 @@
|
||||
]).
|
||||
|
||||
|
||||
/** @defgroup Heaps Heaps
|
||||
/** @defgroup heaps Heaps
|
||||
@ingroup library
|
||||
@{
|
||||
|
||||
@@ -33,18 +36,24 @@ there will be, let alone what they are.
|
||||
The following heap manipulation routines are available once included
|
||||
with the `use_module(library(heaps))` command.
|
||||
|
||||
|
||||
*/
|
||||
- add_to_heap/4
|
||||
- empty_heap/1
|
||||
- get_from_heap/4
|
||||
- heap_size/2
|
||||
- heap_to_list/2
|
||||
- list_to_heap/2
|
||||
- min_of_heap/3
|
||||
- min_of_heap/5
|
||||
|
||||
|
||||
/* A heap is a labelled binary tree where the key of each node is less
|
||||
than or equal to the keys of its sons. The point of a heap is that
|
||||
we can keep on adding new elements to the heap and we can keep on
|
||||
taking out the minimum element. If there are N elements total, the
|
||||
total time is O(NlgN). If you know all the elements in advance, you
|
||||
are better off doing a merge-sort, but this file is for when you
|
||||
want to do say a best-first search, and have no idea when you start
|
||||
how many elements there will be, let alone what they are.
|
||||
A heap is a labelled binary tree where the key of each node is less
|
||||
than or equal to the keys of its sons. The point of a heap is that
|
||||
we can keep on adding new elements to the heap and we can keep on
|
||||
taking out the minimum element. If there are N elements total, the
|
||||
total time is O(NlgN). If you know all the elements in advance, you
|
||||
are better off doing a merge-sort, but this file is for when you want
|
||||
to do say a best-first search, and have no idea when you start how
|
||||
many elements there will be, let alone what they are.
|
||||
|
||||
A heap is represented as a triple t(N, Free, Tree) where N is the
|
||||
number of elements in the tree, Free is a list of integers which
|
||||
@@ -70,75 +79,6 @@ with the `use_module(library(heaps))` command.
|
||||
|
||||
|
||||
|
||||
*/
|
||||
|
||||
/**
|
||||
|
||||
|
||||
@pred add_to_heap(+ _Heap_,+ _key_,+ _Datum_,- _NewHeap_)
|
||||
|
||||
|
||||
Inserts the new _Key-Datum_ pair into the heap. The insertion is not
|
||||
stable, that is, if you insert several pairs with the same _Key_ it
|
||||
is not defined which of them will come out first, and it is possible for
|
||||
any of them to come out first depending on the history of the heap.
|
||||
|
||||
*/
|
||||
/** @pred empty_heap(? _Heap_)
|
||||
|
||||
|
||||
Succeeds if _Heap_ is an empty heap.
|
||||
|
||||
|
||||
*/
|
||||
/** @pred get_from_heap(+ _Heap_,- _key_,- _Datum_,- _Heap_)
|
||||
|
||||
|
||||
Returns the _Key-Datum_ pair in _OldHeap_ with the smallest
|
||||
_Key_, and also a _Heap_ which is the _OldHeap_ with that
|
||||
pair deleted.
|
||||
|
||||
|
||||
*/
|
||||
/** @pred heap_size(+ _Heap_, - _Size_)
|
||||
|
||||
|
||||
Reports the number of elements currently in the heap.
|
||||
|
||||
|
||||
*/
|
||||
/** @pred heap_to_list(+ _Heap_, - _List_)
|
||||
|
||||
|
||||
Returns the current set of _Key-Datum_ pairs in the _Heap_ as a
|
||||
_List_, sorted into ascending order of _Keys_.
|
||||
|
||||
|
||||
*/
|
||||
/** @pred list_to_heap(+ _List_, - _Heap_)
|
||||
|
||||
|
||||
Takes a list of _Key-Datum_ pairs (such as keysort could be used to sort)
|
||||
and forms them into a heap.
|
||||
|
||||
|
||||
*/
|
||||
/** @pred min_of_heap(+ _Heap_, - _Key1_, - _Datum1_,
|
||||
- _Key2_, - _Datum2_)
|
||||
|
||||
Returns the smallest (Key1) and second smallest (Key2) pairs in the
|
||||
heap, without deleting them.
|
||||
|
||||
|
||||
|
||||
*/
|
||||
/** @pred min_of_heap(+ _Heap_, - _Key_, - _Datum_)
|
||||
|
||||
|
||||
Returns the Key-Datum pair at the top of the heap (which is of course
|
||||
the pair with the smallest Key), but does not remove it from the heap.
|
||||
|
||||
|
||||
*/
|
||||
|
||||
/*
|
||||
@@ -206,7 +146,7 @@ sort2(Key1, Datum1, Key2, Datum2, Key2, Datum2, Key1, Datum1).
|
||||
|
||||
|
||||
|
||||
%% @pred get_from_heap(OldHeap, Key, Datum, NewHeap)
|
||||
%% @pred @pred get_from_heap(+ _Heap_,- _key_,- _Datum_,- _Heap_)
|
||||
%
|
||||
% returns the Key-Datum pair in OldHeap with the smallest Key, and
|
||||
% also a New Heap which is the Old Heap with that pair deleted.
|
||||
@@ -239,7 +179,7 @@ repair_heap(t, t, t, 1) :- !.
|
||||
|
||||
|
||||
|
||||
%% @pred heap_size(Heap, Size)
|
||||
%% @pred heap_size(+ _Heap_, - _Size_)
|
||||
%
|
||||
% reports the number of elements currently in the heap.
|
||||
|
||||
@@ -247,7 +187,7 @@ heap_size(t(Size,_,_), Size).
|
||||
|
||||
|
||||
|
||||
%% @pred heap_to_list(Heap, List)
|
||||
%% @pred heap_to_list(+ _Heap_, - _List_)
|
||||
%
|
||||
% returns the current set of Key-Datum pairs in the Heap as a
|
||||
% List, sorted into ascending order of Keys. This is included
|
||||
@@ -280,7 +220,7 @@ heap_tree_to_list(T, [], T).
|
||||
|
||||
|
||||
|
||||
%% @pred list_to_heap(List, Heap)
|
||||
%% @pred list_to_heap(+ _List_, - _Heap_)
|
||||
%
|
||||
% takes a list of Key-Datum pairs (such as keysort could be used to
|
||||
% sort) and forms them into a heap. We could do that a wee bit
|
||||
@@ -307,15 +247,22 @@ list_to_heap([Key-Datum|Rest], M, OldTree, Heap) :-
|
||||
% course the pair with the smallest Key), but does not remove it
|
||||
% from the heap. It fails if the heap is empty.
|
||||
|
||||
%% @pred min_of_heap(Heap, Key1, Datum1, Key2, Datum2)
|
||||
|
||||
/** @pred min_of_heap(+ _Heap_, - _Key_, - _Datum_)
|
||||
|
||||
|
||||
Returns the Key-Datum pair at the top of the heap (which is of course
|
||||
the pair with the smallest Key), but does not remove it from the heap.
|
||||
*/
|
||||
min_of_heap(t(_,_,t(Key,Datum,_,_)), Key, Datum).
|
||||
|
||||
|
||||
%% @pred @pred min_of_heap(+ _Heap_, - _Key1_, - _Datum1_,
|
||||
- _Key2_, - _Datum2_)
|
||||
%
|
||||
% returns the smallest (Key1) and second smallest (Key2) pairs in
|
||||
% the heap, without deleting them. It fails if the heap does not
|
||||
% have at least two elements.
|
||||
|
||||
min_of_heap(t(_,_,t(Key,Datum,_,_)), Key, Datum).
|
||||
|
||||
|
||||
min_of_heap(t(_,_,t(Key1,Datum1,Lson,Rson)), Key1, Datum1, Key2, Datum2) :-
|
||||
min_of_heap(Lson, Rson, Key2, Datum2).
|
||||
|
||||
@@ -325,6 +272,11 @@ min_of_heap(t(Ka,_Da,_,_), t(Kb,Db,_,_), Kb, Db) :-
|
||||
min_of_heap(t(Ka,Da,_,_), _, Ka, Da).
|
||||
min_of_heap(t, t(Kb,Db,_,_), Kb, Db).
|
||||
|
||||
/** @pred empty_heap(? _Heap_)
|
||||
|
||||
|
||||
Succeeds if _Heap_ is an empty heap.
|
||||
*/
|
||||
empty_heap(t(0,[],t)).
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user