[Documentation] Add documentation for ObjectList.mod

objectlist.mod/doc/intro.bbdoc

@@ -0,0 +1,10 @@
+A #TObjectList allows you to conveniently add and remove objects to and from a collection of objects.
+
+It is a #Type bringing together the memory efficient storage
+of arrays and the easy manageability of a #TMap or #TList.
+
+In most cases it is faster than the namend alternatives but of course it 
+depends on the way you are using it in your code. So make sure to
+benchmark according to your individual use case.
+
+Object lists can replace #TList easily when used in OOP-style as they share method names.

objectlist.mod/doc/tobjectlist_addfirst.bmx

@@ -0,0 +1,22 @@
+SuperStrict
+
+Framework Brl.ObjectList
+Import Brl.StandardIO
+
+' create an object list to hold some objects
+Local list:TObjectList = New TObjectList
+
+' add some string objects to the begin of the list
+list.AddFirst("one")
+list.AddFirst("two")
+list.AddFirst("three")
+
+' enumerate all the strings in the list
+For Local a:String = EachIn list
+	Print a
+Next
+
+' outputs:
+' three
+' two
+' one

objectlist.mod/doc/tobjectlist_addlast.bmx

@@ -0,0 +1,22 @@
+SuperStrict
+
+Framework Brl.ObjectList
+Import Brl.StandardIO
+
+' create an object list to hold some objects
+Local list:TObjectList = New TObjectList
+
+' add some string objects to the end of the list
+list.AddLast("one")
+list.AddLast("two")
+list.AddLast("three")
+
+' enumerate all the strings in the list
+For Local a:String = EachIn list
+	Print a
+Next
+
+' outputs:
+' one
+' two
+' three

objectlist.mod/doc/tobjectlist_clear.bmx

@@ -0,0 +1,25 @@
+SuperStrict
+
+Framework Brl.ObjectList
+Import Brl.StandardIO
+
+' create an object list to hold some objects
+Local list:TObjectList = New TObjectList
+
+' add some string objects to the end of the list
+list.AddLast("one")
+list.AddLast("two")
+list.AddLast("three")
+
+' print amount of elements in the list
+Print list.Count()
+
+' clear the list and remove all elements
+list.Clear()
+
+' print amount of elements in the list
+Print list.Count()
+
+' outputs:
+' 3
+' 0

objectlist.mod/doc/tobjectlist_contains.bmx

@@ -0,0 +1,24 @@
+SuperStrict
+
+Framework Brl.ObjectList
+Import Brl.StandardIO
+
+' create an object list to hold some objects
+Local list:TObjectList = New TObjectList
+
+' add some string objects to the end of the list
+list.AddLast("one")
+list.AddLast("two")
+list.AddLast("three")
+
+' check if the list contains some elements
+If list.Contains("four") Then
+	Print "four"
+EndIf
+
+If list.Contains("three") Then
+	Print "three"
+EndIf
+
+' outputs:
+' three

objectlist.mod/doc/tobjectlist_copy.bmx

@@ -0,0 +1,33 @@
+SuperStrict
+
+Framework Brl.ObjectList
+Import Brl.StandardIO
+
+' create an object list to hold some objects
+Local list:TObjectList = New TObjectList
+
+' add some string objects to the end of the list
+list.AddLast("one")
+list.AddLast("two")
+list.AddLast("three")
+
+' copy the list elements into another one
+Local list2:TObjectList = list.Copy()
+
+' enumerate all the strings in the first list
+For Local a:String = EachIn list
+	Print a
+Next
+
+' enumerate all the strings in the second list
+For Local a:String = EachIn list2
+	Print a
+Next
+
+' outputs:
+' one
+' two
+' three
+' one
+' two
+' three

objectlist.mod/doc/tobjectlist_count.bmx

@@ -0,0 +1,19 @@
+SuperStrict
+
+Framework Brl.ObjectList
+Import Brl.StandardIO
+
+' create an object list to hold some objects
+Local list:TObjectList = New TObjectList
+
+
+' add some string objects to the end of the list
+list.AddLast("one")
+list.AddLast("two")
+list.AddLast("three")
+
+' print amount of elements in the list
+Print list.Count()
+
+' outputs:
+' 3

objectlist.mod/doc/tobjectlist_first.bmx

@@ -0,0 +1,23 @@
+SuperStrict
+
+Framework Brl.ObjectList
+Import Brl.StandardIO
+
+' create an object list to hold some objects
+Local list:TObjectList = New TObjectList
+
+
+' add some string objects to the end of the list
+list.AddLast("one")
+list.AddLast("two")
+list.AddLast("three")
+
+
+' request the first element in the list and cast it (back) to a string
+' cast is needed as the function returns "object" rather than "string"
+Local value:String = String(list.First())
+
+Print value
+
+' outputs:
+' one

objectlist.mod/doc/tobjectlist_fromarray.bmx

@@ -0,0 +1,20 @@
+SuperStrict
+
+Framework Brl.ObjectList
+Import Brl.StandardIO
+
+' create an array holding some objects
+Local objects:Object[] = ["one", "two", "three"]
+
+' create a object list out of the elements
+Local list:TObjectList = TObjectList.FromArray(objects) 
+
+' enumerate all the strings in the list
+For Local a:String = EachIn list
+	Print a
+Next
+
+' outputs:
+' one
+' two
+' three

objectlist.mod/doc/tobjectlist_isempty.bmx

@@ -0,0 +1,23 @@
+SuperStrict
+
+Framework Brl.ObjectList
+Import Brl.StandardIO
+
+' create an object list to hold some objects
+Local list:TObjectList = New TObjectList
+
+' add some string objects to the end of the list
+list.AddLast("one")
+list.AddLast("two")
+list.AddLast("three")
+
+' check if the list contains some elements
+If list.IsEmpty() Then
+	Print "list is empty"
+Else
+	Print "list contains elements"
+EndIf
+
+
+' outputs:
+' list contains elements

objectlist.mod/doc/tobjectlist_last.bmx

@@ -0,0 +1,22 @@
+SuperStrict
+
+Framework Brl.ObjectList
+Import Brl.StandardIO
+
+' create an object list to hold some objects
+Local list:TObjectList = New TObjectList
+
+' add some string objects to the end of the list
+list.AddLast("one")
+list.AddLast("two")
+list.AddLast("three")
+
+
+' request the last element in the list and cast it (back) to a string
+' cast is needed as the function returns "object" rather than "string"
+Local value:String = String(list.Last())
+
+Print value
+
+' outputs:
+' three

objectlist.mod/doc/tobjectlist_remove.bmx

@@ -0,0 +1,24 @@
+SuperStrict
+
+Framework Brl.ObjectList
+Import Brl.StandardIO
+
+' create an object list to hold some objects
+Local list:TObjectList = New TObjectList
+
+' add some string objects to the begin of the list
+list.AddLast("one")
+list.AddLast("two")
+list.AddLast("three")
+
+' remove the string "two"
+list.Remove("two")
+
+' enumerate all the strings in the list
+For Local a:String = EachIn list
+	Print a
+Next
+
+' outputs:
+' one
+' three

objectlist.mod/doc/tobjectlist_removefirst.bmx

@@ -0,0 +1,24 @@
+SuperStrict
+
+Framework Brl.ObjectList
+Import Brl.StandardIO
+
+' create an object list to hold some objects
+Local list:TObjectList = New TObjectList
+
+' add some string objects to the begin of the list
+list.AddLast("one")
+list.AddLast("two")
+list.AddLast("three")
+
+' remove the first element of the list
+list.RemoveFirst()
+
+' enumerate all the strings in the list
+For Local a:String = EachIn list
+	Print a
+Next
+
+' outputs:
+' two
+' three

objectlist.mod/doc/tobjectlist_removelast.bmx

@@ -0,0 +1,24 @@
+SuperStrict
+
+Framework Brl.ObjectList
+Import Brl.StandardIO
+
+' create an object list to hold some objects
+Local list:TObjectList = New TObjectList
+
+' add some string objects to the begin of the list
+list.AddLast("one")
+list.AddLast("two")
+list.AddLast("three")
+
+' remove the last element of the list
+list.RemoveLast()
+
+' enumerate all the strings in the list
+For Local a:String = EachIn list
+	Print a
+Next
+
+' outputs:
+' one
+' two

objectlist.mod/doc/tobjectlist_reverse.bmx

@@ -0,0 +1,25 @@
+SuperStrict
+
+Framework Brl.ObjectList
+Import Brl.StandardIO
+
+' create an object list to hold some objects
+Local list:TObjectList = New TObjectList
+
+' add some string objects to the end of the list
+list.AddLast("one")
+list.AddLast("two")
+list.AddLast("three")
+
+' reverse the list
+list.Reverse()
+
+' enumerate all the strings in the list
+For Local a:String = EachIn list
+	Print a
+Next
+
+' outputs:
+' three
+' two
+' one

objectlist.mod/doc/tobjectlist_reversed.bmx

@@ -0,0 +1,33 @@
+SuperStrict
+
+Framework Brl.ObjectList
+Import Brl.StandardIO
+
+' create an object list to hold some objects
+Local list:TObjectList = New TObjectList
+
+' add some string objects to the end of the list
+list.AddLast("one")
+list.AddLast("two")
+list.AddLast("three")
+
+' create another object list containing the elements in reversed order
+Local list2:TObjectList = list.Reversed()
+
+' enumerate all the strings in the first list
+For Local a:String = EachIn list
+	Print a
+Next
+
+' enumerate all the strings in the second list
+For Local a:String = EachIn list2
+	Print a
+Next
+
+' outputs:
+' one
+' two
+' three
+' three
+' two
+' one

objectlist.mod/doc/tobjectlist_sort.bmx

@@ -0,0 +1,54 @@
+SuperStrict
+
+Framework Brl.ObjectList
+Import Brl.StandardIO
+
+' create an object list to hold some objects
+Local list:TObjectList = New TObjectList
+
+' add some string objects to the end of the list
+list.AddLast("short")
+list.AddLast("longer")
+list.AddLast("the longest")
+
+
+' DEFAULT SORT
+' sort them (in this case this leads to an alphabetic sort)
+' second parameter sets sort to ascending or not
+list.Sort(True)
+
+' enumerate all the strings in the list
+For Local a:String = EachIn list
+	Print a
+Next
+
+' outputs:
+' longer
+' short
+' the longest
+
+
+' CUSTOM SORT
+' define a custom compare function
+Function MyCompare:Int( o1:Object, o2:Object )
+	If Len(String(o1)) < Len(String(o2)) Then
+		Return -1 ' o1 before o2
+	ElseIf Len(String(o1)) > Len(String(o2)) Then
+		Return 1 ' o1 after o2
+	Else
+		Return 0 ' equal
+	EndIf
+End Function
+
+' sort them with a custom compare function
+list.Sort(True, MyCompare)
+
+' enumerate all the strings in the list
+For Local a:String = EachIn list
+	Print a
+Next
+
+' outputs:
+' short
+' longer
+' the longest

objectlist.mod/doc/tobjectlist_swap.bmx

@@ -0,0 +1,33 @@
+SuperStrict
+
+Framework Brl.ObjectList
+Import Brl.StandardIO
+
+' create an object list to hold some objects
+Local list:TObjectList = New TObjectList
+
+' add some string objects to the end of the list
+list.AddLast("one")
+list.AddLast("two")
+list.AddLast("three")
+
+
+' create a second object list
+Local list2:TObjectList = New TObjectList
+list2.AddLast("four")
+list2.AddLast("five")
+list2.AddLast("six")
+
+
+' swap the lists
+list.Swap(list2)
+
+' enumerate all the strings in the first list
+For Local a:String = EachIn list
+	Print a
+Next
+
+' outputs:
+' four
+' five
+' six

objectlist.mod/doc/tobjectlist_toarray.bmx

@@ -0,0 +1,25 @@
+SuperStrict
+
+Framework Brl.ObjectList
+Import Brl.StandardIO
+
+' create an object list to hold some objects
+Local list:TObjectList = New TObjectList
+
+' add some string objects to the end of the list
+list.AddLast("one")
+list.AddLast("two")
+list.AddLast("three")
+
+' create an array out of the list elements
+Local objects:Object[] = list.ToArray() 
+
+' enumerate all the strings in the array
+For Local a:String = EachIn objects
+	Print a
+Next
+
+' outputs:
+' one
+' two
+' three

objectlist.mod/doc/tobjectlist_valueatindex.bmx

@@ -0,0 +1,21 @@
+SuperStrict
+
+Framework Brl.ObjectList
+Import Brl.StandardIO
+
+' create an object list to hold some objects
+Local list:TObjectList = New TObjectList
+
+' add some string objects to the end of the list
+list.AddLast("one")
+list.AddLast("two")
+list.AddLast("three")
+
+' find the element at the given index and cast it (back) to a string
+' cast is needed as the function returns "object" rather than "string"
+Local value:String = String(list.ValueAtIndex(1))
+
+Print value 
+
+' outputs:
+' two