The Deque ADT models a line of objects that can be accessed, added to and
-removed from either end of the line
+removed from either end of the line.
A deque can be used as a stack or as a queue.
Consider using a deque when you need to simulate a line of objects that can be accessed
-from both ends, like cars on a ferry.
-On one shore, cars leave the ferry from the front and new ones board it from the front.
-On the other shore, cars leave and board the ferry from the back.
+184 def take_back(self) -> Any:
-185 """Remove and return the item at the back of the deque.
-186
-187 Raise `ValueError` if the deque is empty.
-188
-189 Complexity: O(1)
-190 """
-191 if self.size() == 0:
-192 msg = "can't remove a member from an empty deque"
-193 raise ValueError(msg)
-194 item = self._tail[DATA]
-195 self._tail = self._tail[PREV]
-196 self._length -= 1
-197 if self.size() == 0:
-198 self._head = None
-199 else:
-200 self._tail[NEXT] = None
-201 return item
+ 185 def take_back(self) -> Any:
+186 """Remove and return the item at the back of the deque.
+187
+188 Raise `ValueError` if the deque is empty.
+189
+190 Complexity: O(1)
+191 """
+192 if self.size() == 0:
+193 msg = "can't remove a member from an empty deque"
+194 raise ValueError(msg)
+195 item = self._tail[DATA]
+196 self._tail = self._tail[PREV]
+197 self._length -= 1
+198 if self.size() == 0:
+199 self._head = None
+200 else:
+201 self._tail[NEXT] = None
+202 return item
paddles is a pedagogical algorithms and data structures library.\n\nIt currently implements the Stack, Queue and Deque abstract data types (ADTs).
\n\nLicence
\n\nThe code and text in this repository are\nCopyright \u00a9 2024 by The Open University, UK.\nThe code is licensed under a BSD-3-clause licence.\nThe text is licensed under a\nCreative Commons Attribution 4.0 International Licence.
\n"}, {"fullname": "paddles.deque", "modulename": "paddles.deque", "kind": "module", "doc": "This module implements the Deque ADT.
\n\nIntuition
\n\nThe Deque ADT models a line of objects that can be accessed, added to and\nremoved from either end of the line\nA deque can be used as a stack or as a queue.
\n\nDefinition
\n\nA deque, pronounced 'deck' and short for 'double-ended queue', is a sequence\nwhere only the members at both ends of the sequence.\n(called the front and the back of the queue) can be accessed and removed.\nNew members can only be added at the front or at the back.
\n\nOperations
\n\nThe Deque ADT provides operations to:
\n\n\n- create a new empty deque
\n- add a new member to the front of the deque
\n- add a new member to the back of the deque
\n- remove the member at the front of the deque
\n- remove the member at the back of the deque
\n- access the member at the front of the deque without removing it
\n- access the member at the back of the deque without removing it
\n- compute the size of the deque (number of members).
\n
\n\nApplications
\n\nConsider using a deque when you need to simulate a line of objects that can be accessed\nfrom both ends, like cars on a ferry.\nOn one shore, cars leave the ferry from the front and new ones board it from the front.\nOn the other shore, cars leave and board the ferry from the back.
\n\nImplementations
\n\nThe Deque ADT can be implemented with circular dynamic arrays or doubly-linked lists.\nIn both cases, the operations listed above take constant time.\nA doubly-linked list uses much more memory than a static array of the same length,\nbut a dynamic array may have wasted capacity and requires resizing.\npaddles only provides a doubly-linked list implementation for the moment.
\n"}, {"fullname": "paddles.deque.LinkedListDeque", "modulename": "paddles.deque", "qualname": "LinkedListDeque", "kind": "class", "doc": "An implementation of the Deque ADT, using a doubly-linked list.
\n\nBesides the ADT's operations, this class provides two convenience operations:
\n\n\n- create a non-empty deque from a given sequence
\n- convert a deque to a string, to see its members listed from front to back.
\n
\n\n\n
>>> from paddles.deque import LinkedListDeque\n>>> deque = LinkedListDeque("abc") # create a non-empty deque\n>>> deque.size() # number of members\n3\n>>> deque.take_front() # remove and return the front member\n'a'\n>>> deque.take_back() # remove and return the back member\n'c'\n>>> deque.front() == deque.back() == 'b' # return the front and back members\nTrue\n>>> deque.add_back("C") # add a new member at the back\n>>> deque.add_front("A") # add a new member at the front\n>>> print(deque) # str(deque) also possible\nLinkedListDeque(['A', 'b', 'C'])\n
\n
Initialize the deque with the members of sequence.
\n\nThe members are added to the deque in the order they are in sequence.\nTo create an empty deque, call LinkedListDeque() or LinkedListDeque([]).
\n\nComplexity: O(len(sequence))
\n", "signature": "(sequence: collections.abc.Sequence[typing.Any] = [])"}, {"fullname": "paddles.deque.LinkedListDeque.size", "modulename": "paddles.deque", "qualname": "LinkedListDeque.size", "kind": "function", "doc": "Return how many members the deque has.
\n\nComplexity: O(1)
\n", "signature": "(self) -> int:", "funcdef": "def"}, {"fullname": "paddles.deque.LinkedListDeque.front", "modulename": "paddles.deque", "qualname": "LinkedListDeque.front", "kind": "function", "doc": "Return the item at the front of the deque, without removing it.
\n\nRaise ValueError if the deque is empty.
\n\nComplexity: O(1)
\n", "signature": "(self) -> Any:", "funcdef": "def"}, {"fullname": "paddles.deque.LinkedListDeque.back", "modulename": "paddles.deque", "qualname": "LinkedListDeque.back", "kind": "function", "doc": "Return the item at the back of the deque, without removing it.
\n\nRaise ValueError if the deque is empty.
\n\nComplexity: O(1)
\n", "signature": "(self) -> Any:", "funcdef": "def"}, {"fullname": "paddles.deque.LinkedListDeque.add_front", "modulename": "paddles.deque", "qualname": "LinkedListDeque.add_front", "kind": "function", "doc": "Put item at the front of the deque.
\n\nComplexity: O(1)
\n", "signature": "(self, item: Any) -> None:", "funcdef": "def"}, {"fullname": "paddles.deque.LinkedListDeque.add_back", "modulename": "paddles.deque", "qualname": "LinkedListDeque.add_back", "kind": "function", "doc": "Put item at the back of the deque.
\n\nComplexity: O(1)
\n", "signature": "(self, item: Any) -> None:", "funcdef": "def"}, {"fullname": "paddles.deque.LinkedListDeque.take_front", "modulename": "paddles.deque", "qualname": "LinkedListDeque.take_front", "kind": "function", "doc": "Remove and return the item at the front of the deque.
\n\nRaise ValueError if the deque is empty.
\n\nComplexity: O(1)
\n", "signature": "(self) -> Any:", "funcdef": "def"}, {"fullname": "paddles.deque.LinkedListDeque.take_back", "modulename": "paddles.deque", "qualname": "LinkedListDeque.take_back", "kind": "function", "doc": "Remove and return the item at the back of the deque.
\n\nRaise ValueError if the deque is empty.
\n\nComplexity: O(1)
\n", "signature": "(self) -> Any:", "funcdef": "def"}, {"fullname": "paddles.queue", "modulename": "paddles.queue", "kind": "module", "doc": "This module implements the Queue ADT.
\n\nIntuition
\n\nThe Queue ADT models a line of objects, e.g. cars waiting to board a ferry.\nOnly the object at the front of the line can be accessed and removed.\nThe only way to add an object is to put it at the back of the line.
\n\nDefinition
\n\nA queue is a sequence where members are added to one end of the sequence\n(the back of the queue) and removed from the other end (the front of the queue).
\n\nA queue is a first-in, first-out (FIFO) sequence:\nthe members are removed in the same order they were added.
\n\nA queue is a sequence ordered by age (time of addition).\nThe oldest member is at the front of the queue, and the youngest member is at the back.
\n\nOperations
\n\nThe Queue ADT provides operations to:
\n\n\n- create a new empty queue
\n- add a new member, at the back of the existing ones
\n- remove the member at the front of the queue
\n- access the member at the front of the queue without removing it
\n- compute the size of the queue (number of members).
\n
\n\nApplications
\n\nQueues are used to implement breadth-first search.\nYou should consider using a queue when you need to:
\n\n\n- simulate a real-life queue, like travellers at passport control or\ndocuments in a printer queue
\n- process items in the same order they were added, like a to-do list.
\n
\n\nImplementations
\n\nThe Queue ADT can be implemented with circular dynamic arrays or singly-linked lists.\nIn both cases, the operations listed above take constant time.\nA singly-linked list uses much more memory than a static array of the same length,\nbut a dynamic array may have wasted capacity and requires resizing.\npaddles only provides a singly-linked list implementation for the moment.
\n"}, {"fullname": "paddles.queue.LinkedListQueue", "modulename": "paddles.queue", "qualname": "LinkedListQueue", "kind": "class", "doc": "An implementation of the Queue ADT, using a singly-linked list.
\n\nBesides the ADT's operations, this class provides two convenience operations:
\n\n\n- create a non-empty queue from a given sequence
\n- convert a queue to a string, to see its members listed from front to back.
\n
\n\n\n
>>> from paddles.queue import LinkedListQueue\n>>> q = LinkedListQueue("abc") # create a non-empty queue\n>>> q.size() # number of members\n3\n>>> q.dequeue() # remove and return the front member\n'a'\n>>> q.front() # return but don't remove the front member\n'b'\n>>> q.enqueue("d") # add a new member at the back\n>>> print(q) # str(q) also possible\nLinkedListQueue(['b', 'c', 'd'])\n
\n
Initialize the queue with the members of sequence.
\n\nThe members are added to the queue in the order they are in sequence.\nTo create an empty queue, call LinkedListQueue() or LinkedListQueue([]).
\n\nComplexity: O(len(sequence))
\n", "signature": "(sequence: collections.abc.Sequence[typing.Any] = [])"}, {"fullname": "paddles.queue.LinkedListQueue.size", "modulename": "paddles.queue", "qualname": "LinkedListQueue.size", "kind": "function", "doc": "Return how many members the queue has.
\n\nComplexity: O(1)
\n", "signature": "(self) -> int:", "funcdef": "def"}, {"fullname": "paddles.queue.LinkedListQueue.front", "modulename": "paddles.queue", "qualname": "LinkedListQueue.front", "kind": "function", "doc": "Return the member at the front of the queue, without removing it.
\n\nRaise ValueError if the queue is empty.
\n\nComplexity: O(1)
\n", "signature": "(self) -> Any:", "funcdef": "def"}, {"fullname": "paddles.queue.LinkedListQueue.enqueue", "modulename": "paddles.queue", "qualname": "LinkedListQueue.enqueue", "kind": "function", "doc": "Put item at the back of the queue.
\n\nComplexity: O(1)
\n", "signature": "(self, item: Any) -> None:", "funcdef": "def"}, {"fullname": "paddles.queue.LinkedListQueue.dequeue", "modulename": "paddles.queue", "qualname": "LinkedListQueue.dequeue", "kind": "function", "doc": "Remove and return the item at the front of the queue.
\n\nRaise ValueError if the queue is empty.
\n\nComplexity: O(1)
\n", "signature": "(self) -> Any:", "funcdef": "def"}, {"fullname": "paddles.stack", "modulename": "paddles.stack", "kind": "module", "doc": "This module implements the Stack ADT.
\n\nIntuition
\n\nThe Stack ADT models a pile of objects, e.g. a pile of storage boxes.\nOnly the object at the top of the pile can be accessed and removed.\nThe only way to add an object is to put it on top of the existing pile.
\n\nDefinition
\n\nA stack is a sequence where members are removed from and added to\nthe same end of the sequence, called the top of the stack.
\n\nA stack is a last-in, first-out (LIFO) sequence:\nthe next member to be removed is the one most recently added.
\n\nA stack is a sequence ordered by age (time of addition).\nThe oldest member is at the bottom of the stack, and the youngest member is at the top.
\n\nOperations
\n\nThe Stack ADT provides operations to:
\n\n\n- create a new empty stack
\n- add a new member, on top of the existing ones
\n- remove the member at the top of the stack
\n- access the member at the top of the stack without removing it
\n- compute the size of the stack (number of members).
\n
\n\nApplications
\n\nStacks are used to implement function calls and depth-first search.\nYou should consider using a stack when you need to:
\n\n\n- simulate the handling of a pile of objects, like loading and unloading ship containers
\n- process nested structures, like brackets (e.g.
print([1, {2, 3}])) or\nHTML tags (e.g. <p><b>text</b></p>) \n- process items in the reverse order they were added, like undo operations\n(the next command to be undone is the most recently executed one).
\n
\n\nImplementations
\n\nThe Stack ADT can be implemented with dynamic arrays or singly-linked lists.\nIn both cases, the operations listed above take constant time.\nA singly-linked list uses much more memory than a static array of the same length,\nbut a dynamic array may have wasted capacity and requires resizing.
\n"}, {"fullname": "paddles.stack.DynamicArrayStack", "modulename": "paddles.stack", "qualname": "DynamicArrayStack", "kind": "class", "doc": "An implementation of the Stack ADT, using Python lists.
\n\nBesides the ADT's operations, this class provides two convenience operations:
\n\n\n- create a non-empty stack from a given sequence
\n- convert a stack to a string, to see its members listed from bottom to top.
\n
\n\n\n
>>> from paddles.stack import DynamicArrayStack\n>>> stack = DynamicArrayStack("abc") # create a non-empty stack\n>>> stack.size() # number of members\n3\n>>> stack.pop() # remove and return the top member\n'c'\n>>> stack.peek() # return but don't remove the top member\n'b'\n>>> stack.push("C") # add a new member on top\n>>> print(stack) # str(stack) also possible\nDynamicArrayStack(['a', 'b', 'C'])\n
\n
Initialize the stack with the members of sequence.
\n\nThe members are added to the stack in the order they are in sequence.\nTo create an empty stack, call DynamicArrayStack() or DynamicArrayStack([]).
\n\nComplexity: O(len(sequence))
\n", "signature": "(sequence: collections.abc.Sequence[typing.Any] = [])"}, {"fullname": "paddles.stack.DynamicArrayStack.size", "modulename": "paddles.stack", "qualname": "DynamicArrayStack.size", "kind": "function", "doc": "Return how many members the stack has.
\n\nComplexity: O(1)
\n", "signature": "(self) -> int:", "funcdef": "def"}, {"fullname": "paddles.stack.DynamicArrayStack.peek", "modulename": "paddles.stack", "qualname": "DynamicArrayStack.peek", "kind": "function", "doc": "Return the member at the top of the stack, without removing it.
\n\nRaise ValueError if the stack is empty.
\n\nComplexity: O(1)
\n", "signature": "(self) -> Any:", "funcdef": "def"}, {"fullname": "paddles.stack.DynamicArrayStack.push", "modulename": "paddles.stack", "qualname": "DynamicArrayStack.push", "kind": "function", "doc": "Put item on top of the stack.
\n\nComplexity: O(1)
\n", "signature": "(self, item: Any) -> None:", "funcdef": "def"}, {"fullname": "paddles.stack.DynamicArrayStack.pop", "modulename": "paddles.stack", "qualname": "DynamicArrayStack.pop", "kind": "function", "doc": "Remove and return the member at the top of the stack.
\n\nRaise ValueError if the stack is empty.
\n\nComplexity: O(1)
\n", "signature": "(self) -> Any:", "funcdef": "def"}, {"fullname": "paddles.stack.LinkedListStack", "modulename": "paddles.stack", "qualname": "LinkedListStack", "kind": "class", "doc": "An implementation of the Stack ADT, using singly-linked lists.
\n\nBesides the ADT's operations, this class provides two convenience operations:
\n\n\n- create a non-empty stack from a given sequence
\n- convert a stack to a string, to see its members listed from bottom to top.
\n
\n\n\n
>>> from paddles.stack import LinkedListStack\n>>> stack = LinkedListStack("abc") # create a non-empty stack\n>>> stack.size() # number of members\n3\n>>> stack.pop() # remove and return the top member\n'c'\n>>> stack.peek() # return but don't remove the top member\n'b'\n>>> stack.push("C") # add a new member on top\n>>> print(stack) # str(stack) also possible\nLinkedListStack(['a', 'b', 'C'])\n
\n
Initialize the stack with the members of sequence.
\n\nThe members are added to the stack in the order they are in sequence.\nTo create an empty stack, call LinkedListStack() or LinkedListStack([]).
\n\nComplexity: O(len(sequence))
\n", "signature": "(sequence: collections.abc.Sequence[typing.Any] = [])"}, {"fullname": "paddles.stack.LinkedListStack.size", "modulename": "paddles.stack", "qualname": "LinkedListStack.size", "kind": "function", "doc": "Return how many members the stack has.
\n\nComplexity: O(1)
\n", "signature": "(self) -> int:", "funcdef": "def"}, {"fullname": "paddles.stack.LinkedListStack.push", "modulename": "paddles.stack", "qualname": "LinkedListStack.push", "kind": "function", "doc": "Put item on top of the stack.
\n\nComplexity: O(1)
\n", "signature": "(self, item: Any) -> None:", "funcdef": "def"}, {"fullname": "paddles.stack.LinkedListStack.pop", "modulename": "paddles.stack", "qualname": "LinkedListStack.pop", "kind": "function", "doc": "Remove and return the member at the top of the stack.
\n\nRaise ValueError if the stack is empty.
\n\nComplexity: O(1)
\n", "signature": "(self) -> Any:", "funcdef": "def"}, {"fullname": "paddles.stack.LinkedListStack.peek", "modulename": "paddles.stack", "qualname": "LinkedListStack.peek", "kind": "function", "doc": "Return the member at the top of the stack.
\n\nRaise ValueError if the stack is empty.
\n\nComplexity: O(1)
\n", "signature": "(self) -> Any:", "funcdef": "def"}];
+ /** pdoc search index */const docs = [{"fullname": "paddles", "modulename": "paddles", "kind": "module", "doc": "paddles is a pedagogical algorithms and data structures library.
\n\nIt currently implements the Stack, Queue and Deque abstract data types (ADTs).
\n\nThe code repository is at https://github.com/dsa-ou/paddles.\nThe formatted documentation is at https://dsa-ou.github.io/paddles.
\n\nLicence
\n\npaddles is Copyright \u00a9 2024 by The Open University, UK.\nThe code is licensed under a BSD-3-clause licence.\nThe documentation is licensed under a\nCreative Commons Attribution 4.0 International Licence.
\n"}, {"fullname": "paddles.deque", "modulename": "paddles.deque", "kind": "module", "doc": "This module implements the Deque ADT.
\n\nIntuition
\n\nThe Deque ADT models a line of objects that can be accessed, added to and\nremoved from either end of the line.\nA deque can be used as a stack or as a queue.
\n\nDefinition
\n\nA deque, pronounced 'deck' and short for 'double-ended queue', is a sequence\nwhere only the members at both ends of the sequence\n(called the front and the back of the queue) can be accessed and removed.\nNew members can only be added at the front or at the back.
\n\nOperations
\n\nThe Deque ADT provides operations to:
\n\n\n- create a new empty deque
\n- add a new member to the front of the deque
\n- add a new member to the back of the deque
\n- remove the member at the front of the deque
\n- remove the member at the back of the deque
\n- access the member at the front of the deque without removing it
\n- access the member at the back of the deque without removing it
\n- compute the size of the deque (number of members).
\n
\n\nApplications
\n\nConsider using a deque when you need to simulate a queue where
\n\n\n- objects jump the queue (join at the front) or\nleave it from the back after waiting a certain time
\n- the direction of the queue changes, like cars on a ferry.
\n
\n\nImplementations
\n\nThe Deque ADT can be implemented with circular dynamic arrays or doubly-linked lists.\nIn both cases, the operations listed above take constant time.\nA doubly-linked list uses much more memory than a static array of the same length,\nbut a dynamic array may have wasted capacity and requires resizing.\npaddles only provides a doubly-linked list implementation for the moment.
\n"}, {"fullname": "paddles.deque.LinkedListDeque", "modulename": "paddles.deque", "qualname": "LinkedListDeque", "kind": "class", "doc": "An implementation of the Deque ADT, using a doubly-linked list.
\n\nBesides the ADT's operations, this class provides two convenience operations:
\n\n\n- create a non-empty deque from a given sequence
\n- convert a deque to a string, to see its members listed from front to back.
\n
\n\n\n
>>> from paddles.deque import LinkedListDeque\n>>> deque = LinkedListDeque("abc") # create a non-empty deque\n>>> deque.size() # number of members\n3\n>>> deque.take_front() # remove and return the front member\n'a'\n>>> deque.take_back() # remove and return the back member\n'c'\n>>> deque.front() == deque.back() == 'b' # return the front and back members\nTrue\n>>> deque.add_back("C") # add a new member at the back\n>>> deque.add_front("A") # add a new member at the front\n>>> print(deque) # str(deque) also possible\nLinkedListDeque(['A', 'b', 'C'])\n
\n
Initialize the deque with the members of sequence.
\n\nThe members are added to the deque in the order they are in sequence.\nTo create an empty deque, call LinkedListDeque() or LinkedListDeque([]).
\n\nComplexity: O(len(sequence))
\n", "signature": "(sequence: collections.abc.Sequence[typing.Any] = [])"}, {"fullname": "paddles.deque.LinkedListDeque.size", "modulename": "paddles.deque", "qualname": "LinkedListDeque.size", "kind": "function", "doc": "Return how many members the deque has.
\n\nComplexity: O(1)
\n", "signature": "(self) -> int:", "funcdef": "def"}, {"fullname": "paddles.deque.LinkedListDeque.front", "modulename": "paddles.deque", "qualname": "LinkedListDeque.front", "kind": "function", "doc": "Return the item at the front of the deque, without removing it.
\n\nRaise ValueError if the deque is empty.
\n\nComplexity: O(1)
\n", "signature": "(self) -> Any:", "funcdef": "def"}, {"fullname": "paddles.deque.LinkedListDeque.back", "modulename": "paddles.deque", "qualname": "LinkedListDeque.back", "kind": "function", "doc": "Return the item at the back of the deque, without removing it.
\n\nRaise ValueError if the deque is empty.
\n\nComplexity: O(1)
\n", "signature": "(self) -> Any:", "funcdef": "def"}, {"fullname": "paddles.deque.LinkedListDeque.add_front", "modulename": "paddles.deque", "qualname": "LinkedListDeque.add_front", "kind": "function", "doc": "Put item at the front of the deque.
\n\nComplexity: O(1)
\n", "signature": "(self, item: Any) -> None:", "funcdef": "def"}, {"fullname": "paddles.deque.LinkedListDeque.add_back", "modulename": "paddles.deque", "qualname": "LinkedListDeque.add_back", "kind": "function", "doc": "Put item at the back of the deque.
\n\nComplexity: O(1)
\n", "signature": "(self, item: Any) -> None:", "funcdef": "def"}, {"fullname": "paddles.deque.LinkedListDeque.take_front", "modulename": "paddles.deque", "qualname": "LinkedListDeque.take_front", "kind": "function", "doc": "Remove and return the item at the front of the deque.
\n\nRaise ValueError if the deque is empty.
\n\nComplexity: O(1)
\n", "signature": "(self) -> Any:", "funcdef": "def"}, {"fullname": "paddles.deque.LinkedListDeque.take_back", "modulename": "paddles.deque", "qualname": "LinkedListDeque.take_back", "kind": "function", "doc": "Remove and return the item at the back of the deque.
\n\nRaise ValueError if the deque is empty.
\n\nComplexity: O(1)
\n", "signature": "(self) -> Any:", "funcdef": "def"}, {"fullname": "paddles.queue", "modulename": "paddles.queue", "kind": "module", "doc": "This module implements the Queue ADT.
\n\nIntuition
\n\nThe Queue ADT models a line of objects, e.g. cars waiting to board a ferry.\nOnly the object at the front of the line can be accessed and removed.\nThe only way to add an object is to put it at the back of the line.
\n\nDefinition
\n\nA queue is a sequence where members are added to one end of the sequence\n(the back of the queue) and removed from the other end (the front of the queue).
\n\nA queue is a first-in, first-out (FIFO) sequence:\nthe members are removed in the same order they were added.
\n\nA queue is a sequence ordered by age (time of addition).\nThe oldest member is at the front of the queue, and the youngest member is at the back.
\n\nOperations
\n\nThe Queue ADT provides operations to:
\n\n\n- create a new empty queue
\n- add a new member, at the back of the existing ones
\n- remove the member at the front of the queue
\n- access the member at the front of the queue without removing it
\n- compute the size of the queue (number of members).
\n
\n\nApplications
\n\nQueues are used to implement breadth-first search.\nYou should consider using a queue when you need to:
\n\n\n- simulate a real-life queue, like travellers at passport control or\ndocuments in a printer queue
\n- process items in the same order they were added, like a to-do list.
\n
\n\nImplementations
\n\nThe Queue ADT can be implemented with circular dynamic arrays or singly-linked lists.\nIn both cases, the operations listed above take constant time.\nA singly-linked list uses much more memory than a static array of the same length,\nbut a dynamic array may have wasted capacity and requires resizing.\npaddles only provides a singly-linked list implementation for the moment.
\n"}, {"fullname": "paddles.queue.LinkedListQueue", "modulename": "paddles.queue", "qualname": "LinkedListQueue", "kind": "class", "doc": "An implementation of the Queue ADT, using a singly-linked list.
\n\nBesides the ADT's operations, this class provides two convenience operations:
\n\n\n- create a non-empty queue from a given sequence
\n- convert a queue to a string, to see its members listed from front to back.
\n
\n\n\n
>>> from paddles.queue import LinkedListQueue\n>>> q = LinkedListQueue("abc") # create a non-empty queue\n>>> q.size() # number of members\n3\n>>> q.dequeue() # remove and return the front member\n'a'\n>>> q.front() # return but don't remove the front member\n'b'\n>>> q.enqueue("d") # add a new member at the back\n>>> print(q) # str(q) also possible\nLinkedListQueue(['b', 'c', 'd'])\n
\n
Initialize the queue with the members of sequence.
\n\nThe members are added to the queue in the order they are in sequence.\nTo create an empty queue, call LinkedListQueue() or LinkedListQueue([]).
\n\nComplexity: O(len(sequence))
\n", "signature": "(sequence: collections.abc.Sequence[typing.Any] = [])"}, {"fullname": "paddles.queue.LinkedListQueue.size", "modulename": "paddles.queue", "qualname": "LinkedListQueue.size", "kind": "function", "doc": "Return how many members the queue has.
\n\nComplexity: O(1)
\n", "signature": "(self) -> int:", "funcdef": "def"}, {"fullname": "paddles.queue.LinkedListQueue.front", "modulename": "paddles.queue", "qualname": "LinkedListQueue.front", "kind": "function", "doc": "Return the member at the front of the queue, without removing it.
\n\nRaise ValueError if the queue is empty.
\n\nComplexity: O(1)
\n", "signature": "(self) -> Any:", "funcdef": "def"}, {"fullname": "paddles.queue.LinkedListQueue.enqueue", "modulename": "paddles.queue", "qualname": "LinkedListQueue.enqueue", "kind": "function", "doc": "Put item at the back of the queue.
\n\nComplexity: O(1)
\n", "signature": "(self, item: Any) -> None:", "funcdef": "def"}, {"fullname": "paddles.queue.LinkedListQueue.dequeue", "modulename": "paddles.queue", "qualname": "LinkedListQueue.dequeue", "kind": "function", "doc": "Remove and return the item at the front of the queue.
\n\nRaise ValueError if the queue is empty.
\n\nComplexity: O(1)
\n", "signature": "(self) -> Any:", "funcdef": "def"}, {"fullname": "paddles.stack", "modulename": "paddles.stack", "kind": "module", "doc": "This module implements the Stack ADT.
\n\nIntuition
\n\nThe Stack ADT models a pile of objects, e.g. a pile of storage boxes.\nOnly the object at the top of the pile can be accessed and removed.\nThe only way to add an object is to put it on top of the existing pile.
\n\nDefinition
\n\nA stack is a sequence where members are removed from and added to\nthe same end of the sequence, called the top of the stack.
\n\nA stack is a last-in, first-out (LIFO) sequence:\nthe next member to be removed is the one most recently added.
\n\nA stack is a sequence ordered by age (time of addition).\nThe oldest member is at the bottom of the stack, and the youngest member is at the top.
\n\nOperations
\n\nThe Stack ADT provides operations to:
\n\n\n- create a new empty stack
\n- add a new member, on top of the existing ones
\n- remove the member at the top of the stack
\n- access the member at the top of the stack without removing it
\n- compute the size of the stack (number of members).
\n
\n\nApplications
\n\nStacks are used to implement function calls and depth-first search.\nYou should consider using a stack when you need to:
\n\n\n- simulate the handling of a pile of objects, like loading and unloading ship containers
\n- process nested structures, like brackets (e.g.
print([1, {2, 3}])) or\nHTML tags (e.g. <p><b>text</b></p>) \n- process items in the reverse order they were added, like undo operations\n(the next command to be undone is the most recently executed one).
\n
\n\nImplementations
\n\nThe Stack ADT can be implemented with dynamic arrays or singly-linked lists.\nIn both cases, the operations listed above take constant time.\nA singly-linked list uses much more memory than a static array of the same length,\nbut a dynamic array may have wasted capacity and requires resizing.
\n"}, {"fullname": "paddles.stack.DynamicArrayStack", "modulename": "paddles.stack", "qualname": "DynamicArrayStack", "kind": "class", "doc": "An implementation of the Stack ADT, using Python lists.
\n\nBesides the ADT's operations, this class provides two convenience operations:
\n\n\n- create a non-empty stack from a given sequence
\n- convert a stack to a string, to see its members listed from bottom to top.
\n
\n\n\n
>>> from paddles.stack import DynamicArrayStack\n>>> stack = DynamicArrayStack("abc") # create a non-empty stack\n>>> stack.size() # number of members\n3\n>>> stack.pop() # remove and return the top member\n'c'\n>>> stack.peek() # return but don't remove the top member\n'b'\n>>> stack.push("C") # add a new member on top\n>>> print(stack) # str(stack) also possible\nDynamicArrayStack(['a', 'b', 'C'])\n
\n
Initialize the stack with the members of sequence.
\n\nThe members are added to the stack in the order they are in sequence.\nTo create an empty stack, call DynamicArrayStack() or DynamicArrayStack([]).
\n\nComplexity: O(len(sequence))
\n", "signature": "(sequence: collections.abc.Sequence[typing.Any] = [])"}, {"fullname": "paddles.stack.DynamicArrayStack.size", "modulename": "paddles.stack", "qualname": "DynamicArrayStack.size", "kind": "function", "doc": "Return how many members the stack has.
\n\nComplexity: O(1)
\n", "signature": "(self) -> int:", "funcdef": "def"}, {"fullname": "paddles.stack.DynamicArrayStack.peek", "modulename": "paddles.stack", "qualname": "DynamicArrayStack.peek", "kind": "function", "doc": "Return the member at the top of the stack, without removing it.
\n\nRaise ValueError if the stack is empty.
\n\nComplexity: O(1)
\n", "signature": "(self) -> Any:", "funcdef": "def"}, {"fullname": "paddles.stack.DynamicArrayStack.push", "modulename": "paddles.stack", "qualname": "DynamicArrayStack.push", "kind": "function", "doc": "Put item on top of the stack.
\n\nComplexity: O(1)
\n", "signature": "(self, item: Any) -> None:", "funcdef": "def"}, {"fullname": "paddles.stack.DynamicArrayStack.pop", "modulename": "paddles.stack", "qualname": "DynamicArrayStack.pop", "kind": "function", "doc": "Remove and return the member at the top of the stack.
\n\nRaise ValueError if the stack is empty.
\n\nComplexity: O(1)
\n", "signature": "(self) -> Any:", "funcdef": "def"}, {"fullname": "paddles.stack.LinkedListStack", "modulename": "paddles.stack", "qualname": "LinkedListStack", "kind": "class", "doc": "An implementation of the Stack ADT, using singly-linked lists.
\n\nBesides the ADT's operations, this class provides two convenience operations:
\n\n\n- create a non-empty stack from a given sequence
\n- convert a stack to a string, to see its members listed from bottom to top.
\n
\n\n\n
>>> from paddles.stack import LinkedListStack\n>>> stack = LinkedListStack("abc") # create a non-empty stack\n>>> stack.size() # number of members\n3\n>>> stack.pop() # remove and return the top member\n'c'\n>>> stack.peek() # return but don't remove the top member\n'b'\n>>> stack.push("C") # add a new member on top\n>>> print(stack) # str(stack) also possible\nLinkedListStack(['a', 'b', 'C'])\n
\n
Initialize the stack with the members of sequence.
\n\nThe members are added to the stack in the order they are in sequence.\nTo create an empty stack, call LinkedListStack() or LinkedListStack([]).
\n\nComplexity: O(len(sequence))
\n", "signature": "(sequence: collections.abc.Sequence[typing.Any] = [])"}, {"fullname": "paddles.stack.LinkedListStack.size", "modulename": "paddles.stack", "qualname": "LinkedListStack.size", "kind": "function", "doc": "Return how many members the stack has.
\n\nComplexity: O(1)
\n", "signature": "(self) -> int:", "funcdef": "def"}, {"fullname": "paddles.stack.LinkedListStack.push", "modulename": "paddles.stack", "qualname": "LinkedListStack.push", "kind": "function", "doc": "Put item on top of the stack.
\n\nComplexity: O(1)
\n", "signature": "(self, item: Any) -> None:", "funcdef": "def"}, {"fullname": "paddles.stack.LinkedListStack.pop", "modulename": "paddles.stack", "qualname": "LinkedListStack.pop", "kind": "function", "doc": "Remove and return the member at the top of the stack.
\n\nRaise ValueError if the stack is empty.
\n\nComplexity: O(1)
\n", "signature": "(self) -> Any:", "funcdef": "def"}, {"fullname": "paddles.stack.LinkedListStack.peek", "modulename": "paddles.stack", "qualname": "LinkedListStack.peek", "kind": "function", "doc": "Return the member at the top of the stack.
\n\nRaise ValueError if the stack is empty.
\n\nComplexity: O(1)
\n", "signature": "(self) -> Any:", "funcdef": "def"}];
// mirrored in build-search-index.js (part 1)
// Also split on html tags. this is a cheap heuristic, but good enough.
diff --git a/paddles/__init__.py b/paddles/__init__.py
index f68b540..2a87b56 100644
--- a/paddles/__init__.py
+++ b/paddles/__init__.py
@@ -1,12 +1,14 @@
"""`paddles` is a pedagogical algorithms and data structures library.
-It currently implements the Stack, Queue and Deque **abstract data types (ADTs)**.
+It currently implements the Stack, Queue and Deque abstract data types (ADTs).
+
+The code repository is at https://github.com/dsa-ou/paddles.
+The formatted documentation is at https://dsa-ou.github.io/paddles.
## Licence
-The code and text in this repository are
-Copyright © 2024 by The Open University, UK.
-The code is licensed under a [BSD-3-clause licence](../LICENSE.MD).
-The text is licensed under a
+`paddles` is Copyright © 2024 by The Open University, UK.
+The code is licensed under a [BSD-3-clause licence](https://github.com/dsa-ou/paddles/blob/main/LICENSE).
+The documentation is licensed under a
[Creative Commons Attribution 4.0 International Licence](http://creativecommons.org/licenses/by/4.0).
"""
diff --git a/paddles/deque.py b/paddles/deque.py
index f28c7c4..2f985e6 100644
--- a/paddles/deque.py
+++ b/paddles/deque.py
@@ -3,13 +3,13 @@
## Intuition
The Deque ADT models a line of objects that can be accessed, added to and
-removed from either end of the line
+removed from either end of the line.
A deque can be used as a [stack](stack.html) or as a [queue](queue.html).
## Definition
A **deque**, pronounced 'deck' and short for 'double-ended queue', is a sequence
-where only the members at both ends of the sequence.
+where only the members at both ends of the sequence
(called the **front** and the **back** of the queue) can be accessed and removed.
New members can only be added at the front or at the back.
@@ -26,10 +26,11 @@
- compute the size of the deque (number of members).
## Applications
-Consider using a deque when you need to simulate a line of objects that can be accessed
-from both ends, like cars on a ferry.
-On one shore, cars leave the ferry from the front and new ones board it from the front.
-On the other shore, cars leave and board the ferry from the back.
+
+Consider using a deque when you need to simulate a queue where
+- objects jump the queue (join at the front) or
+ leave it from the back after waiting a certain time
+- the direction of the queue changes, like cars on a ferry.
## Implementations