paweld/fpc
1
0
Fork 0
mirror of https://gitlab.com/freepascal.org/fpc/source.git synced 2025-12-04 13:47:23 +01:00
Code Issues Packages Projects Releases Wiki Activity

doc update for fcl-stl

Browse Source 
git-svn-id: trunk@19054 -
This commit is contained in:
vladob 2011-09-12 10:15:17 +00:00
parent 76b511bec5
commit 863da422df
8 changed files with 227 additions and 57 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
.gitattributes vendored
View File

@ -2328,8 +2328,11 @@ packages/fcl-stl/Makefile.fpc svneol=native#text/plain
packages/fcl-stl/doc/arrayutils.tex svneol=native#text/plain
packages/fcl-stl/doc/deque.tex svneol=native#text/plain
packages/fcl-stl/doc/dequeexample.pp svneol=native#text/plain
packages/fcl-stl/doc/hashmap.tex svneol=native#text/plain
packages/fcl-stl/doc/hashmapexample.pp svneol=native#text/plain
packages/fcl-stl/doc/hashset.tex svneol=native#text/plain
packages/fcl-stl/doc/hashsetexample.pp svneol=native#text/plain
packages/fcl-stl/doc/main.pdf -text
packages/fcl-stl/doc/main.tex svneol=native#text/plain
packages/fcl-stl/doc/makra.tex svneol=native#text/plain
packages/fcl-stl/doc/map.tex svneol=native#text/plain

6
packages/fcl-stl/doc/arrayutils.tex
View File

@ -44,4 +44,10 @@ O(N log N) average and worst case. Uses QuickSort, backed up by HeapSort, when Q
using too much recursion.\\ \hline
\multicolumn{2}{|m{15cm}|}{Sort array arr, with specified size. Array indexing should be 0 based.} \\\hline\hline
\verb!function NextPermutation! \verb!(arr: TArr, size:SizeUint):boolean! &
Worst case for one call $O(N)$. Going through all permutations takes $O(N!)$ time.\\ \hline
\multicolumn{2}{|m{15cm}|}{Orders elements on indexes $0, 1, \dots, size-1$ into nearest
lexikografic larger permutation.} \\\hline
\end{longtable}

72
packages/fcl-stl/doc/hashmap.tex Normal file
View File

@ -0,0 +1,72 @@
\chapter{THashMap}
Implements container for unordered associative array with unique keys.
Takes 3 arguments for specialization, first one is type of keys, second one is type of values, third
one is is a hash functor
(class which has class function hash, which takes element and number $n$ and returns hash of the
element in range $0, 1, \dots, n-1$).
Usage example:
\lstinputlisting[language=Pascal]{hashmapexample.pp}
Memory complexity:
Arounds two times of size of stored elements
Members list:
\begin{longtable}{|m{10cm}|m{5cm}|}
\hline
Method & Complexity guarantees \\ \hline
\multicolumn{2}{|m{15cm}|}{Description} \\ \hline\hline
\verb!Create! & O(1) \\ \hline
\multicolumn{2}{|m{15cm}|}{Constructor. Creates empty map.} \\ \hline\hline
\verb!function Size(): SizeUInt! & O(1) \\ \hline
\multicolumn{2}{|m{15cm}|}{Returns number of elements in map.} \\\hline\hline
\verb!procedure Insert(key: TKey; value: TValue)! &
O(1) \\ \hline
\multicolumn{2}{|m{15cm}|}{Inserts key value pair into map. If key was already there, it will have
new value assigned.} \\\hline\hline
\verb!procedure Delete(key: TKey)! &
O(lg N) \\ \hline
\multicolumn{2}{|m{15cm}|}{Deletes key (and associated value) from map. If element is not in map, nothing happens.} \\\hline\hline
\verb!function Contains(key: TKey):boolean! & O(1) on average \\\hline
\multicolumn{2}{|m{15cm}|}{Checks whether element with given key is in map.} \\\hline\hline
\verb!function Iterator:TIterator! & O(1) on average \\\hline
\multicolumn{2}{|m{15cm}|}{Returns iterator allowing traversal through map. If map is empty returns nil.} \\\hline\hline
\verb!function IsEmpty(): boolean! & O(1) \\ \hline
\multicolumn{2}{|m{15cm}|}{Returns true when map is empty.} \\\hline
\verb!property item[i: Key]: TValue; default;! & O(1) on average \\\hline
\multicolumn{2}{|m{15cm}|}{Property for accessing key i in map. Can be used just by square
brackets (its default property).} \\\hline\hline
\end{longtable}
Some methods return type TIterator, which has following methods:
\begin{longtable}{|m{10cm}|m{5cm}|}
\hline
Method & Complexity guarantees \\ \hline
\multicolumn{2}{|m{15cm}|}{Description} \\ \hline\hline
\verb!function Next:boolean! & O(N) worst case, but traversal of whole set takes O(N) time \\\hline
\multicolumn{2}{|m{15cm}|}{Moves iterator to next larger element in set. Returns true on
success. If the iterator is already pointing on last element returns false.} \\\hline\hline
\verb!property Key:TKey! & $O(1)$ \\\hline
\multicolumn{2}{|m{15cm}|}{Property, which allows reading the key.} \\\hline
\verb!property Value:TValue! & $O(1)$ \\\hline
\multicolumn{2}{|m{15cm}|}{Property, which allows reading and writing of the value.} \\\hline
\verb!property MutableValue:PValue! & $O(1)$ \\\hline
\multicolumn{2}{|m{15cm}|}{Returns pointer on stored value. Usefull for accessing records and
objects.} \\\hline
\end{longtable}

58
packages/fcl-stl/doc/hashset.tex Normal file
View File

@ -0,0 +1,58 @@
\chapter{THashSet}
Implements container for storing unordered set of unique elements.
Takes 2 arguments for specialization, first one is type of elements, second one is a hash functor
(class which has class function hash, which takes element and number $n$ and returns hash of the
element in range $0, 1, \dots, n-1$).
Usage example:
\lstinputlisting[language=Pascal]{hashsetexample.pp}
Memory complexity:
Arounds two times of size of stored elements
Members list:
\begin{longtable}{|m{10cm}|m{5cm}|}
\hline
Method & Complexity guarantees \\ \hline
\multicolumn{2}{|m{15cm}|}{Description} \\ \hline\hline
\verb!Create! & O(1) \\ \hline
\multicolumn{2}{|m{15cm}|}{Constructor. Creates empty set.} \\ \hline\hline
\verb!function Size(): SizeUInt! & O(1) \\ \hline
\multicolumn{2}{|m{15cm}|}{Returns number of elements in set.} \\\hline\hline
\verb!procedure Insert(value: T)! &
O(1) on average \\ \hline
\multicolumn{2}{|m{15cm}|}{Inserts element into set, if given element is already there nothing
happens.} \\\hline\hline
\verb!procedure Delete(value: T)! &
O(1) on average \\ \hline
\multicolumn{2}{|m{15cm}|}{Deletes value from set. If element is not in set, nothing happens.} \\\hline\hline
\verb!function Contains(value: T):boolean! & O(1) on average \\\hline
\multicolumn{2}{|m{15cm}|}{Checks whether element is in set.} \\\hline\hline
\verb!function Iterator:TIterator! & O(1) \\\hline
\multicolumn{2}{|m{15cm}|}{Returns iterator allowing traversal through set. If set is empty returns nil.} \\\hline\hline
\verb!function IsEmpty(): boolean! & O(1) \\ \hline
\multicolumn{2}{|m{15cm}|}{Returns true when set is empty.} \\\hline
\end{longtable}
Some methods return type TIterator, which has following methods:
\begin{longtable}{|m{10cm}|m{5cm}|}
\hline
Method & Complexity guarantees \\ \hline
\multicolumn{2}{|m{15cm}|}{Description} \\ \hline\hline
\verb!function Next:boolean! & O(N) worst case, but traversal of whole set takes O(N) time \\\hline
\multicolumn{2}{|m{15cm}|}{Moves iterator to next larger element in set. Returns true on
success. If the iterator is already pointing on last element returns false.} \\\hline\hline
\verb!property Data:T! & $O(1)$ \\\hline
\multicolumn{2}{|m{15cm}|}{Property, which allows reading of the element.} \\\hline
\end{longtable}

BIN
packages/fcl-stl/doc/main.pdf Normal file
View File

Binary file not shown.

2
packages/fcl-stl/doc/main.tex
View File

@ -59,5 +59,7 @@
\input{arrayutils.tex}
\input{set.tex}
\input{map.tex}
\input{hashset.tex}
\input{hashmap.tex}
\end{document}

75
packages/fcl-stl/doc/map.tex
View File

@ -7,11 +7,6 @@ Usage example:
\lstinputlisting[language=Pascal]{mapexample.pp}
Some methods return type TMSet.PNode. Usefull fields are Data.Key, Data.Value, for retrieving
actual Key and Value from node. This node can be also used for navigation between elements by methods of set class.
You can also change value in node (but not key).
(But don't do anything else with it, you can lose data integrity.)
Memory complexity:
Size of stored base + constant overhead for each stored element (3 pointers + one boolean).
@ -33,55 +28,75 @@ O(lg N), N is number of elements in map \\ \hline
\multicolumn{2}{|m{15cm}|}{Inserts key value pair into map. If key was already there, it will have
new value assigned.} \\\hline\hline
\verb!function InsertAndGetIterator! & $O(\lg N)$\\
\verb!(key:TKey; value: TValue):TIterator! & \\ \hline
\multicolumn{2}{|m{15cm}|}{Same as Insert but also returns iterator poiting to inserted element.} \\\hline\hline
\verb!procedure Delete(key: TKey)! &
O(lg N) \\ \hline
\multicolumn{2}{|m{15cm}|}{Deletes key (and associated value) from map. If element is not in map, nothing happens.} \\\hline\hline
\verb!function Find(key: T):TMSet.PNode! & O(lg N) \\\hline
\verb!function Find(key: T):TIterator! & O(lg N) \\\hline
\multicolumn{2}{|m{15cm}|}{Searches for key in map. If value is not there returns nil. Otherwise
returns pointer to tree node (type TMSet.PNode), which can be used for retrieving data from map.} \\\hline\hline
returns iterator, which can be used for retrieving data from map.} \\\hline\hline
\verb!function FindLess(key: T):TMSet.PNode! & O(lg N) \\\hline
\verb!function FindLess(key: T):TIterator! & O(lg N) \\\hline
\multicolumn{2}{|m{15cm}|}{Searches for greatest element less than key in map. If such element is not there returns nil. Otherwise
returns pointer to tree node (type TMSet.PNode), which can be used for retrieving data from map.} \\\hline\hline
returns iterator, which can be used for retrieving data from map.} \\\hline\hline
\verb!function FindLessEqual(key: T):TMSet.PNode! & O(lg N) \\\hline
\verb!function FindLessEqual(key: T):TIterator! & O(lg N) \\\hline
\multicolumn{2}{|m{15cm}|}{Searches for greatest element less or equal than key in map. If such element is not there returns nil. Otherwise
returns pointer to tree node (type TMSet.PNode), which can be used for retrieving data from map.} \\\hline\hline
returns iterator, which can be used for retrieving data from map.} \\\hline\hline
\verb!function FindGreater(key: T):TMSet.PNode! & O(lg N) \\\hline
\verb!function FindGreater(key: T):TIterator! & O(lg N) \\\hline
\multicolumn{2}{|m{15cm}|}{Searches for smallest element greater than key in map. If such element is not there returns nil. Otherwise
returns pointer to tree node (type TMSet.PNode), which can be used for retrieving data from map.} \\\hline\hline
returns iterator, which can be used for retrieving data from map.} \\\hline\hline
\verb!function FindGreaterEqual(key: T):TMSet.PNode! & O(lg N) \\\hline
\verb!function FindGreaterEqual(key: T):TIterator! & O(lg N) \\\hline
\multicolumn{2}{|m{15cm}|}{Searches for smallest element greater or equal than key in map. If such element is not there returns nil. Otherwise
returns pointer to tree node (type TMSet.PNode), which can be used for retrieving data from map.} \\\hline\hline
returns iterator, which can be used for retrieving data from map.} \\\hline\hline
\verb!function Min:TMSet.PNode! & O(lg N) \\\hline
\multicolumn{2}{|m{15cm}|}{Returns node containing smallest key of map. If map is empty returns
\verb!function Min:TIterator! & O(lg N) \\\hline
\multicolumn{2}{|m{15cm}|}{Returns iterator pointing to smallest key of map. If map is empty returns
nil.} \\\hline\hline
\verb!function Max:TMSet.PNode! & O(lg N) \\\hline
\multicolumn{2}{|m{15cm}|}{Returns node containing largest key of map. If map is empty returns
\verb!function Max:TIterator! & O(lg N) \\\hline
\multicolumn{2}{|m{15cm}|}{Returns iterator pointing to largest key of map. If map is empty returns
nil.} \\\hline\hline
\verb!function Next(x:TMSet.PNode):TMSet.PNode! & O(lg N) worst case, but traversal from smallest element to
largest takes O(N) time \\\hline
\multicolumn{2}{|m{15cm}|}{Returns successor of x. If x is largest key of map, returns nil.} \\\hline\hline
\verb!function Prev(x:TMSet.PNode):TMSet.PNode! & O(lg N) worst case, but traversal from largest element to
smallest takes O(N) time \\\hline
\multicolumn{2}{|m{15cm}|}{Returns predecessor of x. If x is smallest key of map, returns nil.} \\\hline\hline
\verb!function IsEmpty(): boolean! & O(1) \\ \hline
\multicolumn{2}{|m{15cm}|}{Returns true when map is empty.} \\\hline
\verb!function GetValue(key:TKey):TValue! & O(lg N) \\\hline
\multicolumn{2}{|m{15cm}|}{Returns value associated with key. Is key isn't in map crashes.} \\\hline
\verb!property item[i: Key]: TValue; default;! & O(ln N) \\\hline
\multicolumn{2}{|m{15cm}|}{Property for accessing key i in map. Can be used just by square
brackets (its default property).} \\\hline\hline
\end{longtable}
Some methods return type TIterator, which has following methods:
\begin{longtable}{|m{10cm}|m{5cm}|}
\hline
Method & Complexity guarantees \\ \hline
\multicolumn{2}{|m{15cm}|}{Description} \\ \hline\hline
\verb!function Next:boolean! & O(lg N) worst case, but traversal from smallest element to
largest takes O(N) time \\\hline
\multicolumn{2}{|m{15cm}|}{Moves iterator to element with smallest larger key. Returns true on
success. If the iterator is already pointing on element with largest key returns false.} \\\hline\hline
\verb!function Prev:boolean! & O(lg N) worst case, but traversal from largest element to
smallest takes O(N) time \\\hline
\multicolumn{2}{|m{15cm}|}{Moves iterator to element with largest smaller key. Returns true on
success. If the iterator is already pointing on element with smallest key returns false.} \\\hline\hline
\verb!property Key:TKey! & $O(1)$ \\\hline
\multicolumn{2}{|m{15cm}|}{Property, which allows reading the key.} \\\hline
\verb!property Value:TValue! & $O(1)$ \\\hline
\multicolumn{2}{|m{15cm}|}{Property, which allows reading and writing of the value.} \\\hline
\verb!property MutableValue:PValue! & $O(1)$ \\\hline
\multicolumn{2}{|m{15cm}|}{Returns pointer on stored value. Usefull for accessing records and
objects.} \\\hline
\end{longtable}

68
packages/fcl-stl/doc/set.tex
View File

@ -6,10 +6,6 @@ Usage example:
\lstinputlisting[language=Pascal]{setexample.pp}
Some methods return type of PNode. It has field Data, which can be used for retrieving data from
that node. This node can be also used for navigation between elements by methods of set class.
(But don't do anything else with it, you can lose data integrity.)
Memory complexity:
Size of stored elements + constant overhead for each stored element (3 pointers + one boolean).
@ -28,49 +24,67 @@ Method & Complexity guarantees \\ \hline
\verb!procedure Insert(value: T)! &
O(lg N), N is number of elements in set \\ \hline
\multicolumn{2}{|m{15cm}|}{Inserts element into set.} \\\hline\hline
\multicolumn{2}{|m{15cm}|}{Inserts element into set, if given element is already there nothing
happens.} \\\hline\hline
\verb!function InsertAndGetIterator! & $O(\lg N)$\\
\verb!(value: T):TIterator! & \\ \hline
\multicolumn{2}{|m{15cm}|}{Inserts element into set, if given element is already there nothing
happens. Also returns iterator pointing on given element.} \\\hline\hline
\verb!procedure Delete(value: T)! &
O(lg N), N is number of elements in set \\ \hline
\multicolumn{2}{|m{15cm}|}{Deletes value from set. If element is not in set, nothing happens.} \\\hline\hline
\verb!function Find(value: T):PNode! & O(lg N) \\\hline
\verb!function Find(value: T):TIterator! & O(lg N) \\\hline
\multicolumn{2}{|m{15cm}|}{Searches for value in set. If value is not there returns nil. Otherwise
returns pointer to tree node (type PNode), which can be used for retrieving data from set.} \\\hline\hline
returns iterator, which can be used for retrieving data from set.} \\\hline\hline
\verb!function FindLess(value: T):PNode! & O(lg N) \\\hline
\verb!function FindLess(value: T):TIterator! & O(lg N) \\\hline
\multicolumn{2}{|m{15cm}|}{Searches for greatest element less than value in set. If such element is not there returns nil. Otherwise
returns pointer to tree node (type PNode), which can be used for retrieving data from set.} \\\hline\hline
returns iterator, which can be used for retrieving data from set.} \\\hline\hline
\verb!function FindLessEqual(value: T):PNode! & O(lg N) \\\hline
\verb!function FindLessEqual(value: T):TIterator! & O(lg N) \\\hline
\multicolumn{2}{|m{15cm}|}{Searches for greatest element less or equal than value in set. If such element is not there returns nil. Otherwise
returns pointer to tree node (type PNode), which can be used for retrieving data from set.} \\\hline\hline
returns iterator, which can be used for retrieving data from set.} \\\hline\hline
\verb!function FindGreater(value: T):PNode! & O(lg N) \\\hline
\verb!function FindGreater(value: T):TIterator! & O(lg N) \\\hline
\multicolumn{2}{|m{15cm}|}{Searches for smallest element greater than value in set. If such element is not there returns nil. Otherwise
returns pointer to tree node (type PNode), which can be used for retrieving data from set.} \\\hline\hline
returns iterator, which can be used for retrieving data from set.} \\\hline\hline
\verb!function FindGreaterEqual(value: T):PNode! & O(lg N) \\\hline
\verb!function FindGreaterEqual(value: T):TIterator! & O(lg N) \\\hline
\multicolumn{2}{|m{15cm}|}{Searches for smallest element greater or equal than value in set. If such element is not there returns nil. Otherwise
returns pointer to tree node (type PNode), which can be used for retrieving data from set.} \\\hline\hline
returns iterator, which can be used for retrieving data from set.} \\\hline\hline
\verb!function Min:PNode! & O(lg N) \\\hline
\multicolumn{2}{|m{15cm}|}{Returns node containing smallest element of set. If set is empty returns
\verb!function Min:TIterator! & O(lg N) \\\hline
\multicolumn{2}{|m{15cm}|}{Returns iterator pointing to the smallest element of set. If set is empty returns
nil.} \\\hline\hline
\verb!function Max:PNode! & O(lg N) \\\hline
\multicolumn{2}{|m{15cm}|}{Returns node containing largest element of set. If set is empty returns
\verb!function Max:TIterator! & O(lg N) \\\hline
\multicolumn{2}{|m{15cm}|}{Returns iterator pointing to the largest element of set. If set is empty returns
nil.} \\\hline\hline
\verb!function Next(x:PNode):PNode! & O(lg N) worst case, but traversal from smallest element to
largest takes O(N) time \\\hline
\multicolumn{2}{|m{15cm}|}{Returns successor of x. If x is largest element of set, returns nil.} \\\hline\hline
\verb!function Prev(x:PNode):PNode! & O(lg N) worst case, but traversal from largest element to
smallest takes O(N) time \\\hline
\multicolumn{2}{|m{15cm}|}{Returns predecessor of x. If x is smallest element of set, returns nil.} \\\hline\hline
\verb!function IsEmpty(): boolean! & O(1) \\ \hline
\multicolumn{2}{|m{15cm}|}{Returns true when set is empty.} \\\hline
\end{longtable}
Some methods return type TIterator, which has following methods:
\begin{longtable}{|m{10cm}|m{5cm}|}
\hline
Method & Complexity guarantees \\ \hline
\multicolumn{2}{|m{15cm}|}{Description} \\ \hline\hline
\verb!function Next:boolean! & O(lg N) worst case, but traversal from smallest element to
largest takes O(N) time \\\hline
\multicolumn{2}{|m{15cm}|}{Moves iterator to smallest larger element in set. Returns true on
success. If the iterator is already pointing on largest element returns false.} \\\hline\hline
\verb!function Prev:boolean! & O(lg N) worst case, but traversal from largest element to
smallest takes O(N) time \\\hline
\multicolumn{2}{|m{15cm}|}{Moves iterator to largest smaller element in set. Returns true on
success. If the iterator is already pointing on smallest element returns false.} \\\hline\hline
\verb!property Data:T! & $O(1)$ \\\hline
\multicolumn{2}{|m{15cm}|}{Property, which allows reading of the element.} \\\hline
\end{longtable}