15.3.422  src/lib/src/priority-queue.api

# priority-queue.api

# Compiled by:
#     src/lib/std/standard.lib

# Api of an imperative priority queue.
#
# -- Allen Leung



###         "The nature of exponentials is that
###          if you extrapolate them far enough
###          you always get a disaster."
###
###                       -- Gordon Moore


# This api is implemented in:
#
#     (INCOMPLETELY!!)  src/lib/src/heap-priority-queue.pkg
#                       src/lib/src/leftist-tree-priority-queue.pkg
#
api Priority_Queue {
    #
    Priority_Queue(X);

    exception EMPTY_PRIORITY_QUEUE;

    from_list:  ((X, X) -> Bool) -> List(X) -> Priority_Queue(X);

    make_priority_queue:       ((X, X) -> Bool)            -> Priority_Queue(X); 
    make_priority_queue':     (((X, X) -> Bool), Int, X)   -> Priority_Queue(X);                # The Int is an expected-size hint.  The final X is a valid-type dummy value for (say) initializing internal vector.

    is_empty:    Priority_Queue(X) -> Bool;
    clear:       Priority_Queue(X) -> Void;
    min:         Priority_Queue(X) -> X;
    delete_min:  Priority_Queue(X) -> X;
    merge:      (Priority_Queue(X), Priority_Queue(X)) -> Priority_Queue(X);
    set:         Priority_Queue(X) -> X -> Void;
    to_list:     Priority_Queue(X) -> List(X);

    merge_into:  { src:  Priority_Queue(X),
                   dst:  Priority_Queue(X)
                 }
                 ->
                 Void;
};