//
//------------------ DOK FILE --------------------------------------------------
+Header	hashmapLib
=pkg	bios
=title	Hashsets
=short	a simple set of elements
=desc	
Hashsets let you handle set of elements.
Then it makes it efficient to determine whether an element is in the set.
//
//
//------------------ PROTO ----------------------------------------------------- hashset
+Proto	hashset
=type	hashset a1
=mode	type
=pkg	language
=impl	mcy
=link	
=desc	
A hashset has type 'hashset a1'. For example you may create a hashset of floating numbers: hashset Float
The implementation is quite simple: the hashset is an array of lists of keys. A kind of hash function is applied to the key to determine in which list of the array the key will be added.
Therefore it is necessary to specify the length of this array. This length is always a power of 2.
//
//
//------------------ PROTO ----------------------------------------------------- hashsetInit
+Proto	hashsetInit
=type	fun Int list a1 -> hashset a1
=mode	Function
=pkg	bios
=impl	mcy
=link	
=desc	A new hashset is created and filled with the elements from the list lData.
//
+arg	bitSize
=type	Int
=desc	A number of bits
//
+arg	lData
=type	list a1
=desc	A list of elements
//
+arg	result
=type	hashset a1
=desc	A new hashset
//
//
//------------------ PROTO ----------------------------------------------------- hashsetTest
+Proto	hashsetTest
=type	fun hashset a1 (fun a1 -> Bool) -> Bool
=mode	Function
=pkg	bios
=impl	mcy
=link	
=desc	
This function runs through the hashset and calls the fSearch function for each element.
When this function returns true, the search ends and the function returns true.
//
+arg	src
=type	hashset a1
=desc	Any hashset
//
+arg	fSearch
=type	fun a1 -> Bool
=desc	A lambda function which takes one parameters and returns a boolean
//
+arg	result
=type	Bool
=desc	A boolean
//
//
//------------------ PROTO ----------------------------------------------------- listFromHashset
+Proto	listFromHashset
=type	fun hashset a1 -> list a1
=mode	Function
=pkg	bios
=impl	mcy
=link	
=desc	
This function returns the list of elements currently in the hashset.
The order in the list is irrelevant, it cannot be anticipated.
//
+arg	src
=type	hashset a1
=desc	Any hashset
//
+arg	result
=type	list a1
=desc	The list of elements
//
//
//------------------ PROTO ----------------------------------------------------- hashsetMap
+Proto	hashsetMap
=type	fun hashset a1 (fun a1 -> a2) -> list a2
=mode	Function
=pkg	bios
=impl	mcy
=link	
=desc	This function runs through the hashset src, and calls fMap for each element and makes a list of all its non nil results.
//
+arg	src
=type	hashset a1
=desc	Any hashset
//
+arg	fMap
=type	fun a1 -> a2
=desc	A lambda function that associates an element to another value of any type
//
+arg	result
=type	list a2
=desc	A list
//
//
//------------------ PROTO ----------------------------------------------------- hashsetFind
+Proto	hashsetFind
=type	fun hashset a1 (fun a1 -> Bool) -> a1
=mode	Function
=pkg	bios
=impl	mcy
=link	
=desc	
This function runs through the hashset and calls the fSearch function for each element.
When this function returns true, the search ends and the function returns the element.
//
+arg	src
=type	hashset a1
=desc	Any hashset
//
+arg	fSearch
=type	fun a1 -> Bool
=desc	A lambda function which takes one element and returns a boolean
//
+arg	result
=type	a1
=desc	The element
//
//
//------------------ PROTO ----------------------------------------------------- hashsetCount
+Proto	hashsetCount
=type	fun hashset a1 -> Int
=mode	Function
=pkg	bios
=impl	mcy
=link	
=desc	
This function returns the number of elements in the hashset.
//
+arg	h
=type	hashset a1
=desc	any hashset
//
+arg	result
=type	Int
=desc	The number of elements in the hashset
//
//
//------------------ PROTO ----------------------------------------------------- hashsetRemove
+Proto	hashsetRemove
=type	fun hashset a1 a1 -> Bool
=mode	Function
=pkg	bios
=impl	mcy
=link	
=desc	
This function removes an element from a hashset.
//
+arg	h
=type	hashset a1
=desc	A hashset
//
+arg	val
=type	a1
=desc	An element
//
+arg	result
=type	Bool
=desc	Returns [[true]] if the element was in the hashset
//
//
//------------------ PROTO ----------------------------------------------------- hashsetAdd
+Proto	hashsetAdd
=type	fun hashset a1 a1 -> a1
=mode	Function
=pkg	bios
=impl	mcy
=link	
=desc	
This function adds an element in a hashset.
//
+arg	h
=type	hashset a1
=desc	A hashset
//
+arg	val
=type	a1
=desc	An element
//
+arg	result
=type	a1
=desc	The element
//
//
//------------------ PROTO ----------------------------------------------------- hashsetContains
+Proto	hashsetContains
=type	fun hashset a1 a1 -> Bool
=mode	Function
=pkg	bios
=impl	mcy
=link	
=desc	
This function checks whether an element is in a hashset.
//
+arg	h
=type	hashset a1
=desc	A hashset
//
+arg	val
=type	a1
=desc	An element
//
+arg	result
=type	Bool
=desc	true if the element is in the hashset
//
//
//------------------ PROTO ----------------------------------------------------- hashsetCreate
+Proto	hashsetCreate
=type	fun Int -> hashset a1
=mode	Function
=pkg	bios
=impl	mcy
=link	
=desc	
This function creates a new hashset. The internal implementation of hashmaps is an array of lists of couples (key, [[true]]).
The length of the array is expressed by bitSize. The actual length is 2 power bitSize.
When bitSize is 4, the internal array has length 2**4 = 16.
The higher the bitSize, the faster the hashset will be.
//
+arg	bitSize
=type	Int
=desc	A number of bits
//
+arg	result
=type	hashset a1
=desc	A new hashset
//
//