boost-react-native-bundle

<html> <head> <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> <title>Concepts & Interface</title> <link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css"> <meta name="generator" content="DocBook XSL Stylesheets V1.78.1"> <link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset"> <link rel="up" href="../heap.html" title="Chapter 13. Boost.Heap"> <link rel="prev" href="../heap.html" title="Chapter 13. Boost.Heap"> <link rel="next" href="data_structures.html" title="Data Structures"> </head> <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> <table cellpadding="2" width="100%"><tr> <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td> <td align="center"><a href="../../../index.html">Home</a></td> <td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td> <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> <td align="center"><a href="../../../more/index.htm">More</a></td> </tr></table> <hr> <div class="spirit-nav"> <a accesskey="p" href="../heap.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../heap.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="data_structures.html"><img src="../../../doc/src/images/next.png" alt="Next"></a> </div> <div class="section"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> <a name="heap.concepts"></a><a class="link" href="concepts.html" title="Concepts & Interface">Concepts & Interface</a> </h2></div></div></div> <div class="toc"><dl class="toc"> <dt><a href="concepts.html#heap.concepts.basic">Basic Priority Queue Interface</a></dt> <dt><a href="concepts.html#heap.concepts.iterators">Priority Queue Iterators</a></dt> <dt><a href="concepts.html#heap.concepts.comparing">Comparing Priority Queues & Equivalence</a></dt> <dt><a href="concepts.html#heap.concepts.merge">Merging Priority Queues</a></dt> <dt><a href="concepts.html#heap.concepts.mutability">Mutability</a></dt> <dt><a href="concepts.html#heap.concepts.stability">Stability</a></dt> </dl></div> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> <a name="heap.concepts.basic"></a><a class="link" href="concepts.html#heap.concepts.basic" title="Basic Priority Queue Interface">Basic Priority Queue Interface</a> </h3></div></div></div> Priority queues are queues of objects, that are ordered by their priority. They support the operations of adding nodes to the data structure, accessing the top element (the element with the highest priority), and removing the top element. <div class="note"><table border="0" summary="Note"> <tr> <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../doc/src/images/note.png"></td> <th align="left">Note</th> </tr> <tr><td align="left" valign="top"> <code class="literal">boost.heap</code> implements priority queues as max-heaps to be consistent with the STL heap functions. This is in contrast to the typical textbook design, which uses min-heaps. </td></tr> </table></div> <h6> <a name="heap.concepts.basic.h0"></a> <a name="heap.concepts.basic.synopsis"></a><a class="link" href="concepts.html#heap.concepts.basic.synopsis">Synopsis</a> </h6> <pre class="programlisting">template <typename T, class ...Options> class priority_queue { // types typedef T value_type; typedef unspecified size_type; typedef unspecified difference_type; typedef unspecified allocator_type; typedef unspecified value_compare; typedef unspecified reference; typedef unspecified const_reference; typedef unspecified pointer; typedef unspecified const_pointer; // construct/copy/destruct explicit priority_queue(value_compare const & = value_compare()); priority_queue(priority_queue const &); priority_queue& operator=(priority_queue const &); priority_queue(priority_queue &&); // move semantics (C++11 only) priority_queue& operator=(priority_queue &&); // move semantics (C++11 only) // public member functions unspecified push(const_reference); // push new element to heap template<class... Args> void emplace(Args &&...); // push new element to heap, C++11 only const_reference top() const; // return top element void pop(); // remove top element void clear(); // clear heap size_type size() const; // number of elements bool empty() const; // priority queue is empty allocator_type get_allocator(void) const; // return allocator size_type max_size(void) const; // maximal possible size void reserve(size_type); // reserve space, only available if (has_reserve == true) // heap equivalence template<typename HeapType> bool operator==(HeapType const &) const; template<typename HeapType> bool operator!=(HeapType const &) const; // heap comparison template<typename HeapType> bool operator<(HeapType const &) const; template<typename HeapType> bool operator>(HeapType const &) const; template<typename HeapType> bool operator>=(HeapType const &) const; template<typename HeapType> bool operator<=(HeapType const &) const; // public data members static const bool constant_time_size; // size() has constant complexity static const bool has_ordered_iterators; // priority queue has <a class="link" href="concepts.html#heap.concepts.iterators" title="Priority Queue Iterators">ordered iterators</a> static const bool is_mergable; // priority queue is efficiently <a class="link" href="concepts.html#heap.concepts.merge" title="Merging Priority Queues">mergable</a> static const bool is_stable; // priority queue has a <a class="link" href="concepts.html#heap.concepts.stability" title="Stability">stable heap order</a> static const bool has_reserve; // priority queue has a reserve() member }; </pre> <h6> <a name="heap.concepts.basic.h1"></a> <a name="heap.concepts.basic.example"></a><a class="link" href="concepts.html#heap.concepts.basic.example">Example</a> </h6> <pre class="programlisting">// PriorityQueue is expected to be a max-heap of integer values template <typename PriorityQueue> void basic_interface(void) { PriorityQueue pq; pq.push(2); pq.push(3); pq.push(1); cout << "Priority Queue: popped elements" << endl; cout << pq.top() << " "; // 3 pq.pop(); cout << pq.top() << " "; // 2 pq.pop(); cout << pq.top() << " "; // 1 pq.pop(); cout << endl; } </pre> </div> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> <a name="heap.concepts.iterators"></a><a class="link" href="concepts.html#heap.concepts.iterators" title="Priority Queue Iterators">Priority Queue Iterators</a> </h3></div></div></div> <div class="toc"><dl class="toc"><dt><a href="concepts.html#heap.concepts.iterators.ordered_iterators">Ordered Iterators</a></dt></dl></div> <h6> <a name="heap.concepts.iterators.h0"></a> <a name="heap.concepts.iterators.synopsis"></a><a class="link" href="concepts.html#heap.concepts.iterators.synopsis">Synopsis</a> </h6> <pre class="programlisting">class iteratable_heap_interface { public: // types typedef unspecified iterator; typedef unspecified const_iterator; typedef unspecified ordered_iterator; // public member functions iterator begin(void) const; iterator end(void) const; ordered_iterator ordered_begin(void) const; ordered_iterator ordered_end(void) const; }; </pre> Priority queues provide iterators, that can be used to traverse their elements. All heap iterators are const_iterators, that means they cannot be used to modify the values, because changing the value of a heap node may corrupt the heap order. Details about modifying heap nodes are described in the section about the <a class="link" href="concepts.html#heap.concepts.mutability" title="Mutability">mutability interface</a>. Iterators do not visit heap elements in any specific order. Unless otherwise noted, all non-const heap member functions invalidate iterators, while all const member functions preserve the iterator validity. <div class="note"><table border="0" summary="Note"> <tr> <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../doc/src/images/note.png"></td> <th align="left">Note</th> </tr> <tr><td align="left" valign="top"> Some implementations require iterators, that contain a set of elements, that are discovered, but not visited. Therefore copying iterators can be inefficient and should be avoided. </td></tr> </table></div> <h6> <a name="heap.concepts.iterators.h1"></a> <a name="heap.concepts.iterators.example"></a><a class="link" href="concepts.html#heap.concepts.iterators.example">Example</a> </h6> <pre class="programlisting">// PriorityQueue is expected to be a max-heap of integer values template <typename PriorityQueue> void iterator_interface(void) { PriorityQueue pq; pq.push(2); pq.push(3); pq.push(1); typename PriorityQueue::iterator begin = pq.begin(); typename PriorityQueue::iterator end = pq.end(); cout << "Priority Queue: iteration" << endl; for (typename PriorityQueue::iterator it = begin; it != end; ++it) cout << *it << " "; // 1, 2, 3 in unspecified order cout << endl; } </pre> <div class="section"> <div class="titlepage"><div><div><h4 class="title"> <a name="heap.concepts.iterators.ordered_iterators"></a><a class="link" href="concepts.html#heap.concepts.iterators.ordered_iterators" title="Ordered Iterators">Ordered Iterators</a> </h4></div></div></div> Except for <code class="computeroutput"><a class="link" href="../boost/heap/priority_queue.html" title="Class template priority_queue">boost::heap::priority_queue</a></code> all <code class="literal">boost.heap</code> data structures support ordered iterators, which visit all elements of the heap in heap-order. The implementation of these <code class="literal">ordered_iterator</code>s requires some internal bookkeeping, so iterating the a heap in heap order has an amortized complexity of O(N*log(N)). <h6> <a name="heap.concepts.iterators.ordered_iterators.h0"></a> <a name="heap.concepts.iterators.ordered_iterators.example"></a><a class="link" href="concepts.html#heap.concepts.iterators.ordered_iterators.example">Example</a> </h6> <pre class="programlisting">// PriorityQueue is expected to be a max-heap of integer values template <typename PriorityQueue> void ordered_iterator_interface(void) { PriorityQueue pq; pq.push(2); pq.push(3); pq.push(1); typename PriorityQueue::ordered_iterator begin = pq.ordered_begin(); typename PriorityQueue::ordered_iterator end = pq.ordered_end(); cout << "Priority Queue: ordered iteration" << endl; for (typename PriorityQueue::ordered_iterator it = begin; it != end; ++it) cout << *it << " "; // 3, 2, 1 (i.e. 1, 2, 3 in heap order) cout << endl; } </pre> </div> </div> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> <a name="heap.concepts.comparing"></a><a class="link" href="concepts.html#heap.concepts.comparing" title="Comparing Priority Queues & Equivalence">Comparing Priority Queues & Equivalence</a> </h3></div></div></div> The data structures of <code class="literal">boost.heap</code> can be compared with standard comparison operators. The comparison is performed by comparing two heaps element by element using <code class="literal">value_compare</code>. <div class="note"><table border="0" summary="Note"> <tr> <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../doc/src/images/note.png"></td> <th align="left">Note</th> </tr> <tr><td align="left" valign="top"> Depending on the heap type, this operation can be rather expensive, because both data structures need to be traversed in heap order. On heaps without ordered iterators, the heap needs to be copied internally. The typical complexity is O(n log(n)). </td></tr> </table></div> </div> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> <a name="heap.concepts.merge"></a><a class="link" href="concepts.html#heap.concepts.merge" title="Merging Priority Queues">Merging Priority Queues</a> </h3></div></div></div> <h4> <a name="heap.concepts.merge.h0"></a> <a name="heap.concepts.merge.mergable_priority_queues"></a><a class="link" href="concepts.html#heap.concepts.merge.mergable_priority_queues">Mergable Priority Queues</a> </h4> <h6> <a name="heap.concepts.merge.h1"></a> <a name="heap.concepts.merge.synopsis"></a><a class="link" href="concepts.html#heap.concepts.merge.synopsis">Synopsis</a> </h6> <pre class="programlisting">class mergable_heap_interface { public: // public member functions void merge(mergable_heap_interface &); }; </pre> <code class="literal">boost.heap</code> has a concept of a Mergable Priority Queue. A mergable priority queue can efficiently be merged with a different instance of the same type. <h6> <a name="heap.concepts.merge.h2"></a> <a name="heap.concepts.merge.example"></a><a class="link" href="concepts.html#heap.concepts.merge.example">Example</a> </h6> <pre class="programlisting">// PriorityQueue is expected to be a max-heap of integer values template <typename PriorityQueue> void merge_interface(void) { PriorityQueue pq; pq.push(3); pq.push(5); pq.push(1); PriorityQueue pq2; pq2.push(2); pq2.push(4); pq2.push(0); pq.merge(pq2); cout << "Priority Queue: merge" << endl; cout << "first queue: "; while (!pq.empty()) { cout << pq.top() << " "; // 5 4 3 2 1 0 pq.pop(); } cout << endl; cout << "second queue: "; while (!pq2.empty()) { cout << pq2.top() << " "; // 4 2 0 pq2.pop(); } cout << endl; } </pre> <h4> <a name="heap.concepts.merge.h3"></a> <a name="heap.concepts.merge.heap_merge_algorithms"></a><a class="link" href="concepts.html#heap.concepts.merge.heap_merge_algorithms">Heap Merge Algorithms</a> </h4> <code class="literal">boost.heap</code> provides a <code class="literal">heap_merge()</code> algorithm that is can be used to merge different kinds of heaps. Using this algorithm, all <code class="literal">boost.heap</code> data structures can be merged, although some cannot be merged efficiently. <h6> <a name="heap.concepts.merge.h4"></a> <a name="heap.concepts.merge.example0"></a><a class="link" href="concepts.html#heap.concepts.merge.example0">Example</a> </h6> <pre class="programlisting">// PriorityQueue is expected to be a max-heap of integer values template <typename PriorityQueue> void heap_merge_algorithm(void) { PriorityQueue pq; pq.push(3); pq.push(5); pq.push(1); PriorityQueue pq2; pq2.push(2); pq2.push(4); pq2.push(0); boost::heap::heap_merge(pq, pq2); cout << "Priority Queue: merge" << endl; cout << "first queue: "; while (!pq.empty()) { cout << pq.top() << " "; // 5 4 3 2 1 0 pq.pop(); } cout << endl; cout << "second queue: "; while (!pq2.empty()) { cout << pq2.top() << " "; // 4 2 0 pq2.pop(); } cout << endl; } </pre> </div> <div class="section"> <div class="titlepage"><div><div><h3 class="title"> <a name="heap.concepts.mutability"></a><a class="link" href="concepts.html#heap.concepts.mutability" title="Mutability">Mutability</a> </h3></div></div></div> Some priority queues of <code class="literal">boost.heap</code> are mutable, that means the priority of their elements can be changed. To achieve mutability, <code class="literal">boost.heap</code> introduces the concept of handles, which can be used to access the internal nodes of the priority queue in order to change its value and to restore the heap order. <h6> <a name="heap.concepts.mutability.h0"></a> <a name="heap.concepts.mutability.synopsis"></a><a class="link" href="concepts.html#heap.concepts.mutability.synopsis">Synopsis</a> </h6> <pre class="programlisting">class mutable_heap_interface { public: typedef unspecified iterator; struct handle_type { value_type & operator*() const; }; static handle_type s_iterator_to_handle(iterator const &); // priority queue interface handle_type push(T const & v); // update element via assignment and fix heap void update(handle_type const & handle, value_type const & v); void increase(handle_type const & handle, value_type const & v); void decrease(handle_type const & handle, value_type const & v); // fix heap after element has been changed via the handle void update(handle_type const & handle); void increase(handle_type const & handle); void decrease(handle_type const & handle); }; </pre> <div class="warning"><table border="0" summary="Warning"> <tr> <td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../doc/src/images/warning.png"></td> <th align="left">Warning</th> </tr> <tr><td align="left" valign="top"> Incorrect use of <code class="literal">increase</code> or <code class="literal">decrease</code> may corrupt the priority queue data structure. If unsure use <code class="literal">update</code> can be used at the cost of efficiency. </td></tr> </table></div> <h6> <a name="heap.concepts.mutability.h1"></a> <a name="heap.concepts.mutability.example"></a><a class="link" href="concepts.html#heap.concepts.mutability.example">Example</a> </h6> <pre class="programlisting">// PriorityQueue is expected to be a max-heap of integer values template <typename PriorityQueue> void mutable_interface(void) { PriorityQueue pq; typedef typename PriorityQueue::handle_type handle_t; handle_t t3 = pq.push(3); handle_t t5 = pq.<span class="i