diff --git a/reference/spl/book.xml b/reference/spl/book.xml index 9a75f47083..fc98998ac8 100644 --- a/reference/spl/book.xml +++ b/reference/spl/book.xml @@ -1,5 +1,5 @@ - + Standard PHP Library (SPL) @@ -40,6 +40,9 @@ &reference.spl.splstack; &reference.spl.splqueue; + &reference.spl.splheap; + &reference.spl.splmaxheap; + &reference.spl.splminheap; diff --git a/reference/spl/datastructures.xml b/reference/spl/datastructures.xml index 72c50cb9bd..8e7c34fe4d 100644 --- a/reference/spl/datastructures.xml +++ b/reference/spl/datastructures.xml @@ -1,37 +1,62 @@ - + Datastructures - - SPL provies a set of standard datastructures. They are grouped here by their - underlying implementation which usually defines their general field of - application. - - -
- Doubly Linked Lists - + - A Doubly Linked List (DLL) is a list of nodes linked in both directions to - each others. Iterator's operations, access to both ends, addition or - removal of nodes have a cost of O(1) when the underlying structure is a DLL. - It hence provides a decent implementation for stacks and queues. + SPL provies a set of standard datastructures. They are grouped here by their + underlying implementation which usually defines their general field of + application. - - - SplDoublyLinkedList - - SplStack - SplQueue - - - + + Doubly Linked Lists -
+ + A Doubly Linked List (DLL) is a list of nodes linked in both directions to + each others. Iterator's operations, access to both ends, addition or + removal of nodes have a cost of O(1) when the underlying structure is a DLL. + It hence provides a decent implementation for stacks and queues. + + + + + SplDoublyLinkedList + + SplStack + SplQueue + + + + + + + Heaps + + + Heaps are tree-like structures that follow the heap-property: each node + is greater than or equal to its children, when compared using the + implemented compare method which is global to the heap. + + + + + SplHeap + + SplMaxHeap + SplMinHeap + + + + SplPriorityQueue + + + + + diff --git a/reference/spl/spldoublylinkedlist/bottom.xml b/reference/spl/spldoublylinkedlist/bottom.xml new file mode 100644 index 0000000000..71e8f4f030 --- /dev/null +++ b/reference/spl/spldoublylinkedlist/bottom.xml @@ -0,0 +1,50 @@ + + + + + SplDoublyLinkedList::bottom + Peaks at the node from the beginning of the doubly linked list + + + + &reftitle.description; + + mixedSplDoublyLinkedList::bottom + + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + The value of the first node. + + + + + + diff --git a/reference/spl/spldoublylinkedlist/pop.xml b/reference/spl/spldoublylinkedlist/pop.xml index fbf1ecec9b..f33678561e 100644 --- a/reference/spl/spldoublylinkedlist/pop.xml +++ b/reference/spl/spldoublylinkedlist/pop.xml @@ -1,9 +1,9 @@ - + SplDoublyLinkedList::pop - Pops a node from then end of the doubly linked list + Pops a node from the end of the doubly linked list diff --git a/reference/spl/spldoublylinkedlist/top.xml b/reference/spl/spldoublylinkedlist/top.xml new file mode 100644 index 0000000000..61e8905379 --- /dev/null +++ b/reference/spl/spldoublylinkedlist/top.xml @@ -0,0 +1,50 @@ + + + + + SplDoublyLinkedList::top + Peaks at the node from the end of the doubly linked list + + + + &reftitle.description; + + mixedSplDoublyLinkedList::top + + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + The value of the last node. + + + + + + diff --git a/reference/spl/spldoublylinkedlist/valid.xml b/reference/spl/spldoublylinkedlist/valid.xml index a7b4c2fd37..5762b3d55b 100644 --- a/reference/spl/spldoublylinkedlist/valid.xml +++ b/reference/spl/spldoublylinkedlist/valid.xml @@ -1,9 +1,9 @@ - + SplDoublyLinkedList::valid - Check whether the doubly linked list contains more entries + Check whether the doubly linked list contains more nodes diff --git a/reference/spl/splheap.xml b/reference/spl/splheap.xml new file mode 100644 index 0000000000..bf86d7e5a8 --- /dev/null +++ b/reference/spl/splheap.xml @@ -0,0 +1,99 @@ + + + + The SplHeap class + SplHeap + + + + +
+ &reftitle.intro; + + The SplHeap class provides the main functionalities of an Heap. + +
+ + +
+ &reftitle.classsynopsis; + + + + SplHeap + + + + + + abstractSplHeap + + + + Iterator + + + + Countable + + + + + + + + Methods + + + + +
+ + + + + + &reference.spl.entities.splheap; + + + + + diff --git a/reference/spl/splheap/compare.xml b/reference/spl/splheap/compare.xml new file mode 100644 index 0000000000..a27b8a2bac --- /dev/null +++ b/reference/spl/splheap/compare.xml @@ -0,0 +1,87 @@ + + + + + SplHeap::compare + Compare elements in order to place them correctly in the heap while sifting up. + + + + &reftitle.description; + + abstractintSplHeap::compare + mixedvalue1 + mixedvalue2 + + + + Compare value1 with value2. + + + + Throwing exceptions in SplHeap::compare can + corrupt the Heap and place it in an blocked state. You can unblock is by + calling SplHeap::recoverFromCorruption. + However, some elements might not be placed correctly and it may hence + break the heap-property. + + + + + + &reftitle.parameters; + + + + value1 + + + The value of the first node being compared. + + + + + value2 + + + The value of the second node being compared. + + + + + + + + + &reftitle.returnvalues; + + Result of the comparison, positive integer if value1 is greater than value2, 0 if they are equal, negative integer otherwise. + + + + Having multiple elements with the same value in a Heap is not recommended. They will end up in an arbitrary relative position. + + + + + + diff --git a/reference/spl/splheap/construct.xml b/reference/spl/splheap/construct.xml new file mode 100644 index 0000000000..115faf64f4 --- /dev/null +++ b/reference/spl/splheap/construct.xml @@ -0,0 +1,53 @@ + + + + + SplHeap::__construct + Constructs a new empty heap + + + + &reftitle.description; + + SplHeap::__construct + + + + This constructs a new empty heap. + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + &return.void; + + + + + + diff --git a/reference/spl/splheap/count.xml b/reference/spl/splheap/count.xml new file mode 100644 index 0000000000..bb22ec0345 --- /dev/null +++ b/reference/spl/splheap/count.xml @@ -0,0 +1,50 @@ + + + + + SplHeap::count + Counts the number of elements in the heap. + + + + &reftitle.description; + + intSplHeap::count + + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + Returns the number of elements in the heap. + + + + + + diff --git a/reference/spl/splheap/current.xml b/reference/spl/splheap/current.xml new file mode 100644 index 0000000000..f8d931ebc7 --- /dev/null +++ b/reference/spl/splheap/current.xml @@ -0,0 +1,52 @@ + + + + + SplHeap::current + Return current node pointed by the iterator + + + + &reftitle.description; + + mixedSplHeap::current + + + + Get the current datastructure node. + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + The current node value. + + + + + diff --git a/reference/spl/splheap/extract.xml b/reference/spl/splheap/extract.xml new file mode 100644 index 0000000000..4e109d5342 --- /dev/null +++ b/reference/spl/splheap/extract.xml @@ -0,0 +1,50 @@ + + + + + SplHeap::extract + Extracts a node from top of the heap and sift up. + + + + &reftitle.description; + + mixedSplHeap::extract + + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + The value of the extracted node. + + + + + + diff --git a/reference/spl/splheap/insert.xml b/reference/spl/splheap/insert.xml new file mode 100644 index 0000000000..96c6468840 --- /dev/null +++ b/reference/spl/splheap/insert.xml @@ -0,0 +1,64 @@ + + + + + SplHeap::insert + Inserts an element in the heap by sifting it up. + + + + &reftitle.description; + + voidSplHeap::insert + mixedvalue + + + + Insert value in the heap. + + + + + &reftitle.parameters; + + + + value + + + The value to insert. + + + + + + + + + &reftitle.returnvalues; + + &return.void; + + + + + diff --git a/reference/spl/splheap/isempty.xml b/reference/spl/splheap/isempty.xml new file mode 100644 index 0000000000..c333263d61 --- /dev/null +++ b/reference/spl/splheap/isempty.xml @@ -0,0 +1,50 @@ + + + + + SplHeap::isEmpty + Checks whether the heap is empty. + + + + &reftitle.description; + + boolSplHeap::isEmpty + + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + Returns whether the heap is empty. + + + + + + diff --git a/reference/spl/splheap/key.xml b/reference/spl/splheap/key.xml new file mode 100644 index 0000000000..fc896bb4ce --- /dev/null +++ b/reference/spl/splheap/key.xml @@ -0,0 +1,53 @@ + + + + + SplHeap::key + Return current node index + + + + &reftitle.description; + + mixedSplHeap::key + + + + This function returns the current node index + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + The current node index. + + + + + + diff --git a/reference/spl/splheap/next.xml b/reference/spl/splheap/next.xml new file mode 100644 index 0000000000..ff69cec4e5 --- /dev/null +++ b/reference/spl/splheap/next.xml @@ -0,0 +1,53 @@ + + + + + SplHeap::next + Move to the next node + + + + &reftitle.description; + + voidSplHeap::next + + + + Extracts the top node from the heap. + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + &return.void; + + + + + + diff --git a/reference/spl/splheap/recoverfromcorruption.xml b/reference/spl/splheap/recoverfromcorruption.xml new file mode 100644 index 0000000000..f277dd1768 --- /dev/null +++ b/reference/spl/splheap/recoverfromcorruption.xml @@ -0,0 +1,49 @@ + + + + + SplHeap::recoverFromCorruption + Recover from the corrupted state and allow further actions on the heap. + + + + &reftitle.description; + + voidSplHeap::recoverFromCorruption + + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + &return.void; + + + + + diff --git a/reference/spl/splheap/rewind.xml b/reference/spl/splheap/rewind.xml new file mode 100644 index 0000000000..c5f0b9d3a1 --- /dev/null +++ b/reference/spl/splheap/rewind.xml @@ -0,0 +1,55 @@ + + + + + SplHeap::rewind + Rewind iterator back to the start (no-op) + + + + &reftitle.description; + + voidSplHeap::rewind + + + + This rewinds the iterator to the beginning. This is a no-opp for heaps + as the iterator is virtual and in fact never moves from the top of the + heap. + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + &return.void; + + + + + + diff --git a/reference/spl/splheap/top.xml b/reference/spl/splheap/top.xml new file mode 100644 index 0000000000..4decb7324c --- /dev/null +++ b/reference/spl/splheap/top.xml @@ -0,0 +1,50 @@ + + + + + SplHeap::top + Peaks at the node from the top of the heap + + + + &reftitle.description; + + mixedSplHeap::top + + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + The value of the node on the top. + + + + + + diff --git a/reference/spl/splheap/valid.xml b/reference/spl/splheap/valid.xml new file mode 100644 index 0000000000..558868056c --- /dev/null +++ b/reference/spl/splheap/valid.xml @@ -0,0 +1,53 @@ + + + + + SplHeap::valid + Check whether the heap contains more nodes + + + + &reftitle.description; + + boolSplHeap::valid + + + + Checks if the heap contains any more nodes. + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + Returns &true; if the heap contains any more nodes, &false; otherwise. + + + + + + diff --git a/reference/spl/splmaxheap.xml b/reference/spl/splmaxheap.xml new file mode 100644 index 0000000000..153efba521 --- /dev/null +++ b/reference/spl/splmaxheap.xml @@ -0,0 +1,107 @@ + + + + The SplMaxHeap class + SplMaxHeap + + + + +
+ &reftitle.intro; + + The SplMaxHeap class provides the main functionalities of a heap, keeping the maximum on the top. + +
+ + +
+ &reftitle.classsynopsis; + + + + SplMaxHeap + + + + + + SplMaxHeap + + + + extends + SplHeap + + + + Iterator + + + + Countable + + + + + + + + Methods + + + Inherited methods + + + +
+ + + + + + + &reference.spl.entities.splmaxheap; + + + + + diff --git a/reference/spl/splmaxheap/compare.xml b/reference/spl/splmaxheap/compare.xml new file mode 100644 index 0000000000..2306c5ba10 --- /dev/null +++ b/reference/spl/splmaxheap/compare.xml @@ -0,0 +1,78 @@ + + + + + SplMaxHeap::compare + Compare elements in order to place them correctly in the heap while sifting up. + + + + &reftitle.description; + + voidSplMaxHeap::compare + mixedvalue1 + mixedvalue2 + + + + Compare value1 with value2. + + + + + &reftitle.parameters; + + + + value1 + + + The value of the first node being compared. + + + + + value2 + + + The value of the second node being compared. + + + + + + + + + &reftitle.returnvalues; + + Result of the comparison, positive integer if value1 is greater than value2, 0 if they are equal, negative integer otherwise. + + + + Having multiple elements with the same value in a Heap is not recommended. They will end up in an arbitrary relative position. + + + + + + diff --git a/reference/spl/splminheap.xml b/reference/spl/splminheap.xml new file mode 100644 index 0000000000..9085689e9c --- /dev/null +++ b/reference/spl/splminheap.xml @@ -0,0 +1,107 @@ + + + + The SplMinHeap class + SplMinHeap + + + + +
+ &reftitle.intro; + + The SplMinHeap class provides the main functionalities of a heap, keeping the minimum on the top. + +
+ + +
+ &reftitle.classsynopsis; + + + + SplMinHeap + + + + + + SplMinHeap + + + + extends + SplHeap + + + + Iterator + + + + Countable + + + + + + + + Methods + + + Inherited methods + + + +
+ + + + + + + &reference.spl.entities.splminheap; + + + + + diff --git a/reference/spl/splminheap/compare.xml b/reference/spl/splminheap/compare.xml new file mode 100644 index 0000000000..61171e5954 --- /dev/null +++ b/reference/spl/splminheap/compare.xml @@ -0,0 +1,78 @@ + + + + + SplMinHeap::compare + Compare elements in order to place them correctly in the heap while sifting up. + + + + &reftitle.description; + + voidSplMinHeap::compare + mixedvalue1 + mixedvalue2 + + + + Compare value1 with value2. + + + + + &reftitle.parameters; + + + + value1 + + + The value of the first node being compared. + + + + + value2 + + + The value of the second node being compared. + + + + + + + + + &reftitle.returnvalues; + + Result of the comparison, positive integer if value1 is lower than value2, 0 if they are equal, negative integer otherwise. + + + + Having multiple elements with the same value in a Heap is not recommended. They will end up in an arbitrary relative position. + + + + + +