brl.map documentation enhancements.

map.mod/intmap.bmx

@@ -16,12 +16,19 @@ Extern
 	Function bmx_map_intmap_copy(dst:Byte Ptr Ptr, _root:Byte Ptr)
 End Extern
 
+Rem
+bbdoc: A key/value (Int/Object) map.
+End Rem
 Type TIntMap
 
 	Method Delete()
 		Clear
 	End Method
 
+	Rem
+	bbdoc: Clears the map.
+	about: Removes all keys and values.
+	End Rem
 	Method Clear()
 ?ngcmod
 		If Not IsEmpty() Then
@@ -31,10 +38,18 @@ Type TIntMap
 		bmx_map_intmap_clear(Varptr _root)
 	End Method
 	
+	Rem
+	bbdoc: Checks if the map is empty.
+	about: #True if @map is empty, otherwise #False.
+	End Rem
 	Method IsEmpty()
 		Return bmx_map_intmap_isempty(Varptr _root)
 	End Method
 	
+	Rem
+	bbdoc: Inserts a key/value pair into the map.
+	about: If the map already contains @key, its value is overwritten with @value. 
+	End Rem
 	Method Insert( key:Int,value:Object )
 		bmx_map_intmap_insert(key, value, Varptr _root)
 ?ngcmod
@@ -42,14 +57,27 @@ Type TIntMap
 ?
 	End Method
 
+	Rem
+	bbdoc: Checks if the map contains @key.
+	returns: #True if the map contains @key.
+	End Rem
 	Method Contains:Int( key:Int )
 		Return bmx_map_intmap_contains(key, Varptr _root)
 	End Method
 	
+	Rem
+	bbdoc: Finds a value given a @key.
+	returns: The value associated with @key.
+	about: If the map does not contain @key, a #Null object is returned.
+	End Rem
 	Method ValueForKey:Object( key:Int )
 		Return bmx_map_intmap_valueforkey(key, Varptr _root)
 	End Method
 	
+	Rem
+	bbdoc: Remove a key/value pair from the map.
+	returns: #True if @key was removed, or #False otherwise.
+	End Rem
 	Method Remove( key:Int )
 ?ngcmod
 		_modCount :+ 1
@@ -67,6 +95,11 @@ Type TIntMap
 		End If
 	End Method
 	
+	Rem
+	bbdoc: Gets the map keys.
+	returns: An enumeration object
+	about: The object returned by #Keys can be used with #EachIn to iterate through the keys in the map.
+	End Rem
 	Method Keys:TIntMapEnumerator()
 		Local nodeenum:TIntNodeEnumerator
 		If Not isEmpty() Then
@@ -84,6 +117,11 @@ Type TIntMap
 		Return mapenum
 	End Method
 	
+	Rem
+	bbdoc: Get the map values.
+	returns: An enumeration object.
+	about: The object returned by #Values can be used with #EachIn to iterate through the values in the map.
+	End Rem
 	Method Values:TIntMapEnumerator()
 		Local nodeenum:TIntNodeEnumerator
 		If Not isEmpty() Then
@@ -101,12 +139,19 @@ Type TIntMap
 		Return mapenum
 	End Method
 	
+	Rem
+	bbdoc: Returns a copy the contents of this map.
+	End Rem
 	Method Copy:TIntMap()
 		Local map:TIntMap=New TIntMap
 		bmx_map_intmap_copy(Varptr map._root, _root)
 		Return map
 	End Method
 	
+	Rem
+	bbdoc: Returns a node enumeration object.
+	about: The object returned by #ObjectEnumerator can be used with #EachIn to iterate through the nodes in the map.
+	End Rem
 	Method ObjectEnumerator:TIntNodeEnumerator()
 		Local nodeenum:TIntNodeEnumerator=New TIntNodeEnumerator
 		nodeenum._node=_FirstNode()
@@ -155,8 +200,12 @@ End Type
 
 Rem
 bbdoc: Int holder for key returned by TIntMap.Keys() enumerator.
+about: Because a single instance of #TIntKey is used during enumeration, #value changes on each iteration.
 End Rem
 Type TIntKey
+	Rem
+	bbdoc: Int key value.
+	End Rem
 	Field value:Int
 End Type
 

map.mod/map.bmx

@@ -186,6 +186,9 @@ End Type
 
 '***** PUBLIC *****
 
+Rem
+bbdoc: An key/value (Object/Object) map backed by a Red/Black tree.
+End Rem
 Type TMap
 
 ?Not Threaded
@@ -193,6 +196,10 @@ Type TMap
 		Clear
 	End Method
 ?
+	Rem
+	bbdoc: Clears the map.
+	about: Removes all keys and values.
+	End Rem
 	Method Clear()
 		If _root=nil Return
 		_root.Clear
@@ -202,10 +209,18 @@ Type TMap
 ?
 	End Method
 	
+	Rem
+	bbdoc: Checks if the map is empty.
+	about: #True if @map is empty, otherwise #False.
+	End Rem
 	Method IsEmpty()
 		Return _root=nil
 	End Method
 	
+	Rem
+	bbdoc: Inserts a key/value pair into the map.
+	about: If the map already contains @key, its value is overwritten with @value. 
+	End Rem
 	Method Insert( key:Object,value:Object )
 
 		Assert key Else "Can't insert Null key into map"
@@ -248,15 +263,28 @@ Type TMap
 		_InsertFixup node
 	End Method
 	
+	Rem
+	bbdoc: Checks if the map contains @key.
+	returns: #True if the map contains @key.
+	End Rem
 	Method Contains( key:Object )
 		Return _FindNode( key )<>nil
 	End Method
 
+	Rem
+	bbdoc: Finds a value given a @key.
+	returns: The value associated with @key.
+	about: If the map does not contain @key, a #Null object is returned.
+	End Rem
 	Method ValueForKey:Object( key:Object )
 		Local node:TNode=_FindNode( key )
 		If node<>nil Return node._value
 	End Method
 	
+	Rem
+	bbdoc: Remove a key/value pair from the map.
+	returns: #True if @key was removed, or #False otherwise.
+	End Rem
 	Method Remove( key:Object )
 		Local node:TNode=_FindNode( key )
 		If node=nil Return 0
@@ -267,6 +295,11 @@ Type TMap
 		Return 1
 	End Method
 	
+	Rem
+	bbdoc: Gets the map keys.
+	returns: An enumeration object
+	about: The object returned by #Keys can be used with #EachIn to iterate through the keys in the map.
+	End Rem
 	Method Keys:TMapEnumerator()
 		Local nodeenum:TNodeEnumerator=New TKeyEnumerator
 		nodeenum._node=_FirstNode()
@@ -279,6 +312,11 @@ Type TMap
 		Return mapenum
 	End Method
 	
+	Rem
+	bbdoc: Get the map values.
+	returns: An enumeration object.
+	about: The object returned by #Values can be used with #EachIn to iterate through the values in the map.
+	End Rem
 	Method Values:TMapEnumerator()
 		Local nodeenum:TNodeEnumerator=New TValueEnumerator
 		nodeenum._node=_FirstNode()
@@ -291,15 +329,22 @@ Type TMap
 		Return mapenum
 	End Method
 	
+	Rem
+	bbdoc: Returns a copy the contents of this map.
+	End Rem
 	Method Copy:TMap()
 		Local map:TMap=New TMap
 		'avoid copying an empty map (_root = nil there), else it borks "eachin"
-		if _root <> nil
+		If _root <> nil
 			map._root=_root.Copy( nil )
-		endif
+		EndIf
 		Return map
 	End Method
 
+	Rem
+	bbdoc: Returns a node enumeration object.
+	about: The object returned by #ObjectEnumerator can be used with #EachIn to iterate through the nodes in the map.
+	End Rem
 	Method ObjectEnumerator:TNodeEnumerator()
 		Local nodeenum:TNodeEnumerator=New TNodeEnumerator
 		nodeenum._node=_FirstNode()
@@ -530,7 +575,7 @@ Type TMap
 End Type
 
 Rem
-bbdoc: Create a map
+bbdoc: Creates a map
 returns: A new map object
 End Rem
 Function CreateMap:TMap()
@@ -538,7 +583,7 @@ Function CreateMap:TMap()
 End Function
 
 Rem
-bbdoc: Clear a map
+bbdoc: Clears a map
 about:
 #ClearMap removes all keys and values from @map
 End Rem
@@ -547,7 +592,7 @@ Function ClearMap( map:TMap )
 End Function
 
 Rem
-bbdoc: Check if a map is empty
+bbdoc: Checks if a map is empty
 returns: True if @map is empty, otherwise false
 End Rem
 Function MapIsEmpty( map:TMap )
@@ -555,7 +600,7 @@ Function MapIsEmpty( map:TMap )
 End Function
 
 Rem
-bbdoc: Insert a key/value pair into a map
+bbdoc: Inserts a key/value pair into a map
 about:
 If @map already contained @key, it's value is overwritten with @value. 
 End Rem
@@ -564,7 +609,7 @@ Function MapInsert( map:TMap,key:Object,value:Object )
 End Function
 
 Rem
-bbdoc: Find a value given a key
+bbdoc: Finds a value given a key
 returns: The value associated with @key
 about:
 If @map does not contain @key, a #Null object is returned.
@@ -574,7 +619,7 @@ Function MapValueForKey:Object( map:TMap,key:Object )
 End Function
 
 Rem
-bbdoc: Check if a map contains a key
+bbdoc: Checks if a map contains a key
 returns: True if @map contains @key
 End Rem
 Function MapContains( map:TMap,key:Object )
@@ -582,14 +627,14 @@ Function MapContains( map:TMap,key:Object )
 End Function
 
 Rem
-bbdoc: Remove a key/value pair from a map
+bbdoc: Removes a key/value pair from a map
 End Rem
 Function MapRemove( map:TMap,key:Object )
 	map.Remove key
 End Function
 
 Rem
-bbdoc: Get map keys
+bbdoc: Gets map keys
 returns: An iterator object
 about:
 The object returned by #MapKeys can be used with #EachIn to iterate through 
@@ -600,7 +645,7 @@ Function MapKeys:TMapEnumerator( map:TMap )
 End Function
 
 Rem
-bbdoc: Get map values
+bbdoc: Gets map values
 returns: An iterator object
 about:
 The object returned by #MapValues can be used with #EachIn to iterate through 
@@ -611,7 +656,7 @@ Function MapValues:TMapEnumerator( map:TMap )
 End Function
 
 Rem
-bbdoc: Copy a map
+bbdoc: Copies a map
 returns: A copy of @map
 End Rem
 Function CopyMap:TMap( map:TMap )

map.mod/ptrmap.bmx

@@ -16,12 +16,19 @@ Extern
 	Function bmx_map_ptrmap_copy(dst:Byte Ptr Ptr, _root:Byte Ptr)
 End Extern
 
+Rem
+bbdoc: A key/value (Byte Ptr/Object) map.
+End Rem
 Type TPtrMap
 
 	Method Delete()
 		Clear
 	End Method
 
+	Rem
+	bbdoc: Clears the map.
+	about: Removes all keys and values.
+	End Rem
 	Method Clear()
 ?ngcmod
 		If Not IsEmpty() Then
@@ -31,10 +38,18 @@ Type TPtrMap
 		bmx_map_ptrmap_clear(Varptr _root)
 	End Method
 	
+	Rem
+	bbdoc: Checks if the map is empty.
+	about: #True if @map is empty, otherwise #False.
+	End Rem
 	Method IsEmpty()
 		Return bmx_map_ptrmap_isempty(Varptr _root)
 	End Method
 	
+	Rem
+	bbdoc: Inserts a key/value pair into the map.
+	about: If the map already contains @key, its value is overwritten with @value. 
+	End Rem
 	Method Insert( key:Byte Ptr,value:Object )
 		bmx_map_ptrmap_insert(key, value, Varptr _root)
 ?ngcmod
@@ -42,14 +57,27 @@ Type TPtrMap
 ?
 	End Method
 
+	Rem
+	bbdoc: Checks if the map contains @key.
+	returns: #True if the map contains @key.
+	End Rem
 	Method Contains:Int( key:Byte Ptr )
 		Return bmx_map_ptrmap_contains(key, Varptr _root)
 	End Method
 	
+	Rem
+	bbdoc: Finds a value given a @key.
+	returns: The value associated with @key.
+	about: If the map does not contain @key, a #Null object is returned.
+	End Rem
 	Method ValueForKey:Object( key:Byte Ptr )
 		Return bmx_map_ptrmap_valueforkey(key, Varptr _root)
 	End Method
 	
+	Rem
+	bbdoc: Remove a key/value pair from the map.
+	returns: #True if @key was removed, or #False otherwise.
+	End Rem
 	Method Remove( key:Byte Ptr )
 ?ngcmod
 		_modCount :+ 1
@@ -67,6 +95,11 @@ Type TPtrMap
 		End If
 	End Method
 	
+	Rem
+	bbdoc: Gets the map keys.
+	returns: An enumeration object
+	about: The object returned by #Keys can be used with #EachIn to iterate through the keys in the map.
+	End Rem
 	Method Keys:TPtrMapEnumerator()
 		Local nodeenum:TPtrNodeEnumerator
 		If Not isEmpty() Then
@@ -84,6 +117,11 @@ Type TPtrMap
 		Return mapenum
 	End Method
 	
+	Rem
+	bbdoc: Get the map values.
+	returns: An enumeration object.
+	about: The object returned by #Values can be used with #EachIn to iterate through the values in the map.
+	End Rem
 	Method Values:TPtrMapEnumerator()
 		Local nodeenum:TPtrNodeEnumerator
 		If Not isEmpty() Then
@@ -101,12 +139,19 @@ Type TPtrMap
 		Return mapenum
 	End Method
 	
+	Rem
+	bbdoc: Returns a copy the contents of this map.
+	End Rem
 	Method Copy:TPtrMap()
 		Local map:TPtrMap=New TPtrMap
 		bmx_map_ptrmap_copy(Varptr map._root, _root)
 		Return map
 	End Method
 	
+	Rem
+	bbdoc: Returns a node enumeration object.
+	about: The object returned by #ObjectEnumerator can be used with #EachIn to iterate through the nodes in the map.
+	End Rem
 	Method ObjectEnumerator:TPtrNodeEnumerator()
 		Local nodeenum:TPtrNodeEnumerator=New TPtrNodeEnumerator
 		nodeenum._node=_FirstNode()
@@ -155,8 +200,12 @@ End Type
 
 Rem
 bbdoc: Byte Ptr holder for key returned by TPtrMap.Keys() enumerator.
+about: Because a single instance of #TPtrKey is used during enumeration, #value changes on each iteration.
 End Rem
 Type TPtrKey
+	Rem
+	bbdoc: Byte Ptr key value.
+	End Rem
 	Field value:Byte Ptr
 End Type
 

map.mod/stringmap.bmx

@@ -16,12 +16,19 @@ Extern
 	Function bmx_map_stringmap_copy(dst:Byte Ptr Ptr, _root:Byte Ptr)
 End Extern
 
+Rem
+bbdoc: A key/value (String/Object) map.
+End Rem
 Type TStringMap
 
 	Method Delete()
 		Clear
 	End Method
 
+	Rem
+	bbdoc: Clears the map.
+	about: Removes all keys and values.
+	End Rem
 	Method Clear()
 ?ngcmod
 		If Not IsEmpty() Then
@@ -31,10 +38,18 @@ Type TStringMap
 		bmx_map_stringmap_clear(Varptr _root)
 	End Method
 	
+	Rem
+	bbdoc: Checks if the map is empty.
+	about: #True if @map is empty, otherwise #False.
+	End Rem
 	Method IsEmpty()
 		Return bmx_map_stringmap_isempty(Varptr _root)
 	End Method
 	
+	Rem
+	bbdoc: Inserts a key/value pair into the map.
+	about: If the map already contains @key, its value is overwritten with @value. 
+	End Rem
 	Method Insert( key:String,value:Object )
 		bmx_map_stringmap_insert(key, value, Varptr _root)
 ?ngcmod
@@ -42,14 +57,27 @@ Type TStringMap
 ?
 	End Method
 
+	Rem
+	bbdoc: Checks if the map contains @key.
+	returns: #True if the map contains @key.
+	End Rem
 	Method Contains:Int( key:String )
 		Return bmx_map_stringmap_contains(key, Varptr _root)
 	End Method
 	
+	Rem
+	bbdoc: Finds a value given a @key.
+	returns: The value associated with @key.
+	about: If the map does not contain @key, a #Null object is returned.
+	End Rem
 	Method ValueForKey:Object( key:String )
 		Return bmx_map_stringmap_valueforkey(key, Varptr _root)
 	End Method
 	
+	Rem
+	bbdoc: Remove a key/value pair from the map.
+	returns: #True if @key was removed, or #False otherwise.
+	End Rem
 	Method Remove( key:String )
 ?ngcmod
 		_modCount :+ 1
@@ -67,6 +95,11 @@ Type TStringMap
 		End If
 	End Method
 	
+	Rem
+	bbdoc: Gets the map keys.
+	returns: An enumeration object
+	about: The object returned by #Keys can be used with #EachIn to iterate through the keys in the map.
+	End Rem
 	Method Keys:TStringMapEnumerator()
 		Local nodeenum:TStringNodeEnumerator
 		If Not isEmpty() Then
@@ -84,6 +117,11 @@ Type TStringMap
 		Return mapenum
 	End Method
 	
+	Rem
+	bbdoc: Get the map values.
+	returns: An enumeration object.
+	about: The object returned by #Values can be used with #EachIn to iterate through the values in the map.
+	End Rem
 	Method Values:TStringMapEnumerator()
 		Local nodeenum:TStringNodeEnumerator
 		If Not isEmpty() Then
@@ -101,12 +139,19 @@ Type TStringMap
 		Return mapenum
 	End Method
 	
+	Rem
+	bbdoc: Returns a copy the contents of this map.
+	End Rem
 	Method Copy:TStringMap()
 		Local map:TStringMap=New TStringMap
 		bmx_map_stringmap_copy(Varptr map._root, _root)
 		Return map
 	End Method
 	
+	Rem
+	bbdoc: Returns a node enumeration object.
+	about: The object returned by #ObjectEnumerator can be used with #EachIn to iterate through the nodes in the map.
+	End Rem
 	Method ObjectEnumerator:TStringNodeEnumerator()
 		Local nodeenum:TStringNodeEnumerator=New TStringNodeEnumerator
 		nodeenum._node=_FirstNode()