Class Index | File Index

Classes


Class CircularList


Defined in: CircularList.js.

Class Summary
Constructor Attributes Constructor Name and Description
 
CircularList(data, lifecycleListener)
A CircularList is a doubly-linked list consisting of a single cycle with every item appearing once.
Method Summary
Method Attributes Method Name and Description
 
forEach(func)
Iterates over each 'enumerable' item in this circular list once.
 
hide()
Hides a node from the CircularList it is in.
 
 
push(data, lifecycleListener)
Adds some data to a new node immediately before this node in the circular list.
 
The inverse operation of 'hide'.
 
spliceInto(newPrevious)
Adds this CircularList (potentially consisting of one item referring to itself) into another CircularList where the splice point is immediately after the 'newPrevious' node.
 
 
Class Detail
CircularList(data, lifecycleListener)
A CircularList is a doubly-linked list consisting of a single cycle with every item appearing once.

While conceptually it has no start or end, it is useful to be able to iterate over the list segment starting with one item and covering all of the items once.

Parameters:
{object} data
the data to be associated with the beginning of the list. This argument is optional and if it is not provided then this list node will be non enumerable. May be null, but undefined is the same as not providing the argument.
{object} lifecycleListener
see the description of the lifecycleListener property.
Method Detail
forEach(func)
Iterates over each 'enumerable' item in this circular list once. Any item that is not enumerable will not appear. The callback function receives the data item associated with the list node as its first argument and the the list node itself as the second argument.

May not be called from a 'hidden' node.

This function assumes a regular topology - i.e. that the list contains a single cycle, and that all nodes are in that cycle. It is possible to end up with irregular topologies, in which case this method could loop forever. If you expect to call this method on an irregular topology, you should keep track of all nodes you've visited and terminate by returning false when you hit a node you've already visited.

Parameters:
{function} func
a callback function that can optionally take (data, listnode) as its arguments. It will be called for each 'enumerable' item in the list. If it returns the boolean false the iteration will terminate early. May not be null.

hide()
Hides a node from the CircularList it is in.

While hidden, the CircularList it was in will no longer see it, but it can be easily restored. Hidden nodes cannot be iterated from.

Hiding creates a CircularList segment (consisting of this node) with an irregular topology.

It is safe to do if either:

  1. No modifications are done to the list it was hidden from other while this node is hidden
  2. The only modifications are to hide other nodes, and when this node is restored, all other hidden nodes will also be restored. (The usecase of the dancing-links algorithm)
Calling hide on a node already hidden does nothing.

{boolean} isEmpty()
Returns:
{boolean} true if this list contains no enumerable items, false otherwise.

{CircularList} push(data, lifecycleListener)
Adds some data to a new node immediately before this node in the circular list.

The fact that it adds it before may seem weird, but that's because I want a CircuclarList to behave a lot like a normal list, and when you call push on a normal list you expect it to add to the end. In a CircularList, adding before a node is the same as adding to the end of the list segment that starts with the current node and covers all the nodes in the list.

Parameters:
{Object} data
the data to be added to the list. May not be undefined but may be null.
{Object} lifecycleListener
an optional listener to be notified of changes to the node created to hold this data.
Returns:
{CircularList} the node containing the newly pushed data.

restore()
The inverse operation of 'hide'. Will restore a node into the same position in an earlier circular list. This operation overwrites the links of the nodes surrounding it, so it may corrupt the topology of the original circular list if it has been changed while this node has been hidden. See hide for more details.

Calling restore on a node that isn't hidden will not do anything.


spliceInto(newPrevious)
Adds this CircularList (potentially consisting of one item referring to itself) into another CircularList where the splice point is immediately after the 'newPrevious' node.

For example:

    a → b → c → d → {wraps back to a}
    x → y → z → {wraps back to x}
if spliceInto is called with x.spliceInto(b) you will end up with a circular list
    a → b → x → y → z → c → d → {wraps back to a}
Parameters:
{CircularList} newPrevious
the CircularList node that this CircularList will be inserted after.

{Array} toArray()
Returns:
{Array} an array containing each data item in this list. Will never be null. May not be called from a 'hidden' node.

toString()

Documentation generated by JsDoc Toolkit 2.4.0 on Sat Aug 19 2017 12:52:27 GMT+0000 (UTC)