HPL2/HPL2 Helper Scripts/Lists - Revision history

Mrbehemo at 01:52, 11 February 2024

2024-02-11T01:52:41Z

Mrbehemo: Added DefaultValue, Capacity, Fill(), Extend(), AddUnique(), ToString(), ==

2024-02-11T01:52:02Z

Added DefaultValue, Capacity, Fill(), Extend(), AddUnique(), ToString(), ==

Mrbehemo at 12:02, 6 January 2024

2024-01-06T12:02:20Z

Mrbehemo at 12:00, 6 January 2024

2024-01-06T12:00:13Z

Mrbehemo at 19:04, 23 December 2023

2023-12-23T19:04:59Z

Mrbehemo at 18:57, 23 December 2023

2023-12-23T18:57:06Z

Mrbehemo at 12:03, 8 December 2023

2023-12-08T12:03:19Z

Mrbehemo at 11:58, 8 December 2023

2023-12-08T11:58:19Z

Mrbehemo: Clarified intro and behaviours sections re. capacity and initialising.

2023-12-08T11:57:43Z

Clarified intro and behaviours sections re. capacity and initialising.

Mrbehemo at 00:30, 25 November 2023

2023-11-25T00:30:16Z

@@ Line 236: / Line 236: @@
 ===Equality===
-The logical equality operator (double equals sing "==") can be used to compare two lists of the same type, just like with other values. It will return true if the lists contain the same number of items and the coresponding data items in the lists have equal values, or if the two lists both point to the same data.
+The logical equality operator (double equals sign "==") can be used to compare two lists of the same type, just like with other values. It will return true if the lists contain the same number of items and the coresponding data items in the lists have equal values, or if the two lists both point to the same data.
 <syntaxhighlight lang="cpp">
 // Example:

@@ Line 147: / Line 147: @@
 string sLatest = myListOfStrings[myListOfStrings.LastIndex];
 // sLatest becomes whatever string was added to the list most recently.
 </syntaxhighlight>
@@ Line 171: / Line 184: @@
 if (!myList.IsFull) myList.Add(1);
 // The condition succeeds if the list has space for another item.
 </syntaxhighlight>
@@ Line 199: / Line 232: @@
 // listA and listB both lists refer to the same 3 strings, and the final content of both listA and listB is: "one", "two", "banana".
 // listC was made as a copy, so it was not affected when listA[2] was changed. listC still has: "one", "two", "three".
 </syntaxhighlight>
@@ Line 236: / Line 292: @@
 ====Set()====
 <syntaxhighlight lang="cpp">
-bool Set(uint aulIndex, int alItem)
+bool Set(uint aulIndex, int alItem, bool abExtend = true)
-bool Set(uint aulIndex, float afItem)
+bool Set(uint aulIndex, float afItem, bool abExtend = true)
-bool Set(uint aulIndex, double adItem)
+bool Set(uint aulIndex, double adItem, bool abExtend = true)
-bool Set(uint aulIndex, bool abItem)
+bool Set(uint aulIndex, bool abItem, bool abExtend = true)
-bool Set(uint aulIndex, string asItem)
+bool Set(uint aulIndex, string asItem, bool abExtend = true)
-bool Set(uint aulIndex, cVector avItem)
+bool Set(uint aulIndex, cVector avItem, bool abExtend = true)
-bool Set(uint aulIndex, cPoint avItem)
+bool Set(uint aulIndex, cPoint avItem, bool abExtend = true)
-bool Set(uint aulIndex, cRotator avItem)
+bool Set(uint aulIndex, cRotator avItem, bool abExtend = true)
 </syntaxhighlight>
-Assigns a new value to an indexed item in the list, if it exists. If the list is shorter than the index or the item cannot be added, this returns false. If it was successfull set, it returns true.
+Assigns a new value to an indexed item in the list.
 #''uint aulIndex'' - The index of the item to be changed.
 #''int alItem, float afItem, double adItem, bool abItem, string asItem, cVector avItem, cPoint avItem, or cRotator avItem'' - The item, of the appropriate type, to be assigned.
 <syntaxhighlight lang="cpp">
-// Example:
+// Example 1:
 myListOfBools.Set(7, false);
 // The bool at index 7 in the list becomes false, replacing the previous one.
 </syntaxhighlight>

@@ Line 842: / Line 842: @@
 string ToString()
 </syntaxhighlight>
-Makes a new string representing the whole list, by joining string versions of each item in the list, and returns the string. (Uses the ToString() method of each node class, and the Join() method of cString.) (Coming soon, this entry is a placeholder!)
+Returns a new string representing the whole list, by getting string versions of each item in the list and joining them. (Uses the ToString() method of each node class, and the Join() method of cString.) (Coming soon, this entry is a placeholder!)

@@ Line 814: / Line 814: @@
-===Arrays from lists===
+===Converting lists===
-cListBase and its derived classes provide the following methods for transforming lists into arrays:
+cListBase and its derived classes provide the following methods for converting lists into other types of collections:
@@ Line 828: / Line 828: @@
 cRotator[] ToArray()
 </syntaxhighlight>
-Makes an new array, where each element in the array is a copy of an item from the list, and returns the array.
+Makes a new array, where each element in the array is a copy of an item from the list, and returns the array.
 ====ToStringArray()====
 <syntaxhighlight lang="cpp">
-string[] ToArray()
+string[] ToStringArray()
 </syntaxhighlight>
-Makes an new array, where each element in the array is a string version of each item in the list, and returns the array. (Uses the ToString() method of each node class.)
+Makes a new string representing the whole list, by joining string versions of each item in the list, and returns the string. (Uses the ToString() method of each node class, and the Join() method of cString.) (Coming soon, this entry is a placeholder!)

@@ Line 5: / Line 5: @@
 =Summary=
-The script file "HelperScripts_Lists.hps" adds support for linked list classes. For beginners or other people not familiar with classes, these are best thought of as new variable types.
+The script file "HelperScripts_Lists.hps" adds support for linked list classes. For beginners or other people not familiar with classes, these are best thought of as new variable types. A linked list, or just "list", is a type of collection that works similarly to an array. Both lists and arrays are ways of grouping multiple variables together under one name.
-A linked list, or just "list", is a type of collection that works similarly to an array. Both lists and arrays are ways of grouping multiple variables together under one name. The advantages to using lists over arrays is that it is programmatically easier (and more performant) to insert, remove or re-order items in the list than it would be with an array.
+There are three main advantages to using lists over arrays. The first is that it is more efficient (and more performant) to insert, remove or re-order items in the list than it would be with an array. The second is that lists can also take up less memory than arrays. The memory requirement of an array is defined by its maximum capacity, whereas the memory requirement of a list is only as much as its current content. And therefore the third advantage is that it is not necessary to know in advance how big a list needs to be - it expands automatically as items are added. (And of course, advanced users may note that there are exceptions when an array would be more efficient, but most users won't need to worry about this.)

@@ Line 86: / Line 86: @@
-===Constructors with initial data===
+===Constructor with data===
 <syntaxhighlight lang="cpp">
 cListBase(float[] afArray)
@@ Line 99: / Line 99: @@
 cListFloat mySecondList = myFirstList;					// Makes a new float list containing the same items as the other list.
 </syntaxhighlight>
+<br>
 <syntaxhighlight lang="cpp">
 cListFloat(float afSingleFloat)

@@ Line 66: / Line 66: @@
-===Constructor with maximum capacity===
+===Constructor with capacity===
 <syntaxhighlight lang="cpp">
 cListBase(uint aulMaxSize)

@@ Line 7: / Line 7: @@
 The script file "HelperScripts_Lists.hps" adds support for linked list classes. For beginners or other people not familiar with classes, this is best thought of as new variable types.
-A linked list, or just "list", is a type of collection that works similarly to an array. The advantages to using lists over arrays is that it is programmatically easier (and more performant) to insert, remove or re-order items in the list than it would be with an array.
+A linked list, or just "list", is a type of collection that works similarly to an array. Both lists and arrays are ways of grouping multiple variables together under one name. The advantages to using lists over arrays is that it is programmatically easier (and more performant) to insert, remove or re-order items in the list than it would be with an array.
 Lists can also take up less memory than arrays. The memory requirement of an array is defined by its maximum capacity, whereas the memory requirement of a list is only as much as its current content. It is not necessary to know in advance how big a list needs to be - it expands automatically as items are added.
@@ Line 66: / Line 66: @@
-===Constructor with maximum size===
+===Constructor with maximum capacity===
 <syntaxhighlight lang="cpp">
 cListBase(uint aulMaxSize)
 </syntaxhighlight>
-If the list is initialised with a constructor, then a maximum length can be specified for the list.
+If the list is initialised with a constructor, then a maximum capacity can be specified for the list.
-<br>If the list is declared without a specific constructor, then the default maximum count is assigned. (65535, or 2^16 - 1).
+<br>If the list is declared without a specific capacity, then the default maximum capacity is assigned, which is 65535 (or 2^16 - 1).
 <syntaxhighlight lang="cpp">
 // Example:
-cListInt listOfIntsDefault;
+cListFloat listOfFloatsDefault;
-cListVector listOfVectorDefault;
+cListVector listOfVectorsDefault;
-cListInt listOfUpToFiveInts = cListInt(5);
+cListFloat listOfUpToFiveFloats = cListFloat(5);
 cListVector listOfUpTo1000Vectors = cListVector(1000);
 </syntaxhighlight>
-The default 65535 (2^16-1) is the maximum size that can be indexed. Using this a or smaller arbitrary limit can help to catch runaway bugs. '''Advanced users''' may try changing the value of mulCountMax to use a smaller default maximum. Using a larger maximum could cause problems.
+The default 65535 (2^16-1) is the maximum capacity that can be indexed. Using this a or smaller arbitrary limit can help to catch runaway bugs. '''Advanced users''' may try changing the value of mulCountMax to use a smaller default maximum. Using a larger maximum will likely cause problems.
 <br>Note that arrays require as much memory as their full capacity even when empty, but lists are only ever as big as their content, so lowering the maximum size of the list does not help performance. But it might be useful in certain situations where a limit is required by design.
@@ Line 88: / Line 89: @@
 <syntaxhighlight lang="cpp">
 cListBase(float[] afArray)
 </syntaxhighlight>
-All the derived list classes ('''except for cListGeneric''') can be initialised with data by passing an array of values of the relevant type.
+Lists can be initialised with data by passing an array of values of the relevant type, or an existing list. The default capacity is used for the new list.
 <syntaxhighlight lang="cpp">
 // Example:
 float[] myArray = { 4, 8, 15, 16, 23, 42 };
-cListFloat myFirstList = cListFloat(myArray);			// Makes a new float list by copying the float array.
+cListFloat myFirstList = cListFloat(myArray);			// Makes a new float list by copying items from the float array.
-cListFloat mySecondList = myFirstList;					// Makes a new float list that is a copy of the other list.
+cListFloat mySecondList = myFirstList;					// Makes a new float list containing the same items as the other list.
 </syntaxhighlight>

@@ Line 319: / Line 319: @@
 </syntaxhighlight>
 ===Getting list items===
@@ Line 464: / Line 434: @@
 string sRandomColor = listOfColors.GetRandom();
 // The string sRandomColor is assigned a random value from listOfColors, and that value is no longer available in the list.
 </syntaxhighlight>