Document LinkedList

Author: Xrayez

doc/LinkedList.xml

@@ -1,8 +1,36 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="LinkedList" inherits="Reference" version="3.2">
 	<brief_description>
+		A doubly linked list data structure.
 	</brief_description>
 	<description>
+		A data structure which consists of a set of sequentially linked elements called nodes. Uses [ListNode] as a basic building block. Each node contains a reference to the previous node, the next node, and the data associated with the node. Insertion and deletion operations are faster [code]O(1)[/code] compared to [Array], but performs worse for random access [code]O(n)[/code].
+		[ListNode]s are constructed by inserting values to the list, and are not meant to be instantiated directly:
+		[codeblock]
+		var list = LinkedList.new()
+		var node = list.push_back("Goost")
+		var same_node = list.find("Goost")
+		[/codeblock]
+		Traversing a list can be done using a [code]for[/code] loop:
+		[codeblock]
+		for node in list:
+		    print(node)
+		[/codeblock]
+		or by manually walking the list using the nodes themselves:
+		[codeblock]
+		# Forward!
+		var node = list.front
+		while node:
+		    print(node)
+		    node = node.next
+
+		# Backward!
+		var node = list.back
+		while node:
+		    print(node)
+		    node = node.prev
+		[/codeblock]
+		Nodes can be passed around throughout the code, and values can be changed dynamically for nodes which are already inserted into the list.
 	</description>
 	<tutorials>
 	</tutorials>
@@ -11,6 +39,7 @@
 			<return type="void">
 			</return>
 			<description>
+				Erases all nodes from the list.
 			</description>
 		</method>
 		<method name="create_from">
@@ -19,12 +48,18 @@
 			<argument index="0" name="value" type="Variant">
 			</argument>
 			<description>
+				Initializes the list from a [Variant] compatible type. Clears all nodes before copying.
+				If [code]value[/code] is [code]null[/code], just clears the contents of the list.
+				If [code]value[/code] is [Array], each element in the array is converted to a [ListNode]. Pool*Arrays are converted similarly to [Array].
+				If [code]value[/code] is [Dictionary], each key in the dictionary is converted to a [ListNode], and the values are encoded as [ListNode] meta variables using [method Object.set_meta]. Values can be retrieved later with [code]node.get_meta("value")[/code] for each node.
+				Any other type is simply pushed back to the list.
 			</description>
 		</method>
 		<method name="empty" qualifiers="const">
 			<return type="bool">
 			</return>
 			<description>
+				Returns [code]true[/code] if the list doesn't contain any nodes.
 			</description>
 		</method>
 		<method name="erase">
@@ -33,6 +68,7 @@
 			<argument index="0" name="value" type="Variant">
 			</argument>
 			<description>
+				Erases (deletes) the first found node with a matching value in the list.
 			</description>
 		</method>
 		<method name="find">
@@ -41,18 +77,21 @@
 			<argument index="0" name="value" type="Variant">
 			</argument>
 			<description>
+				Returns a node if a list contains a node with specified value, otherwise returns [code]null[/code].
 			</description>
 		</method>
 		<method name="get_elements">
 			<return type="Array">
 			</return>
 			<description>
+				An alias for [method get_nodes].
 			</description>
 		</method>
 		<method name="get_nodes">
 			<return type="Array">
 			</return>
 			<description>
+				Returns all nodes as an [Array], preserving front-to-back order.
 			</description>
 		</method>
 		<method name="insert_after">
@@ -63,6 +102,7 @@
 			<argument index="1" name="value" type="Variant">
 			</argument>
 			<description>
+				Constructs a new [ListNode] and places it [i]after[/i] existing node in the list. If [code]node[/code] is [code]null[/code], then the value is pushed at the end of the list, making the behavior equivalent to [method push_back].
 			</description>
 		</method>
 		<method name="insert_before">
@@ -73,12 +113,14 @@
 			<argument index="1" name="value" type="Variant">
 			</argument>
 			<description>
+				Constructs a new [ListNode] and places it [i]before[/i] existing node in the list. If [code]node[/code] is [code]null[/code], then the value is pushed at the end of the list, making the behavior equivalent to [method push_back].
 			</description>
 		</method>
 		<method name="invert">
 			<return type="void">
 			</return>
 			<description>
+				Inverts the order of nodes in the list.
 			</description>
 		</method>
 		<method name="move_before">
@@ -89,6 +131,7 @@
 			<argument index="1" name="before_node" type="ListNode">
 			</argument>
 			<description>
+				Moves a node [i]before[/i] the other one within the list.
 			</description>
 		</method>
 		<method name="move_to_back">
@@ -97,6 +140,7 @@
 			<argument index="0" name="node" type="ListNode">
 			</argument>
 			<description>
+				Moves a node to the back of the list ([member back] node will point to [code]node[/code]).
 			</description>
 		</method>
 		<method name="move_to_front">
@@ -105,18 +149,29 @@
 			<argument index="0" name="node" type="ListNode">
 			</argument>
 			<description>
+				Moves a node to the front of the list (the [member front] node will point to [code]node[/code]).
 			</description>
 		</method>
 		<method name="pop_back">
 			<return type="void">
 			</return>
 			<description>
+				Erases the last node of the list. Make sure to preserve the [member ListNode.value] if you're interested in the data associated with the node:
+				[codeblock]
+				var value = list.back.value
+				list.pop_back()
+				[/codeblock]
 			</description>
 		</method>
 		<method name="pop_front">
 			<return type="void">
 			</return>
 			<description>
+				Erases the first node of the list. Make sure to preserve the [member ListNode.value] if you're interested in the data associated with the node:
+				[codeblock]
+				var value = list.front.value
+				list.pop_front()
+				[/codeblock]
 			</description>
 		</method>
 		<method name="push_back">
@@ -125,6 +180,7 @@
 			<argument index="0" name="value" type="Variant">
 			</argument>
 			<description>
+				Constructs a new [ListNode] and pushes it at the [i]end[/i] of the list.
 			</description>
 		</method>
 		<method name="push_front">
@@ -133,6 +189,7 @@
 			<argument index="0" name="value" type="Variant">
 			</argument>
 			<description>
+				Constructs a new [ListNode] and pushes it at the [i]beginning[/i] of the list.
 			</description>
 		</method>
 		<method name="remove">
@@ -141,18 +198,21 @@
 			<argument index="0" name="node" type="ListNode">
 			</argument>
 			<description>
+				Removes (and deletes) an existing node from the list.
 			</description>
 		</method>
 		<method name="size" qualifiers="const">
 			<return type="int">
 			</return>
 			<description>
+				Returns the total number of nodes in the list.
 			</description>
 		</method>
 		<method name="sort">
 			<return type="void">
 			</return>
 			<description>
+				Sorts the list in alphabetical order if the list contains [String]s. If the list contains nodes with different types of values, these are sorted according to the order of [enum @GlobalScope.Variant.Type].
 			</description>
 		</method>
 		<method name="swap">
@@ -163,13 +223,16 @@
 			<argument index="1" name="node_B" type="ListNode">
 			</argument>
 			<description>
+				Moves [code]node_A[/code] to the position of [code]node_B[/code], and moves [code]node_B[/code] to the original position of [code]node_A[/code]. If [code]node_A == node_B[/code], does nothing.
 			</description>
 		</method>
 	</methods>
 	<members>
 		<member name="back" type="ListNode" setter="" getter="get_back">
+			The last node in the list. Can be [code]null[/code] if the list is [method empty].
 		</member>
 		<member name="front" type="ListNode" setter="" getter="get_front">
+			The first node in the list. Can be [code]null[/code] if the list is [method empty].
 		</member>
 	</members>
 	<constants>

tests/project/goost/core/types/test_list.gd

@@ -136,6 +136,21 @@ func test_insert_after_back():
 	assert_eq(list.back.value, "Godot")
 
 
+func test_insert_after_null():
+	populate_test_data(list)
+	list.insert_after(null, "Godot")
+	assert_eq(list.back.value, "Godot")
+
+
+func test_insert_before_null():
+	populate_test_data(list)
+	list.insert_before(null, "Godot")
+	# Not sure about this, see issue upstream from which this was ported:
+	# https://github.com/godotengine/godot/issues/42116
+	# But consistency with builtin List<Variant> is more important currently.
+	assert_eq(list.back.value, "Godot")
+
+
 func test_size():
 	var nodes = populate_test_data(list)
 	var original_size = nodes.size()
@@ -443,7 +458,7 @@ func test_custom_iterators():
 		gut.p(node)
 
 
-func tets_sort():
+func tets_sort_strings():
 	var n: ListNode
 	n = list.push_back("B")
 	assert_eq(n.value, "B")
@@ -469,6 +484,28 @@ func tets_sort():
 		assert_eq(abcd[i], abcd_list[i])
 
 
+func test_sort_variants():
+	list.push_back("Goost")
+	list.push_back(Color.blue)
+	list.push_back(37)
+	list.push_back(Vector2.ONE)
+	list.push_back(true)
+	list.push_back(null)
+	list.push_back(100.0)
+
+	list.sort()
+
+	var nodes = list.get_nodes()
+
+	assert_eq(nodes[0].value, null)
+	assert_eq(nodes[1].value, true)
+	assert_eq(nodes[2].value, 37)
+	assert_eq(nodes[3].value, 100.0)
+	assert_eq(nodes[4].value, "Goost")
+	assert_eq(nodes[5].value, Vector2.ONE)
+	assert_eq(nodes[6].value, Color.blue)
+
+
 func test_print_list_node():
 	var node = list.push_back("Goost")
 	gut.p(node)